Google Cast

Chrome Sender App Development

This overview describes how to build a Google Cast sender application for Chrome using the Google Cast SDK.

In this overview, sender application or Google Cast application refers to a web (HTML/JavaScript) app running inside a Chrome browser on a Mac/Windows/Linux/ChromeOS desktop/laptop device (the sender device); neither Chrome for Android, nor Chrome for iOS supports Cast applications (see Android Apps or iOS Apps instead). Receiver application refers to an HTML/Javascript application running on Chromecast or another Google Cast device.

Setup

The Google Cast Chrome Sender SDK is provided by the Google Cast extension running on the user's installation of Chrome. See the Google Cast Release Notes for the details for each release.

No special setup steps are required in order to use the Google Cast Chrome Sender SDK. As long as you have the Google Cast extension installed within the Chrome instance you use for testing, it is possible for your web content to access and use the SDK. The SDK works with Chrome version 32 and higher - which covers all up-to-date installations of Chrome. Note that the extension is not currently available for Chrome on mobile devices.

Updates to the Google Cast extension occur automatically for all users, and are used to provide fixes, user-facing features, as well as SDK capabilities. Updates are backwards-compatible, and should be transparent to your site.

A public beta channel for the Google Cast extension is also available. New versions of the extension are pushed to the beta channel prior to a full release; the beta channel is also updated more often. This gives developers (and passionate early adopters) advance access to new features, and allows you to ensure that your site works with upcoming versions of the extension.

To use the public beta channel:

  • Disable (or remove) the stable extension, assuming that you already have it installed. Right-click on the Cast extension icon, select "Manage", and then clear the "Enabled" checkbox.
  • Install the beta extension from the Chrome Web Store.
  • Use the "Send Feedback" option to report issues. We can’t respond individually to most feedback, but we greatly value the input on the beta channel.
  • Under "Options", use the "Enable Log Window" feature to see detailed Cast extension logs. These may help you with debugging.
  • When pushing updates to your live site, ensure that you test with the current stable extension. Most visitors to your site will have the stable extension installed, and if you depend on beta-only features stable version users will be impacted.

Register your application and device, as described in Registration. Once you have your app ID, you're ready to develop your application.

Development

For your app to implement the features of Google Cast, it needs to know the location of the Google Cast Chrome Sender API library. All pages of your app must refer to the libary as follows:

<script type="text/javascript" src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js"></script>

A Google Cast Chrome Sender app may be described in several phases. This overview describes the code for each phase.

Namespace

The Google Cast Chrome Sender SDK defines its top-level namespace as chrome.cast.*. The namespace represents the following:

  • Methods or functions that invoke operations on the API and their associated callbacks
  • Data objects that are passed to and from methods and callbacks
  • Event listeners for listener functions in the API

Review the Google Cast Chrome Sender API Reference for a complete description of the namespace.

Initialization

To determine if the API is available and initialize it, you can provide the callback function, window['__onGCastApiAvailable'] before the Cast API loads. It is invoked with loaded == true when the API loads, or with errorInfo when load fails (e.g. when no extension is discovered).

window['__onGCastApiAvailable'] = function(loaded, errorInfo) {
  if (loaded) {
    initializeCastApi();
  } else {
    console.log(errorInfo);
  }
}

Another way to initialize the API (still supported) is, upon page load set a timer, wait for the DOM to complete loading and for the Chrome Sender API to become available. For example, check for the API's availability with the following code:

if (!chrome.cast || !chrome.cast.isAvailable) {
  setTimeout(initializeCastApi, 1000);
}

Then, you initialize the API as follows:

initializeCastApi = function() {
  var sessionRequest = new chrome.cast.SessionRequest(applicationID);
  var apiConfig = new chrome.cast.ApiConfig(sessionRequest,
    sessionListener,
    receiverListener);
  chrome.cast.initialize(apiConfig, onInitSuccess, onError);
};

You at first create a sessionRequest object based on your own applicationID, if you are using a registered receiver application. If you are using the default receiver, for which no registration is required, you use a constant predefined by the Chrome Sender SDK, as shown below, instead of the applicationID:

var sessionRequest = new chrome.cast.SessionRequest(
                     chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID);

Next, you define an ApiConfig object using the sessionRequest object, along with two callback functions, namely sessionListener and receiverListener. Then you call the chrome.cast.initialize method by passing the ApiConfig object.

