search

silvermine / videojs-chromecast

MIT License
148 stars 75 forks source link

readme

Silvermine VideoJS Chromecast Plugin

Build Status Coverage Status Dependency Status Dev Dependency Status

What is it?

A plugin for videojs versions 6+ that adds a button to the control bar which will cast videos to a Chromecast.

How do I use it?

The @silvermine/videojs-chromecast plugin includes 3 types of assets: JavaScript, CSS, and images.

You can either build the plugin locally and use the assets that are output from the build process directly, or you can install the plugin as an NPM module, include the JavaScript and SCSS source in your project using a Common-JS module loader and SASS build process, and copy the images from the image source folder to your project.

Note that regardless of whether you are using this plugin via the pre-built JS or as a module, the Chromecast framework will need to be included after the plugin. For example:

<script src="https://unpkg.com/video.js@6.1.0/dist/video.js"></script>
<script src="https://github.com/silvermine/videojs-chromecast/raw/master/dist/silvermine-videojs-chromecast.min.js"></script>
<script type="text/javascript" src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Building the plugin locally

  1. Either clone this repository or install the @silvermine/videojs-chromecast module using npm install @silvermine/videojs-chromecast.
  2. Ensure that @silvermine/videojs-chromecast's devDependencies are installed by running npm install from within the videojs-chromecast folder.
  3. Run grunt build to build and copy the JavaScript, CSS and image files to the videojs-chromecast/dist folder.
  4. Copy the plugin's files from the dist folder into your project as needed.
  5. Ensure that the images in the dist/images folder are accessible at ./images/, relative to where the plugin's CSS is located. If, for example, your CSS is located at https://example.com/plugins/silvermine-videojs-chromecast.css, then the plugin's images should be located at https://example.com/plugins/images/.
  6. Follow the steps in the "Configuration" section below.

Note: when adding the plugin's JavaScript to your web page, include the silvermine-videojs-chromecast.min.js JavaScript file in your HTML after loading Video.js. The plugin's built JavaScript file expects there to be a reference to Video.js at window.videojs and will throw an error if it does not exist.

Initialization options

Providing initialization options via require()

If requiring this plugin via NPM, any desired initialization options can be supplied to the constructor function exported by the module. For example:

require('@silvermine/videojs-chromecast')(videojs, { preloadWebComponents: true });

Providing initialization options via <script>

If using the prebuilt JS, the initialization options can be provided via window.SILVERMINE_VIDEOJS_CHROMECAST_CONFIG. Note that these options need to be set before the <script> tag to include the plugin.

<script>
   window.SILVERMINE_VIDEOJS_CHROMECAST_CONFIG = {
      preloadWebComponents: true,
   };
</script>
<script src="https://github.com/silvermine/videojs-chromecast/raw/master/path/to/silvermine-videojs-chromecast.js"></script>

Configuration

Once the plugin has been loaded and registered, configure it and add it to your Video.js player using Video.js' plugin configuration option (see the section under the heading "Setting up a Plugin" on Video.js' plugin documentation page.

Important: In addition to defining plugin configuration, you are required to define the player's techOrder option, setting 'chromecast' as the first Tech in the list. Below is an example of the minimum required configuration for the Chromecast plugin to function:

var options;

options = {
   controls: true,
   techOrder: [ 'chromecast', 'html5' ], // You may have more Tech, such as Flash or HLS
   plugins: {
      chromecast: {}
   }
};

videojs(document.getElementById('myVideoElement'), options);

Please note that even if you choose not to use any of the configuration options, you must either provide a chromecast entry in the plugins option for Video.js to initialize the plugin for you:

options = {
   plugins: {
      chromecast: {}
   }
};

or you must initialize the plugin manually:

var player = videojs(document.getElementById('myVideoElement'));

player.chromecast(); // initializes the Chromecast plugin

Configuration options

Plugin configuration
Chromecast Tech configuration

Here is an example configuration object that makes full use of all required and optional configuration:

var titles, subtitles, customData, options;

titles = {
   'https://example.com/videos/video-1.mp4': 'Example Title',
   'https://example.com/videos/video-2.mp4': 'Example Title2',
};

subtitles = {
   'https://example.com/videos/video-1.mp4': 'Subtitle',
   'https://example.com/videos/video-2.mp4': 'Subtitle2',
};

customData = {
   'https://example.com/videos/video-1.mp4': { 'customColor': '#0099ee' },
   'https://example.com/videos/video-2.mp4': { 'customColor': '#000080' },
};

options = {
   // Must specify the 'chromecast' Tech first
   techOrder: [ 'chromecast', 'html5' ], // Required
   // Configuration for the Chromecast Tech
   chromecast: {
      requestTitleFn: function(source) { // Not required
         return titles[source.url];
      },
      requestSubtitleFn: function(source) { // Not required
         return subtitles[source.url];
      },
      requestCustomDataFn: function(source) { // Not required
         return customData[source.url];
      },
      modifyLoadRequestFn: function (loadRequest) { // HLS support
         loadRequest.media.hlsSegmentFormat = 'fmp4';
         loadRequest.media.hlsVideoSegmentFormat = 'fmp4';
         return loadRequest;
      }
   },
   plugins: {
      chromecast: {
         receiverAppID: '1234' // Not required
         addButtonToControlBar: false, // Defaults to true
      },
   }
};
Localization

The ChromecastButton component has two translated strings: "Open Chromecast menu" and "Cast".

To localize the Chromecast button strings, follow the steps in the Video.js Languages tutorial to add "Open Chromecast menu" and "Cast" keys to the map of translation strings.

Using the NPM module

If you are using a module loader such as Browserify or Webpack, first install @silvermine/videojs-chromecast using npm install. Then, use require('@silvermine/videojs-chromecast') to require @silvermine/videojs-chromecast into your project's source code. require('@silvermine/videojs-chromecast') returns a function that you can use to register the plugin with Video.js by passing in a reference to videojs:

var videojs = require('video.js');

// Initialize the Chromecast plugin
require('@silvermine/videojs-chromecast')(videojs);

Then, follow the steps in the "Configuration" section above.

This plugin's source code uses ES6+ syntax and keywords, such as class and static. If you need to support browsers that do not support newer JavaScript syntax, you will need to use a tool like Babel to transpile and polyfill your code.

Alternatively, you can require('@silvermine/videojs-chromecast/dist/silvermine-videojs-chromecast.js') to use a JavaScript file that has already been polyfilled/transpiled down to ES5 compatibility.

Using the CSS and images

If you are using SCSS in your project, you can simply reference the plugin's main SCSS file in your project's SCSS:

@import "path/to/node_modules/@silvermine/videojs-chromecast/src/scss/videojs-chromecast";

Optionally, you can override the SCSS variables that contain the paths to the icon image files:

Images

The plugin's images are located at videojs-chromecast/src/images. If you have not overridden the icon image path variables in the SCSS, then copy the images from the src/images folder to a folder that is accessible at ./images/, relative to where the plugin's CSS is located. If, for example, your CSS is located at https://example.com/plugins/silvermine-videojs-chromecast.css, then the plugin's images should be located at https://example.com/plugins/images/.

In addition, the ic_cast_white_24dp.png icon image that is used as the default icon for all four button states ("default", "default + hover", "casting", "casting + hover"), the images folder contains grey, black, and blue versions of the icons.

Events

How do I contribute?

We genuinely appreciate external contributions. See our extensive documentation on how to contribute.

License

This software is released under the MIT license. See the license file for more details.