From c75e396470740b966f20d8926ce53aa3dbd758da Mon Sep 17 00:00:00 2001 From: Lindsay-Needs-Sleep Date: Sun, 25 Oct 2020 19:14:29 -0600 Subject: [PATCH] [issue #72] Documentation changes: - add an iOS troubleshooting tip - remove documentation for unimplemented `setCustomReceivers` - reformat supported API section - Add link to tests for example usage --- README.md | 82 ++++++++++++++++++------------ src/android/ChromecastSession.java | 7 ++- tests/www/js/tests_auto.js | 3 +- www/chrome.cast.js | 10 ---- 4 files changed, 57 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 2214f35..1aec865 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,13 @@ cordova plugin add https://github.com/jellyfin/cordova-plugin-chromecast.git ``` +If you have trouble installing the pulgin or running the project for iOS, from `/platforms/ios/` try running: +```bash +sudo gem install cocoapods +pod repo update +pod install +``` + ### Additional iOS Installation Instructions To **distribute** an iOS app with this plugin you must add usage descriptions to your project's `config.xml`. These strings will be used when asking the user for permission to use the microphone and bluetooth. @@ -60,43 +67,53 @@ document.addEventListener("deviceready", function () { ``` -### Example +### Example Usage Here is a simple [example](doc/example.js) that loads a video, pauses it, and ends the session. +If you want more detailed code examples, please ctrl+f for the function of interest in [tests_auto.js](tests/www/js/tests_auto.js). +The other test files may contain code examples of interest as well: [[tests_manual_primary_1.js](tests/www/js/tests_manual_primary_1.js), [tests_manual_primary_2.js](tests/www/js/tests_manual_primary_2.js), [tests_manual_secondary.js](tests/www/js/tests_manual_secondary.js)] + ## API -Here are the support [Chromecast API]((https://developers.google.com/cast/docs/reference/chrome#chrome.cast)) methods. Any object types required by any of these methods are also supported. (eg. chrome.cast.ApiConfig) - -[chrome.cast.initialize](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.initialize) -[chrome.cast.requestSession](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.requestSession) -[chrome.cast.setCustomReceivers](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.setCustomReceivers) -[chrome.cast.Session.setReceiverVolumeLevel](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#setReceiverVolumeLevel) -[chrome.cast.Session.setReceiverMuted](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#setReceiverMuted) -[chrome.cast.Session.stop](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#stop) -[chrome.cast.Session.leave](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#leave) -[chrome.cast.Session.sendMessage](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#sendMessage) -[chrome.cast.Session.loadMedia](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#loadMedia) -[chrome.cast.Session.queueLoad](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#queueLoad) -[chrome.cast.Session.addUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addUpdateListener) -[chrome.cast.Session.removeUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeUpdateListener) -[chrome.cast.Session.addMessageListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addMessageListener) -[chrome.cast.Session.removeMessageListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeMessageListener) -[chrome.cast.Session.addMediaListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addMediaListener) -[chrome.cast.Session.removeMediaListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeMediaListener) -[chrome.cast.media.Media.play](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#play) -[chrome.cast.media.Media.pause](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#pause) -[chrome.cast.media.Media.seek](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#seek) -[chrome.cast.media.Media.stop](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#stop) -[chrome.cast.media.Media.setVolume](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#setVolume) -[chrome.cast.media.Media.supportsCommand](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#supportsCommand) -[chrome.cast.media.Media.getEstimatedTime](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#getEstimatedTime) -[chrome.cast.media.Media.editTracksInfo](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#editTracksInfo) -[chrome.cast.media.Media.queueJumpToItem](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#queueJumpToItem) -[chrome.cast.media.Media.addUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#addUpdateListener) -[chrome.cast.media.Media.removeUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#removeUpdateListener) +Here are the supported [Chromecast API]((https://developers.google.com/cast/docs/reference/chrome#chrome.cast)) methods. Any object types required by any of these methods are also supported. (eg. [chrome.cast.ApiConfig](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.ApiConfig)). You can search [chrome.cast.js](www/chrome.cast.js) to check if an API is supported. + +* [chrome.cast.initialize](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.initialize) +* [chrome.cast.requestSession](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.requestSession) + +[chrome.cast.Session](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session) +Most *Properties* Supported. +Supported *Methods*: +* [setReceiverVolumeLevel](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#setReceiverVolumeLevel) +* [setReceiverMuted](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#setReceiverMuted) +* [stop](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#stop) +* [leave](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#leave) +* [sendMessage](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#sendMessage) +* [loadMedia](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#loadMedia) +* [queueLoad](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#queueLoad) +* [addUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addUpdateListener) +* [removeUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeUpdateListener) +* [addMessageListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addMessageListener) +* [removeMessageListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeMessageListener) +* [addMediaListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addMediaListener) +* [removeMediaListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeMediaListener) + +[chrome.cast.media.Media](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media) +Most *Properties* Supported. +Supported *Methods*: +* [play](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#play) +* [pause](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#pause) +* [seek](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#seek) +* [stop](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#stop) +* [setVolume](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#setVolume) +* [supportsCommand](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#supportsCommand) +* [getEstimatedTime](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#getEstimatedTime) +* [editTracksInfo](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#editTracksInfo) +* [queueJumpToItem](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#queueJumpToItem) +* [addUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#addUpdateListener) +* [removeUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#removeUpdateListener) ### Specific to this plugin -We have added some additional methods unique to this plugin. +We have added some additional methods that are unique to this plugin (that *do not* exist in the chrome cast API). They can all be found in the `chrome.cast.cordova` object. To make your own **custom route selector** use this: @@ -179,7 +196,8 @@ Manual tests: * Interaction between 2 devices connected to the same session * You will need to be able to run the tests from 2 different devices (preferred) or between a device and chrome desktop browser * To use the chrome desktop browser see [Tests Chrome](#tests-chrome) - + * [What a successful manual run looks like](https://github.com/jellyfin/cordova-plugin-chromecast/wiki/img/manual-tests-success.jpg) + [Why we chose a non-standard test framework](https://github.com/jellyfin/cordova-plugin-chromecast/issues/50) ### Tests Chrome diff --git a/src/android/ChromecastSession.java b/src/android/ChromecastSession.java index cdefe04..5c7a0d5 100644 --- a/src/android/ChromecastSession.java +++ b/src/android/ChromecastSession.java @@ -42,7 +42,12 @@ public class ChromecastSession { private boolean requestingMedia = false; /** Handles and used to trigger queue updates. **/ private MediaQueueController mediaQueueCallback; - /** Stores a callback that should be called when the queue is loaded. **/ + /** + * Stores a callback that should be called when the queue is loaded. + * See https://github.com/jellyfin/cordova-plugin-chromecast/wiki/img/queueReloadCallback.jpg + * For how queueReloadCallback is used with multiple devices connected to the same session, and + * the primary device loads the media. + **/ private Runnable queueReloadCallback; /** Stores a callback that should be called when the queue status is updated. **/ private Runnable queueStatusUpdatedCallback; diff --git a/tests/www/js/tests_auto.js b/tests/www/js/tests_auto.js index 74ab8a0..7b9f6fb 100644 --- a/tests/www/js/tests_auto.js +++ b/tests/www/js/tests_auto.js @@ -73,7 +73,6 @@ assert.exists(chrome.cast.media); assert.exists(chrome.cast.initialize); assert.exists(chrome.cast.requestSession); - assert.exists(chrome.cast.setCustomReceivers); assert.exists(chrome.cast.Session); assert.exists(chrome.cast.media.PlayerState); assert.exists(chrome.cast.media.ResumeState); @@ -870,7 +869,7 @@ done(); }); }); - it('session.loadMedia should be able to load videos twice in a row and handle MovieMediaMetadata and TvShowMediaMetadata correctly, and first media should be invalidated', function (done) { + it.only('session.loadMedia should be able to load videos twice in a row and handle MovieMediaMetadata and TvShowMediaMetadata correctly, and first media should be invalidated', function (done) { var firstMedia; var mediaInfo = new chrome.cast.media.MediaInfo(videoUrl, 'video/mp4'); mediaInfo.metadata = new chrome.cast.media.MovieMediaMetadata(); diff --git a/www/chrome.cast.js b/www/chrome.cast.js index ec07f16..e0b5888 100644 --- a/www/chrome.cast.js +++ b/www/chrome.cast.js @@ -561,16 +561,6 @@ chrome.cast.requestSession = function (successCallback, errorCallback, opt_sessi }); }; -/** - * Sets custom receiver list - * @param {chrome.cast.Receiver[]} receivers The new list. Must not be null. - * @param {function} successCallback - * @param {function} errorCallback - */ -chrome.cast.setCustomReceivers = function (receivers, successCallback, errorCallback) { - // TODO: Implement -}; - /** * Describes the state of a currently running Cast application. Normally, these objects should not be created by the client. * @param {string} sessionId Uniquely identifies this instance of the receiver application.