Chromecast with the Native SDKs

In this topic, you will learn how to cast videos to a Chromecast-connected TV from your apps built with the Brightcove Native SDKs.

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 mobile device app using the Brightcove Native SDKs 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). Playlists are supported with the Brightcove receiver on Chromecast with the web player. Client-side ads are not supported.

To use the plugin follow these steps:

  1. Include the Chromecast Plugin for the Native SDK for Android and/or iOS (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 enables the sender app in the Native SDKs. 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.

Implementation

For implementation details, see the following:

Custom Data

The customData interface provides a method by which senders can pass arbitrary data into a custom Chromecast receiver, such as Brightcove's receiver app.

For the Brightcove Player (web) sender, customData is handled entirely by the plugin. There is nothing for integrators to do.

For all other senders, such as the the Native SDK for Android or iOS, customData must be constructed by the sender.

customData.accountId (required)

Type: string

When casting from a web player, this is automatic. All other senders (e.g. the Native SDKs) must explicitly set this.

customData.analyticsParams

Type: object

This property should be an object, which can be used to pass parameters to the analytics implementation on the receiver for beacons sent to the Data Collection API. It supports the following properties:

Property Type Description
analyticsParams.application string Allows setting a clear text application ID. This is useful for applications like Engage.
analyticsParams.user string Allows setting a clear text user ID for beacons sent to the Data Collection API. This is useful for features like Cross Device Resume (XDR).

customData.catalogParams

Type: object

This should be a Catalog Parameters Objects

All values passed to the Playback API on the receiver must come from this object.

customData.keySystems

Type: object

When providing media via a media info object, this can be used to provide DRM settings in a format identical to that returned by the Playback API:

keySystems: {
  'com.widevine.alpha': {
    url: 'https://url/to/widevine/license'
  }
}

customData.playerUrl

Type: string

This can be used to provide a custom player URL to load.

When casting from a web player, by default it will mirror the player on the sender. This behavior can be overridden by passing "playerUrl": "default" in options (see above). This is useful for testing.

When casting from native SDKs, it will fall back to the default player (which is available in the Players Prod account).

Limitations

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