Chromecast Plugin for Brightcove Player

Introduction

Google Chromecast is a device that you plug into your TV's HDMI port. Using your smartphone or computer as a remote control, you can use Chromecast to access video content. The Chromecast Plugin enables a player to cast video from your desktop or Android Chrome browser using Brightcove Player to the Chromecast device.

The plugin supports all Video Cloud videos or external streams using HLS or DASH, including DRM-encrypted streams using Widevine. Advertising is supported through Video Cloud server-side ad insertion (SSAI). Client-side ads and playlists are not supported.

To use the plugin follow these steps:

1. Include the Chromecast Plugin for Brightcove Player (see Implementation section below).
2. Be sure the Chromecast device is on the same network as your device that will play the video.
3. Start playing the video.
4. Click the cast button and select your Chromecast device.

Chromecast app components

The software behind Chromecast is comprised of the following components:

• Sender app: This is any application that can initiate a cast session and communicate with a receiver. The sender application can be thought of as the "client side" portion of the Chromecast ecosystem.

  The Chromecast Plugin for Brightcove Player enables the sender app in Brightcove Player. You will learn about it in this topic.

• Receiver app: This is a custom web application that is hosted on the public internet and runs on a Chromecast device. It handles communication between the sender app and the receiver device. It can be thought of as a single page HTML app with CSS and JavaScript assets.

  By default, the Chromecast Plugin uses the Brightcove Cast Receiver app, which is hosted on our CDN. The receiver app is a web application that is loaded onto the Chromecast during a cast session.

Supported Chromecast devices

The following devices are supported:

• Chromecast (3rd Generation)
• Chromecast Ultra
• Chromecast with Google TV

How it Works

The current implementation (plugin/receiver version 2.x) uses the CAF (Cast Application Framework) API.

When the Chromecast receiver plugin is added, the player will display a cast button in the player UI when there is an available Chromecast on the local network.

When this button is clicked or tapped, a cast session is initiated with the current video that is loaded in the player. Here's how it works:

1. The plugin sends a set of parameters to the receiver.
2. The receiver mirrors the sending player by loading it from Brightcove's CDN.
3. Once loaded, the receiver-side player loads the video ID from the Playback API that was sent when the cast session began.
4. Then, the receiver-side player begins playback at the playhead position of the sending player.

This process is identical for non-Video Cloud sources except there is no Playback API request.

Analytics

Currently, from an analytics perspective, the cast session is treated as an entirely new playback session.

From a UX perspective, the viewer will see their stream pause on the sender device and resume on the receiver.

From a data perspective, because our metrics are anonymized by default, it is logged as a new viewer starting a new stream on a separate device. This is what actually happens.

Requirements

The following requirements are needed for the Chromecast plugin:

• Brightcove Player v6.45.0 or newer
• Brightcove Chromecast plugin v2.0.0 or newer

Implementation

The Chromecast Plugin for Brightcove Player is used like all other Brightcove Player plugins, that is you must load the plugin into the player.

Using Studio

The following steps detail using Studio to load the plugin.

1. Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
2. Select the link for the player to open the player's properties.
3. In the left navigation menu, select Plugins.

4. Next, select the Add a Plugin button, and then select Brightcove Plugin.

   

5. Expand the Brightcove Plugin dropdown and select Chromecast Receiver.

   

6. Optional: Enter the configuration options in the Options(JSON) text box. An example for the default player in the 1752604059001 account is shown. You, of course, need to enter information for your player.

    {
       "playerUrl" : "https://players.brightcove.net/1507807800001/default_default/index.min.js"
    }

   See below for details on the options.

7. Select the Save button. You will now see the Chromecast Receiver plugin added to the list of plugins for your player.

   

8. To publish the player, select Publish & Embed > Publish Changes.
9. To close the open dialog, select Close.

10. Return to the MEDIA and publish your video or playlist using the player you just updated for Chromecast.

    Once the plugin is loaded, the video has started playing, and an available Chromecast device is in range, the cast button will appear in the player as shown here in this screenshot of a player:

    

Configuring manually

Follow these steps to add the plugin using the JSON editor:

1. Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
2. Select the link for the player to open the player's properties.

3. In the left navigation menu, select JSON Editor.

   

4. Add an object to the plugins array

   Your code should look similar to this:

    { 
     "compatibility": true,
     "video_cloud": {
       "policy_key": "your policy key" },
     "player": {
       "template": {
         "name": "single-video-template", 
         "version": "6.45.4"
       }
     },
     "studio_configuration": {
       "player": {
         "responsive": true,
         "height": 540,
         "width": 960,
         "units": "px"
       }
     },
     "plugins": [ {
       "name": "chromecastReceiver", 
       "options": {},
       "stylesheets": ["https://players.brightcove.net/videojs-chromecast-receiver/3/videojs-chromecast-receiver.css"], 
       "scripts": ["https://players.brightcove.net/videojs-chromecast-receiver/3/videojs-chromecast-receiver.js"] }
     ]
    }

   See below for details on the options.

Configuration options

No matter which method you choose to setup the Chromecast Plugin for Brightcove Player, you can pass options to modify plugin behavior. While setting these options is not necessary, additional customization is possible for advanced users.

