Introduction to Chromecast Integration

This topic describes terminology, use cases, architecture, and components for Ooyala's integration with Chromecast.

Use Cases

A Cast session can start with either of the following use cases, both of which are supported in Ooyala's Chromecast integration:

Cast & Play

  1. The user taps the Cast button. This button invokes a menu to connect, control and disconnect from cast receivers.
  2. The user selects the Receiver device from the Cast menu.
  3. The user selects content to play.

    Content starts to play on the receiver screen.

Play & Cast

  1. The user selects content to play. Content starts playing on the sender device.
  2. The user taps the Cast button.
  3. The user selects the receiver device from the Cast menu.

    Content starts to play on the receiver screen and is paused on the sender device.

When there are multiple senders, the last sender always gets the controls and starts to cast a new app from scratch. The old video is disconnected if the new sender plays a different video.

Run-time Workflow

The following illustration shows a high-level view of the different components of a Chromecast integration. Each of these components is defined in detail in subsequent parts of this documentation.
Step Component Action
1 Sender app on the mobile device Requests App ID
2 Google Maps App ID to server URL
3 TV with Chromecast Requests receiver
4 Receiver app on web server Sends receiver web page
5 TV with Chromecast Displays receiver on TV
6 TV with Chromecast Connects receiver to sender

Chromecast Sender Application

The sender application is the Cast component built into Ooyala’s Android or iOS SDK that provides users with playback controls like play, pause, stop, and the ability to select which device content is streamed. Under the hood, these sender apps can detect receiver devices on the same local network, establish a secure channel, and exchange messages.

The sender application is the application of the ‘primary’ viewing device and is responsible for locating nearby Chromecast devices. The sender application framework:

  • Integrates with Google’s Cast SDK (part of the Google Play Services platform) for iOS, and Google's Cast Companion Library for Android.
  • Integrates with Ooyala iOS and/or Android SDKs for mobile-based applications.
  • Communicates the Ooyala embed_code and parameters (initialTime, embedToken, and so on) to the Receiver application.
  • Communicates Ooyala player controls like Load, Play, Pause, Seek, Stop, Set Volume, and Get Status to the Receiver application.
  • Receives Ooyala player information, playhead time change, status change, and errors from the Receiver Application.

The sender application consists of the following components.

  • Cast Button: The button that invokes a menu to connect, control and disconnect from cast receivers.
  • Cast Menu: The menu that pops up when the cast button is clicked. The Cast menu lets users connect, control and disconnect from Cast receivers.
  • User Controls: The end user can use user controls such as play, pause, seek, etc. to control content that is casting/playing on a Cast receiver.
Note: While Ooyala does not support Sender applications in Player V4 Web, we do support casting on the browser using the default Cast plugin on Chrome. This plugin does not interact with the Ooyala player. This will mirror the content on the Chrome tab.

Chromecast Receiver Application

The receiver application is an HTML5/JavaScript application that runs on the Chromecast device. The receiver application performs the following functions:
  • Provides a user interface to display the app's content on the TV screen.
  • Handles messages from the sender application to control content on the receiver device.
  • Handles custom messages from the sender application that are application-specific.
The Receiver application framework:
  • Integrates with Google's Receiver SDK, which builds and enables the receiver application page.
  • Uses Ooyala Player V4.
  • Establishes communication with the Sender application via Google Custom Channel.
  • Requires the player_branding_id as part of the setup process.

Ooyala helps you get started by providing a sample receiver application. The receiver application contains code with playback capabilities and styling abstracted from the Receiver app. This receiver allows for quick and easy implementation for testing purposes.

Note: See Enabling Chromecast in the Ooyala HTML5 Player for information on how to enable Chromecast in the Ooyala HTML5 Player.

Mini Controller

Controls should appear when the user navigates away from the current content page or expanded controls. These controls provide instant access and a visible reminder for the currently casting video.

Communication Protocol

The sample receiver and sender applications use Google's media namespace to send play, pause, seek, start, and other events between the sender and receiver. Ooyala uses Google's cast media commands, which create media status objects in the receiver code. The receiver publishes to the Ooyala message bus to set closed captions and send additional player state information to the sender. You can use your own sender application with the Ooyala receiver application as long as you set up the communication protocol to handle events.

The namespace used in the sender and receiver Ooyala Chromecast Integration applications is x-urn:cast:ooyala.

Sender → Receiver

Upon connecting to the receiver, the sender creates a media session that loads the required video via the MediaInfo object with the video embed code. When the video is loaded, the sender gets a media object from the receiver which is used to communicate with the receiver. The sender also gets messages through the Ooyala namespace message bus from the receiver to control closed captions and update the state of its control widgets.

The sender receives media status updates implicitly to know whether or not the media session is alive, the state of the player, etc. Sender commands to control the player have callbacks that can be used for notifications about changes in media status.

Receiver → Sender

All events are processed through the MediaManager object.

Upgrading a Previous Ooyala Chromecast Implementation

If you implemented Chromecast integration using the previous Ooyala version (see Chromecast and Ooyala (Deprecated)), you can update to the latest version by completing the following steps:
  1. Read the developer documentation (this section).
  2. Purchase a Chromecast device to test.
  3. Facilitate your own hosting infrastructure for receiver applications (you must set up CORS enablement on the CDN you use for content serving).
  4. Register your receiver HTML with Google Cast Registration.
    • For iOS, view the sample Chromecast Sender iOS App.
    • For Android, view the sample Chromecast Sender Android App
These steps are also described in the file at