support Contact Support | system status System Status
Page Contents

    Chromecast Plugin for Brightcove Player

    In this topic, you will learn how to cast your videos to a Chromecast-connected TV, using the Chromecast plugin (2.x) for Brightcove Player.

    Overview

    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 for Brightcove Player enables the player to cast video from your desktop or Android Chrome browser 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. Load the Chromecast Plugin for Brightcove Player (detailed 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 application: 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 application: 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.

    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

    Devices

    The following devices are supported:

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

    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 Brightcove 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.

    Using the plugin

    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.

      Add a Plugin button
      Add a Plugin button
    5. Expand the Brightcove Plugin dropdown and select Chromecast Receiver.

      chromcast-receiver
      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.

      Plugin added
      Plugin added
    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:

      Cast button

    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.

      Add a Plugin button
      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/2/videojs-chromecast-receiver.css"],
            "scripts": ["https://players.brightcove.net/videojs-chromecast-receiver/2/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.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.

    • options.splashScreen
      Type: string
      Default: ''

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

    • 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!
    • 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
    • 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).

    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 changelog here.


    Page last updated on 13 Oct 2020