To pass options in code, you would use something similar to the following:

 videojs.getPlayer('myPlayerID').ready(function() { 
    var myPlayer = this;
    options = {};
    options.playerUrl = '//players.brightcove.net/1752604059001/default_default/index.min.js'; myPlayer.chromecastReceiver(options);
 });

Advice

If your web player(s) contains a large number of plugins or custom scripts, you should consider creating a lightweight player specifically for Chromecast playback.

Since the web player and its playback engine are somewhat resource intensive, running in a resource constrained environment (such as a Chromecast) with additional heavy scripts can negatively impact the user experience!

Options

The Chromecast plugin supports the following options:

• options.appName

  Type: string
  Default: 'Brightcove Chromecast CAF v2.0'

  Override the default application name with your own custom name.

• options.playerUrl

  Type: string
  Default: ''

  By default, the sender-side player is mirrored on the receiver. You can use this option to provide a custom receiver-side Brightcove Player URL.

  Since this is a Brightcove player that is loaded on the receiver, you can customize, style and debug the player outside of Chromecast.

  Note that when using the playerUrl option, the players used as a sender and a receiver are different. If you are using domain restricted players, you need to use whitelisting. The whitelisting should be done for the sender player, NOT the player used as receiver (which is the player specified in this option).

• options.splashScreen

  Type: string
  Default: ''

  The splash screen that should be shown before a video and when videos are switching.

• options.ssaiDynamicMacros

  Type: Array
  Default: undefined

  This option allows users to pass a set of dynamic ad macros into the Chromecast receiver from the web player.

  Each element of this array should be a string that matches the name of a global variable (a property of window). This value will then be passed to the player on the Chromecast and used when resolving ad macros in a VOD SSAI URL.

  For example, let's say your SSAI implementation relies on the exampleMacro being available globally. You would add the following to your Chromecast plugin options:

  "ssaiDynamicMacros": ["exampleMacro"]

  When the sender player casts, will pass the value of window.exampleMacro across to the receiver, where it will be picked up automatically by the built-in SSAI ad macro resolution.

Uncommon options

The following options are not generally used.

• options.authRequest

  Type: string or object or function
  Default: {}
  
  

  You can use this option if you need the Chromecast to perform a request to get authorization to play content before a video is requested.

  You can also use this to get cookies, but your server will have to be set up to allow players.brightcove.net the ability to have cross domain cookies set if you are hosting your own content.

  String usage

  When authRequest is a string, an empty GET request will be made to that URL.

  Object usage

  When authRequest is an object, it can be used to specify certain request payload properties:

  Property	Type	Required	Default	Description
  url	string	Yes	''	The URL to request
  method	string	No	GET	The HTTP method to use
  body	string	No	''	The request body
  headers	object	No	{}	An object describing HTTP headers where the keys are the header name and the properties are the header values
  withCredentials	boolean	No	false	An object describing HTTP headers where the keys are the header name and the properties are the header values
  timeout	number	No	15000	How many milliseconds to wait before giving up on the auth request

  Function usage

  When authRequest is a function, it should return either a string or an object per those usages.

Limitations and known issues

• HEVC/4K content is only supported on Chromecast Ultra devices and newer Chromecast with Google TV devices.
• Client-side advertising is not currently supported, but SSAI is supported!
• Playback rate adjustment is not currently supported with this plugin.
• We have seen issues with seeking on the sender after a caption track has been selected and is displayed in the receiver.
• On Chromecast with Google TV devices, we have seen issues with the UI as well as playback issues when using captions.
• Google has stopped supporting non-secure origins (HTTP) with Chromecast, hence the plugin will not work in non-secure contexts. In these cases, the player's Chromecast button will not appear.
• Since the Chromecast Plugin relies on the browser's support for casting, it is only supported in the following OS/browser combinations:
  • Desktop/Chrome
  • Android/Chrome
  The Chromecast Plugin is not supported on Safari on desktop/iOS or Chrome on iOS. For these cases, the Chromecast icon will not be displayed.
• Google does not support multiple instances of the Chromecast sender button on a single page. Possible workarounds would be to embed the Brightcove Player using the Standard (iframe) player implementation, or to dynamically instantiate and destroy players as needed. See the document Brightcove Player Sample: Loading the Player Dynamically for information on the latter possibility.
• This plugin does not cast to Google Nest Hub. The plugin only supports actual Chromecast devices (i.e. Chromecast and Chromecast Ultra).
• Android WebView does not support casting with Chromecast. For more information see Android's Issue Tracker.

Changes from v1.x to v2.x

Besides internal changes, like using the CAF API instead of the v2 Chromecast API, the following interfaces have changed:

• options.css and options.js are no longer supported.
• customData.analyticsParams was added
• customData.catalogData was renamed customData.catalogParams to improve consistency with other usages
• customData.policyKey was replaced by customData.catalogParams.policyKey
• customData.keySystems was added

Changelog

See the Chromecast Receiver and Plugin Release.

For historical release notes, see the changelog here.

Limitations

• Currently, the Chromecast plugin does not support remote control.