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);