The call to the method chrome.cast.initialize has two callbacks, one for success, one for error. The sessionListener function is discussed further in the Session management section, below. Here, assuming the initialize function returns success, your application is ready to use the Cast features.

Device selection

Device selection is managed by the Cast extension. The Cast features in your app are available to your users once the initialize call returns success and the receiverListener callback function returns with the availability of device(s). Here's the receiverListener callback:

function receiverListener(e) {
  if( e === chrome.cast.ReceiverAvailability.AVAILABLE) {
  }
}

The receiverListener callback only reports whether Cast devices are available; it does not report which devices are available. The available devices are known to the Cast extension.

The user performs device selection through requestSession API call. That action must be triggered by clicking on the Google Cast icon, which must display in the media control bar, as described in the User Experience Guidelines. When the user clicks on the Cast icon, your app can request a session, which automatically triggers the Cast extension to present a list of Cast devices to connect.

This is one of the two ways for your app to get hold of a session object. Another is to connect to an existing session, discussed in Session management, below.

Launch

When the user clicks the Cast icon, launch your application and create a Cast session, as follows:

chrome.cast.requestSession(onRequestSessionSuccess, onLaunchError);

The onRequestSessionSuccess callback function returns a chrome.cast.Session object between your sender app and Chromecast receiver app for the selected Cast receiver device.

function onRequestSessionSuccess(e) {
      session = e;
 }

The Session object also has a Receiver which you can use to display the friendly name of the receiver.

The connection to your receiver doesn't occur until your sender issues its first message, such as loadRequest, described below.

Media control

Now that you have a chrome.cast.Session object, you may load media to the selected Cast device by creating a MediaInfo object for the currentMediaURL, creating a LoadRequest object from it, and then calling the loadMedia method of the session object.

var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
session.loadMedia(request,
   onMediaDiscovered.bind(this, 'loadMedia'),
   onMediaError);

function onMediaDiscovered(how, media) {
   currentMedia = media;
}

Upon successful callback of onMediaDiscovered, you get a chrome.cast.media.Media object, which grants you full media control of PLAY, PAUSE, RESUME, STOP and SEEK for the loaded media.

  • PLAY/RESUME: currentMedia.play(null, success, error);
  • PAUSE: currentMedia.pause(null, success, error);
  • STOP: currentMedia.stop(null, success, error);
  • SEEK: currentMedia.seek(null, success, error);

Media status

During media playback various events occur, so you need to add the following event listener when the media is successfully loaded.

function onMediaDiscovered(how, media) {
  media.addUpdateListener(onMediaStatusUpdate);
}

When events such as pause, play, resume or seek occur, you need to act on them and synchronize between your sender app and the receiver app on the Cast device.

Session management

Creating a new session when launching your app in response to a user action is described in Launch, above. There is a second way of getting hold of a session. For example, after a video has been cast to the receiver device and your app has created a session, a user may browse your site and visit other pages or simply reload. In this case it’s possible for your app to get hold of the existing session, using the sessionListener callback function, as follows:

function sessionListener(e) {
  session = e;
  if (session.media.length != 0) {
    onMediaDiscovered('onRequestSessionSuccess', session.media[0]);
  }
}

This enables your app to auto-join an existing session on any page of your app, manage a session’s lifecycle, and ultimately provide a seamless user experience in your app.

There is also a third way of getting a Cast session. A user with the Cast extension installed in their Chrome browser can mirror any Chrome tab to a Chromecast device. If the user lands on your site, for which you have implemented a Chromecast app, tab mirroring will automatically trigger a new Cast session instead of putting the browser in mirroring mode.

As described in Launch above, the connection to your receiver doesn't occur until your sender issues its first message.

Termination

To stop casting, you need a valid Session object. Then call the session's stop function:

function stopApp() {
  session.stop(onSuccess, onError);
}

Sample apps

See the following samples for a completely coded app:

  • Hello Video sample app - demonstrates the essential API objects, methods and event listeners.
  • CastVideos sample app - provides an implementation of an HTML5/Javascript media player that acts as a Chrome sender, is fully compliant with our UX guidelines, and demonstrates typical features such as transition between local playback mode and cast mode, states and progress bar synchronization between the two modes, and auto-join during page reload.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.