Secondary Image

Cast developers can add an additional informational (secondary) image to the UI for audio and video applications. Most commonly-used image formats are supported for the secondary image.

This secondary image appears on the top right of the display, and can be used to display a graphic with additional information about the currently-playing content, such as content format, radio station call sign, or TV-show rating.

Details of implementation and integration differ slightly between audio and video apps, as explained below.

Audio

Overview

For audio applications, the secondary image displays on the upper-right of the screen when audio content has been loaded onto the receiver. The secondary image persists on screen as long as content is playing, until it is removed.

The secondary image is supported for audio applications through metadata to allow the secondary image to be updated based on the content that is playing. For example, the secondary image can display a Station Logo for the currently-playing audio content.

If a smart display is used as a remote control for audio, the secondary image, if set will also appear on the smart display, and any subsequent changes will be reflected on the smart display as well as on the receiver (if associated with a display device).

Implementation

To set, remove, or update the secondary image, the secondaryImage property of MusicTrackMediaMedata must be modified. To set a secondary image, first you need to create an Image object, providing the secondary image URL as one of the parameters. Set metadata.secondaryImage to the Image object you just created, as shown in the example below.

Here we are setting the secondary image within the load interceptor. When the content loads, the secondary image is displayed.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, loadRequestData => {
    loadRequestData.media.metadata = new cast.framework.messages.MusicTrackMediaMetadata();

    // Set image on secondaryImage field of metadata object
    loadRequestData.media.metadata.secondaryImage =
        new cast.framework.messages.Image("https://www.image.png");

    return loadRequestData;
});

As shown here, you can also make use of EMSG or ID3 Events to update the secondary image. To do this, first get the mediaInformation object from the playerManager. Then get a reference to the metadata object from the mediaInformation. On this metadata object, set the updated secondaryImage for display. For changes to take effect, update the mediaInformation by calling setMediaInformation on playerManager and passing the updated mediaInformation object.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.addEventListener(cast.framework.events.EventType.EMSG, () => {
    let mediaInformation = playerManager.getMediaInformation();
    mediaInformation.metadata.secondaryImage =
        new cast.framework.messages.Image("http://anotherimage.png");
    playerManager.setMediaInformation(mediaInformation);
});

To unset the secondary image, set the secondaryImage to null on the metadata object.

// To unset the secondary image, set secondaryImage to null.
let mediaInformation = playerManager.getMediaInformation();
mediaInformation.metadata.secondaryImage = null;
playerManager.setMediaInformation(mediaInformation);

Video

Overview

For video applications, the secondary image is not driven by content metadata. The secondary image only displays on the overlay, which only appears when video controls are displayed.

Here we can see what the secondary image overlay looks like on smart displays.

Implementation

Setting the secondary image overlay is simple. First get an instance of the UiManager. On this instance of UiManager, call setSecondaryImage and pass to it two parameters: the position and url of the image. The position that is passed is SecondaryImagePosition.VIDEO_OVERLAY. Setting the secondary image can be done anytime.

/**
 * Sets the image for secondary image overlay.
 * Clears out any image that was previously set.
 */
const castUiManager = cast.framework.ui.UiManager.getInstance();
castUiManager.setSecondaryImage(cast.framework.ui.SecondaryImagePosition.VIDEO_OVERLAY, "http://www.image.png");

Unsetting the secondary image is similar to setting an image. The only difference is that you pass in null for the second parameter when calling setSecondaryImage.

// To manually clear out image, set image to null or empty string.
const castUiManager = cast.framework.ui.UiManager.getInstance();
castUiManager.setSecondaryImage(
    cast.framework.ui.SecondaryImagePosition.VIDEO_OVERLAY, null);