KONtx.control.CaptionsOverlay

media player transport keys with closed captioning

The KONtx.control.CaptionsOverlay class is an accessory to the KONtx.mediaplayer class to provide a closed captioning (CC) toggle button to the fullscreen transport keys user interface. On activation, this button pauses the media player until the captions data (provided as a TTML URL) is downloaded, parsed, and has started sequencing. The activation state of this toggle button is persistently stored per viewer profile.

See Chapter 7, Closed Captions for more information.

By default, the KONtx.control.CaptionsOverlay shows a closed captioning button, a play/pause button, a stop button, and a visual indication of the playback progress. The CC button works as follows:

  • The CC button is greyed out. The viewer cannot select the button. The TTML document may be unavailable or malformed.

  • The CC button is available for selection. The TTML document is available and able to be parsed. The viewer must toggle the CC button to display captions. The button's toggle state is stored in the viewer's profile and used for future playlist entries.

  • The CC button is selected. Closed captions are displayed.

The closed captioning controller is activated by the transport controls as follows:

  • When the play control is activated, the captions controller is loaded and the captions sequencer is started.
  • When the pause control is activated, the captions sequencer pauses.
  • When the stop control is activated, the captions controller is unloaded, the captions sequencer is stopped, and the content is removed from the screen.

Extends

KONtx.element.Core

Example

Properties

Property

Type

Description

data.body

Array

The normalized body of the TTML document.

data.captions

Object

The caption Object for the current entry in the current playlist.

data.config

Object

Closed captions settings on the root node "tt".

data.fulfilled

Boolean

Indicates if the parser has completed. Set after onDataReceived() function completion. Default value is true.

data.head

Object

The normalized head of the TTML document.

data.id

String

The identifier of the TTML URL provided when captions are activated. Used for parsing performance.

defaultRegionId

String

The default region used for styling. The default value is "anonymous".

fontSize

String

The closed captions text font size. Default value is 6.67% of the video height.

state.dataDelivered

Boolean

If hardware-based closed captions is used, this Boolean indicates if the TTML URL has been sent through the TV API active input object to the device. The default value is false.

state.nextCaptionIndex

integer

Provides the index of the next caption.

state.nextInterval

integer

Provides the index of the next captions interval.

state.regionsActive[index]

Array

Provides the active region at the given index.

styles

Object

Provides the screen width and height attributes.

onActivate

event

Subscribes to the media player event. Fired when the CC button is selected on the transport control.

onControlStop

event

Fired when the stop button is selected on the transport controls.

onDataReceived

event

Normalizes the incoming data to create a standard payload for the renderer by calling processConfig(), processHead(), and processBody().

onDeactivate

event

Unsubscribes from the media player event. Fired when the CC button is unselected.

onPlayerStateChange

event

Fires the onPlayerTimeIndexChange event if the event.payload.newState is BUFFERING or PLAY. Fires the onDeactivate event if the event.payload.newState is STOP.

onPlayerTimeIndexChange

event

Sets the interval, caption, and region state properties based on the time of the captions entry.

Methods

void addEntries(int currentInterval);

If the time of the entry is at the current time interval then the closed captions region is added.

void applyEntryStyles(Object regionNode, Object captionEntry);

Sets the region style to caption entry styles.

void applyEntryText(Object regionNode, Object captionEntry);

Sets the region text to the caption content.

int convertTimeSignature(Object clock);

Converts frame rate time or clock time to fractional seconds, causing a small delay, to support video streaming time interval granularity which does not support milliseconds.

Text createEntryNode(Array regionNodes, Object captionEntry);

Creates a region node if it does not already exist.

void initialize();

Initializes the control.

Object populateEntryStyles(Object entry, String defaultStyle);

Hierarchically merges styles to the entry and container display. Returns the merged styles Object.

Array processBody(Object data);

Sets each closed captions entry from the given data. Returns the body array of closed caption entries.

Object processConfig(Object data);

Sets the "frameRate" from the configuration in the given data. Returns the config Object.

void processEntries(int currentInterval);

Adds or removes entries based on the current time interval.

Object processHead(Object data);

Sets the "styling.style" and "layout.region" from the head in the given data. Sets the defaultRegionId property to "anonymous" if none exists. Returns the head Object.

void removeEntries(int currentInterval);

If the end time of the entry is less than the current time interval then the closed captions region is removed.

void setHardwareState(Boolean state);

If the given state is true and the media player is in an active state, then the hardware interface (if available) is activated and the captions entry URL is passed to the hardware for rendering via the TV API call tv.cc.setClosedCaptionUrls(). If the given state is false then the hardware interface (if available) is deactivated.

void setSoftwareState(Boolean state);

If the given state is true, then the software renderer is activated and the captions entry URL is passed to the software parser and the software renderer is activated when the onDataReceived event is fired. If the given state is false then the software rendering of captions is deactivated.

Array structureList(Object data, String namespace);

Creates a string identifier-based array of entry items using the TTML "id" attribute. Returns the array of items.

Table of Contents