Skip to content

Commit 98edc9e

Browse files
anthonylavadoanthonylavado
authored
Merge pull request #57 from miloproductionsinc/master
Redo of 1.0.0 refactor pull request
2 parents 3ff77a5 + a668f07 commit 98edc9e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+40285
-4565
lines changed

‎.eslintrc.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
root: true
2+
extends: semistandard
3+
rules:
4+
indent:
5+
- error
6+
- 4
7+
camelcase: off
8+
padded-blocks: off
9+
operator-linebreak: off
10+
no-throw-literal: off

‎.github/pull_request_template.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!--
2+
Please make sure the checklist boxes are all checked before submitting the PR.
3+
4+
Thanks!
5+
-->
6+
7+
### Platforms affected
8+
9+
10+
11+
### Motivation and Context
12+
<!-- Why is this change required? What problem does it solve? -->
13+
<!-- If it fixes an open issue, please link to the issue here. -->
14+
15+
16+
17+
### Description
18+
19+
20+
21+
### Testing
22+
<!-- Please describe in detail how you tested your changes. -->
23+
24+
25+
26+
### Checklist
27+
<!-- Place and x inside the [ ] to indicate completion -->
28+
29+
- [ ] I've updated the documentation as necessary
30+
- [ ] If this Pull Request resolves an issue, I linked to the issue in the text above (and used the correct [keyword to close issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/))
31+
- [ ] I've run `npm test` and no errors were found (run `npm style` to auto-fix errors it can)
32+
- [ ] I've run the tests (See Readme)
33+
- [ ] I added automated test coverage as appropriate for this change (See Readme Contributing section)

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,3 +136,5 @@ Temporary Items
136136

137137
# Created by .ignore support plugin (hsz.mobi)
138138
node_modules
139+
140+
package-lock.json

‎README.md‎

Lines changed: 187 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,200 @@
11
<h1 align="center">cordova-plugin-chromecast</h1>
2-
<h3 align="center">Chromecast in Cordova</h3>
2+
<h3 align="center">Control Chromecast from your Cordova app</h3>
33

4-
## Installation
5-
Add the plugin with the command below in your cordova project directory.
4+
# Installation
65

76
```
87
cordova plugin add https://github.com/jellyfin/cordova-plugin-chromecast.git
98
```
109

