Customize CAF Receiver UI

Styling the Player

The CAF Receiver SDK provides a built-in player UI. In order to use this UI, you need to add cast-media-player element to your HTML. CSS-like styling allows setting various things including background image, splash image, font family and other things.

<cast-media-player id="player"></cast-media-player>
<style>
  body {
    --playback-logo-image: url('http://some/image.png');
  }
  #player {
    --theme-hue: 100;
    --progress-color: rgb(0, 255, 0);
    --splash-image: url('http://some/image.png');
  }
</style>
<script>
  // Update style using javascript
  let playerElement = document.getElementById('player');
  playerElement.style.setProperty('--splash-image', 'url("http://some/other/image.png")');
</script>

The following tables list all currently available customization parameters.

Name Default Value Description
--background-image Background image.
--ad-title Ad Title of the ad.
--skip-ad-title Skip ad Text of the Skip Ad text box.
--font-family Open Sans Font family for metadata and progress bar.
--spinner-image Default image The image to display while launching.
--buffering-image Default image The image to display while buffering.
--pause-image Default image The image to display while paused.
--play-image The image to show in metadata while playing.
--theme-hue 42 The hue to use for the player.
--progress-color hsl(hue, 95%, 60%) Color for progress bar.
--break-color hsl(hue, 100%, 50%) Color for the ad break mark.
--splash-background none CSS background property
--splash-image App name CSS background-image property
--splash-size auto CSS background-size property
--splash-color transparent CSS background-color property
--logo-repeat repeat CSS background-repeat property
--logo-background none CSS background property
--logo-image none CSS background-image property
--logo-size auto CSS background-size property
--logo-color transparent CSS background-color property
--logo-repeat repeat CSS background-repeat property
--playback-logo-image none CSS background-image property
--watermark-background none CSS background property
--watermark-image none CSS background-image property
--watermark-position 0 CSS background-position property
--watermark-size auto CSS background-size property
--watermark-color transparent CSS background-color property
--watermark-repeat repeat CSS background-repeat property

A blank value in the "Default value" column indicates no default exists.

Slideshow

To have up to 10 images cycle through during idle state (in place of the splash image), use the following slideshow parameters.

Name Default Value Description
--slideshow-interval 10s Time between images.
--slideshow-animation 2s Duration of transition.
--slideshow-image-1 First image in slideshow.
--slideshow-image-2 Second image in slideshow.
--slideshow-image-3 Third image in slideshow.
--slideshow-image-4 Fourth image in slideshow.
--slideshow-image-5 Fifth image in slideshow.
--slideshow-image-6 Sixth image in slideshow.
--slideshow-image-7 Seventh image in slideshow.
--slideshow-image-8 Eighth image in slideshow.
--slideshow-image-9 Ninth image in slideshow.
--slideshow-image-10 Tenth image in slideshow.

A blank value in the "Default value" column indicates no default exists.

Overscan

Layouts for TV have some unique requirements due to the evolution of TV standards and the desire to always present a full screen picture to viewers. TV devices can clip the outside edge of an app layout in order to ensure that the entire display is filled. This behavior is generally referred to as overscan. Avoid screen elements getting clipped due to overscan by incorporating a 10% margin on all sides of your layout.

Optimizing for Smart Display

Smart displays are devices with touch functionality to allow receiver applications to support touch-enabled controls.

This guide explains how to optimize your CAF receiver application when launched on smart displays and how to customize the player controls.

Accessing UI controls

The UI Controls object can be accessed with the following code:

const controls = cast.framework.ui.Controls.getInstance();

If you are not using cast-media-player element, you need to set touchScreenOptimizedApp in CastReceiverOptions.

context.start({ touchScreenOptimizedApp: true });

Default layout

Default control buttons are assigned to each slot based on MetadataType and MediaStatus.supportedMediaCommands.

MetadataType.Movie, MetadataType.Generic

A. --playback-logo-image

B. MovieMediaMetadata.subtitle or GenericMediaMetadata.subtitle.

C. MovieMediaMetadata.title or GenericMediaMetadata.title.

D. MediaStatus.currentTime

E. MediaInformation.duration

F. ControlsSlot.SLOT_1

G. ControlsSlot.SLOT_2

H. Play / Pause

I. ControlsSlot.SLOT_3

J. ControlsSlot.SLOT_4

When the value of supportedMediaCommands equals to ALL_BASIC_MEDIA, default control layout will display as below:

When the value of supportedMediaCommands equals to ALL_BASIC_MEDIA | QUEUE_PREV | QUEUE_NEXT, default control layout will display as below:

When the value of supportedMediaCommands equals to PAUSE | QUEUE_PREV | QUEUE_NEXT, default control layout will display as below:

When text tracks are available, closed caption button would be always shown at SLOT_1.

To dynamically change the value of supportedMediaCommands after starting a receiver context, you can call PlayerManager.setSupportedMediaCommands to override the value. Also, you can add new command by using addSupportedMediaCommands or remove existing command by using removeSupportedMediaCommands.

MetadataType.MUSIC_TRACK

A. --playback-logo-image

B. MusicTrackMediaMetadata.albumName

C. MusicTrackMediaMetadata.title

D. MusicTrackMediaMetadata.albumArtist, MusicTrackMediaMetadata.artist, or MusicTrackMediaMetadata.composer

E. MusicTrackMediaMetadata.images[0]

F. MediaStatus.currentTime

G. MediaInformation.duration

H. ControlsSlot.SLOT_1

I. ControlsSlot.SLOT_2

J. Play / Pause

K. ControlsSlot.SLOT_3

L. ControlsSlot.SLOT_4

When the value of supportedMediaCommands equals to ALL_BASIC_MEDIA, default control layout will display as below:

When the value of supportedMediaCommands equals to ALL_BASIC_MEDIA | QUEUE_PREV | QUEUE_NEXT, default control layout will display as below:

To dynamically change the value of supportedMediaCommands after starting a receiver context, you can call PlayerManager.setSupportedMediaCommands to override the value. Also, you can add new command by using addSupportedMediaCommands or remove existing command by using removeSupportedMediaCommands.

Custom button layout

Using a custom layout if you want to change buttons in UI controls.

It's highly recommended to remove all default buttons to prevent conflicts of custom layout and default layout.

const controls = cast.framework.ui.Controls.getInstance();
controls.clearDefaultSlotAssignments();

Then, you can assign control buttons to 4 slots by calling assignButton.

controls.assignButton(
  cast.framework.ui.ControlsSlot.SLOT_1,
  cast.framework.ui.ControlsButton.LIKE
)

controls.assignButton(
  cast.framework.ui.ControlsSlot.SLOT_4,
  cast.framework.ui.ControlsButton.DISLIKE
)

And, the custom layout will display as below:

When the assigned button is not supported in MediaStatus.supportedMediaCommands, the button would be greyed out. For example, supportedMediaCommands equals to ALL_BASIC_MEDIA | QUEUE_NEXT | LIKE | DISLIKE, QUEUE_PREV button would be disabled.

To dynamically change the value of supportedMediaCommands after starting a receiver context, you can call PlayerManager.setSupportedMediaCommands to override the value. Also, you can add new command by using addSupportedMediaCommands or remove existing command by using removeSupportedMediaCommands.