Tracks

Audio tracks

For audio track selection, the Web Receiver SDK provides a AudioTracksManager class that simplifies and streamlines track selection, giving you more control and better access to properties, such as name, URL, and language. This class is best used in the event handler for the cast.framework.events.EventType.PLAYER_LOAD_COMPLETE event.

The API provides various ways to query and select the active audio tracks. Here is an example of how to select a track to be active by specifying its ID:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(
  cast.framework.events.EventType.PLAYER_LOAD_COMPLETE, () => {
    const audioTracksManager = playerManager.getAudioTracksManager();

    // Get all audio tracks
    const tracks = audioTracksManager.getTracks();

    // Choose the first audio track to be active by specifying its ID
    audioTracksManager.setActiveById(tracks[0].trackId);
  });
context.start();

The AudioTracksManager class also provides a method getActiveTrack().

Here is an example of how to select the first audio track for a specified language, in this case English:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(
  cast.framework.events.EventType.PLAYER_LOAD_COMPLETE, () => {
    const audioTracksManager = playerManager.getAudioTracksManager();

    // Set the first matching language audio track to be active
    audioTracksManager.setActiveByLanguage('en');
  });
context.start();

The AudioTracksManager class also provides a method getTracksByLanguage(language) that returns all tracks for the specified language.

The audio language code is retrieved from the media manifest and should follow RFC 5646. Language codes can be presented in 2-character nomenclature (such as "es", "en" or "de"), or 4 character nomenclature (such as "en-us", "es-es" or "fr-ca").

If the media manifest follows a different language code standard, the Web Receiver app needs to convert it into an RFC 5646 conforming language code. Web Receiver SDK provides an interceptor EDIT_AUDIO_TRACKS to perform modifications:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
// Intercept the EDIT_AUDIO_TRACKS request
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.EDIT_AUDIO_TRACKS, request => {
  // write logic to convert language codes here
});
context.start();

When playing through ad breaks, any audio track selection, such as language, made before a break will persist after the break for the same content, even if the ads are in a different language.

Closed captions (subtitles)

For closed caption track selection, the Web Receiver SDK provides the TextTracksManager class that simplifies and streamlines track selection, giving you more control and better access to properties, such as name, URL and language.

The TextTracksManager class is best used in the event handler for the cast.framework.events.EventType.PLAYER_LOAD_COMPLETE event.

Closed captions selection in the Web Receiver SDK is simplified and streamlined with other parts of the SDK.

The API supports controlling WebVTT, TTML and CEA-608.

The TextTracksManager class provides various ways to query and select a closed caption track to be active. Here is an example of how to select the first track to be active by specifying its ID:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(
  cast.framework.events.EventType.PLAYER_LOAD_COMPLETE, () => {
    const textTracksManager = playerManager.getTextTracksManager();

    // Get all text tracks
    const tracks = textTracksManager.getTracks();

    // Choose the first text track to be active by its ID
    textTracksManager.setActiveByIds([tracks[0].trackId]);
  });
context.start();

The TextTracksManager class also provides a method getActiveTracks().

Here is an example of how to select the first text track for a specific language:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(
  cast.framework.events.EventType.PLAYER_LOAD_COMPLETE, () => {
    const textTracksManager = playerManager.getTextTracksManager();

    // Set the first matching language text track to be active
    textTracksManager.setActiveByLanguage('en');
  });
context.start();

The TextTracksManager class also provides a method getTracksByLanguage(language) that returns all tracks for the specified language.

The text language code is retrieved from the media manifest and should follow RFC 5646. Language codes can be presented in 2-character nomenclature (such as "es", "en" or "de"), or 4-character nomenclature (such as "en-us", "es-es" or "fr-ca").

If the media manifest follows a different language code standard, the Web Receiver app needs to convert any incoming requests to that standard. These requests, such as voice commands, use RFC 5646 language codes. The Web Receiver SDK provides an interceptor EDIT_TRACKS_INFO to translate the requests to your manifest's standard:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
// intercept the EDIT_TRACKS_INFO request
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.EDIT_TRACKS_INFO, request => {
  // write logic to convert language codes here
});
context.start();

The API allows a developer to dynamically add new closed caption tracks, in this case for different languages and out-of-band tracks, and then select a track to be the new active track:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(
  cast.framework.events.EventType.PLAYER_LOAD_COMPLETE, () => {

    // Create text tracks object
    const textTracksManager = playerManager.getTextTracksManager();

    // Create track 1 for English text
    const track1 = textTracksManager.createTrack();
    track1.trackContentType = 'text/vtt';
    track1.trackContentId = 'http://example.com/en.vtt';
    track1.language = 'en';

    // Create track 2 for Spanish text
    const track2 = textTracksManager.createTrack();
    const track2Id = track2.trackId;
    track2.trackContentType = 'text/vtt';
    track2.trackContentId = 'http://example.com/spa.vtt';
    track2.language = 'spa';

    // Add tracks
    textTracksManager.addTracks([track1, track2]);

    // Set the first matching language text track to be active
    textTracksManager.setActiveByLanguage('en');
  });
context.start();

When playing through ad breaks, any text track selection, such as language, made before a break will persist after the break for the same content, even if the ads are in a different language.

Forced captions

Forced captions or forced narrative is text overlay that is displayed so the viewer can understand when alternative language is used or to clarify audio. Unlike closed captions, a viewer does not need to enable forced captions as they are auto-selected based on the viewer's audio preferences.

To add forced captions to your Cast application, you will need to include it as part of your manifest. In your manifest, set the role of the track to be forced-subtitle. When the Cask SDK picks up these tracks, it will identify them as forced captions. There is no sender work needed as the Cast SDK will separate out forced captions and closed captions. This means a viewer will not be able to select a forced caption.

When closed captions are enabled, forced captions are disabled to prevent overlap of captions. When closed captions are turned off and if forced captions are provided in the manifest, then forced captions are displayed based on the viewer's audio language preference.

Media Browse

Queueing