11-
If you have NodeJS installed, the dependencies should be automatically copied. Otrherwise, you will need to import the following projects as Library Projects in order for this plugin to work.
10+
### Additional iOS Installation Instructions
11+
To **distribute** an iOS app with this plugin you must add usage descriptions to your project's `config.xml`.
12+
These strings will be used when asking the user for permission to use the microphone and bluetooth.
13+
```xml
14+
<!-- ios 6-13 (deprecated) -->
15+
<platform name="ios">
16+
<config-file parent="NSBluetoothPeripheralUsageDescription" target="*-Info.plist">
17+
<string>Bluetooth is required to scan for nearby Chromecast devices with guest mode enabled.</string>
18+
</config-file>
19+
<!-- ios 13+ -->
20+
<config-file parent="NSBluetoothAlwaysUsageDescription" target="*-Info.plist">
21+
<string>Bluetooth is required to scan for nearby Chromecast devices with guest mode enabled.</string>
22+
</config-file>
23+
<config-file parent="NSMicrophoneUsageDescription" target="*-Info.plist">
24+
<string>The microphone is required to pair with nearby Chromecast devices with guest mode enabled.</string>
25+
</config-file>
26+
</platform>
27+
```
28+
29+
# Supports
30+
31+
**Android** 4.4+ (7.x highest confirmed) (may support lower, untested)
32+
**iOS** 9.0+ (13.2.1 highest confirmed)
33+
34+
## Quirks
35+
* Android 4.4 (maybe 5.x and 6.x) are not able automatically rejoin/resume a chromecast session after an app restart.
36+
37+
# Usage
38+
39+
This project attempts to implement the [official Google Cast API for Chrome](https://developers.google.com/cast/docs/reference/chrome#chrome.cast) within the Cordova webview.
40+
This means that you should be able to write almost identical code in cordova as you would if you were developing for desktop Chrome.
41+
42+
We have not implemented every function in the [API](https://developers.google.com/cast/docs/reference/chrome#chrome.cast) but most of the core functions are there. If you find a function is missing we welcome [pull requests](#contributing)! Alternatively, you can file an [issue](https://github.com/jellyfin/cordova-plugin-chromecast/issues), please include a code sample of the expected functionality if possible!
43+
44+
The most significant usage difference between the [cast API](https://developers.google.com/cast/docs/reference/chrome#chrome.cast) and this plugin is the initialization.
45+
46+
In **Chrome desktop** you would do:
47+
```js
48+
window['__onGCastApiAvailable'] = function(isAvailable, err) {
49+
if (isAvailable) {
50+
// start using the api!
51+
}
52+
};
53+
```
54+
55+
But in **cordova-plugin-chromecast** you do:
56+
```js
57+
document.addEventListener("deviceready", function () {
58+
// start using the api!
59+
});
60+
```
61+
62+
63+
### Example
64+
Here is a simple [example](doc/example.js) that loads a video, pauses it, and ends the session.
65+
66+
## API
67+
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)
68+
69+
[chrome.cast.initialize](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.initialize)
70+
[chrome.cast.requestSession](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.requestSession)
71+
[chrome.cast.setCustomReceivers](https://developers.google.com/cast/docs/reference/chrome/chrome.cast#.setCustomReceivers)
72+
[chrome.cast.Session.setReceiverVolumeLevel](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#setReceiverVolumeLevel)
73+
[chrome.cast.Session.setReceiverMuted](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#setReceiverMuted)
74+
[chrome.cast.Session.stop](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#stop)
75+
[chrome.cast.Session.leave](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#leave)
76+
[chrome.cast.Session.sendMessage](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#sendMessage)
77+
[chrome.cast.Session.loadMedia](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#loadMedia)
78+
[chrome.cast.Session.queueLoad](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#queueLoad)
79+
[chrome.cast.Session.addUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addUpdateListener)
80+
[chrome.cast.Session.removeUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeUpdateListener)
81+
[chrome.cast.Session.addMessageListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addMessageListener)
82+
[chrome.cast.Session.removeMessageListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeMessageListener)
83+
[chrome.cast.Session.addMediaListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#addMediaListener)
84+
[chrome.cast.Session.removeMediaListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.Session#removeMediaListener)
85+
[chrome.cast.media.Media.play](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#play)
86+
[chrome.cast.media.Media.pause](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#pause)
87+
[chrome.cast.media.Media.seek](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#seek)
88+
[chrome.cast.media.Media.stop](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#stop)
89+
[chrome.cast.media.Media.setVolume](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#setVolume)
90+
[chrome.cast.media.Media.supportsCommand](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#supportsCommand)
91+
[chrome.cast.media.Media.getEstimatedTime](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#getEstimatedTime)
92+
[chrome.cast.media.Media.editTracksInfo](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#editTracksInfo)
93+
[chrome.cast.media.Media.queueJumpToItem](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#queueJumpToItem)
94+
[chrome.cast.media.Media.addUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#addUpdateListener)
95+
[chrome.cast.media.Media.removeUpdateListener](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.Media.html#removeUpdateListener)
96+
97+
98+
### Specific to this plugin
99+
We have added some additional methods unique to this plugin.
100+
They can all be found in the `chrome.cast.cordova` object.
101+
102+
To make your own **custom route selector** use this:
103+
```js
104+
// This will begin an active scan for routes
105+
chrome.cast.cordova.scanForRoutes(function (routes) {
106+
// Here is where you should update your route selector view with the current routes
107+
// This will called each time the routes change
108+
// routes is an array of "Route" objects (see below)
109+
}, function (err) {
110+
// Will return with err.code === chrome.cast.ErrorCode.CANCEL when the scan has been ended
111+
});
112+
113+
// When the user selects a route
114+
// stop the scan to save battery power
115+
chrome.cast.cordova.stopScan();
116+
117+
// and use the selected route.id to join the route
118+
chrome.cast.cordova.selectRoute(route.id, function (session) {
119+
// Save the session for your use
120+
}, function (err) {
121+
// Failed to connect to the route
122+
});
123+
124+
```
125+
126+
**Route** object
127+
```text
128+
id {string} - Route id
129+
name {string} - User friendly route name
130+
isCastGroup {boolean} - Is the route a cast group?
131+
isNearbyDevice {boolean} - Is it a device only accessible via guest mode?
132+
(aka. probably not on the same network, but is nearby and allows guests)
133+
```
134+
135+
136+
# Plugin Development
137+
138+
## Setup
139+
140+
Follow these direction to set up for plugin development:
141+
142+
* You will need an existing cordova project or [create a new cordova project](https://cordova.apache.org/#getstarted).
143+
* Add the chromecast and chromecast tests plugins:
144+
* `cordova plugin add --link <path to plugin>`
145+
* `cordova plugin add --link <path to plugin>/tests`
146+
* This --link** option may require **admin permission**
147+
148+
#### **About the `--link` flag
149+
The `--link` flag allows you to modify the native code (java/swift/obj-c) directly in the relative platform folder if desired.
150+
* This means you can work directly from Android Studio/Xcode!
151+
* Note: Be careful about adding and deleting files. These changes will be exclusive to the platform folder and will not be transferred back to your plugin folder.
152+
* Note: The link only works for native files. Other files such as js/css/html/etc must **not** be modified in the platform folder, these changes will be lost.
153+
* To update the js/css/html/etc files you must run:
154+
* `cordova plugin remove <plugin-name>`
155+
* With **admin permission**: `cordova plugin add --link <relative path to the plugin's root dir>`
156+
157+
## Testing
158+
159+
### Code Format
160+
161+
Run `npm test` to ensure your code fits the styling. It will also find some errors.
162+
163+
* If errors are found, you can try running `npm run style`, this will attempt to automatically fix the errors.
164+
165+
### Tests Mobile
166+
Requirements:
167+
* A chromecast device
168+
169+
How to run the tests:
170+
* Follow [setup](#setup)
171+
* Change `config.xml`'s content tag to `<content src="plugins/cordova-plugin-chromecast-tests/www/html/tests.html" />`
172+
173+
Auto tests:
174+
* Run the app, select auto tests, let it do its thing
12175

13-
- `adt-bundle\sdk\extras\google\google_play_services\libproject\google-play-services_lib`
14-
- `adt-bundle\sdk\extras\android\support\v7\appcompat`
15-
- `adt-bundle\sdk\extras\android\support\v7\mediarouter`
176+
Manual tests:
177+
* This tests tricky features of chromecast such as:
178+
* Resume casting session after page reload / app restart
179+
* Interaction between 2 devices connected to the same session
180+
* You will need to be able to run the tests from 2 different devices (preferred) or between a device and chrome desktop browser
181+
* To use the chrome desktop browser see [Tests Chrome](#tests-chrome)
16182

17-
## Usage
183+
[Why we chose a non-standard test framework](https://github.com/jellyfin/cordova-plugin-chromecast/issues/50)
18184

19-
This project attempts to implement the official Google Cast SDK for Chrome within Cordova. We've made a lot of progress in making this possible, so check out the [offical documentation](https://developers.google.com/cast/docs/chrome_sender) for examples.
185+
### Tests Chrome
20186

21-
When you call `chrome.cast.requestSession()` a popup will be displayed to select a Chromecast. If you would prefer to make your own interface you can call `chrome.cast.getRouteListElement()` which will return a `<ul>` tag that contains the Chromecasts in a list. All you have to do is style that bad boy and you're off to the races!
187+
The auto tests also run in desktop chrome.
188+
They use the google provided cast_sender.js.
189+
These are particularly useful for ensuring we are following the [official Google Cast API for Chrome](https://developers.google.com/cast/docs/reference/chrome#chrome.cast) correctly.
190+
To run the tests:
191+
* run: `npm run host-chrome-tests [port default=8432]`
192+
* Navigate to: `http://localhost:8432/chrome/tests_chrome.html`
22193

23-
## Status
194+
## Contributing
24195

25-
The project is now pretty much feature complete - the only things that will possibly break are missing parameters. We haven't done any checking for optional paramaters. When using the plugin make sure your constructors and function calls have every parameter you can find in the method declarations.
196+
* Write a test for your contribution if applicable (for a bug fix, new feature, etc)
197+
* You should test on [Chrome](#tests-chrome) first to ensure you are following [Google Cast API](https://developers.google.com/cast/docs/reference/chrome#chrome.cast) behavior correctly
198+
* If the test does not pass on [Chrome](#tests-chrome) we should not be implementing it either (unless it is a `chrome.cast.cordova` function)
199+
* Make sure all tests pass ([Code Format](#code-format), [Tests Mobile](#tests-mobile), and [Tests Chrome](#tests-chrome))
200+
* Update documentation as necessary

0 commit comments

Comments
 (0)