Roku SDK Documentation : Closed Caption Support

Table of Contents

The Roku platform supports the following closed caption formats:

• SMPTE-TT
• EIA-608/708
• WebVTT
• SRT

Overview

SMPTE-TT uses TTML formatted data either in an external file or embedded into the video stream to carry the caption text, timing, and format information. With EIA-608/708, caption information can only be embedded into the video stream. Adding support for either of these formats to your BrightScript channel is straightforward. SMPTE-TT and EIA-608 caption formats are not supported on legacy Roku platforms where the device is running firmware version 3.1. These platforms are limited to the use of SRT subtitles.

Certification Requirements

Packaged Control Settings

In accordance with our certification requirements, Roku’s Video node automatically handles:

• closed captioning, 
• language selection, and 
• instant replay.

Unless the channel overrides it, all Roku players will launch an Options overlay menu when the  key is pressed during playback of full-screen videos.

However, this only works if the channel does not have its OnKeyEvent() handler fired, and the Video node is playing full screen and setFocus is enabled i.e., the Video node is in focus, as displayed in the following code example:

Note: When a full-screen video is playing, the user will expect the * key to work as expected. The channel must not override it in cases where there are no other UI elements showing with associated actions for the * key.

Custom Control Settings

Recommendations

Note that Captions have following three values:

• “on,”
• “on-replay,” and
• “off.”

The following is a list of recommendations and items to be aware of:

• Starting from Roku OS 8, it is no longer necessary for a channel to partake in the Closed Caption track selection, apart from adding any available tracks to the list of available tracks. The firmware now selects a Closed Caption track based on the preferred caption language selection in the system preferences. When the selected language is not available, it defaults to the system's UI language.
• The global closedCaptionMode method of the Video node object is how you turn on and off closed captioning of the current playing video. The global settings can be read and set in the roDeviceInfo object. These affect the same system setting. Whenever the user switches on/off closed caption, it is expected that the global setting will be adjusted accordingly. Therefore setting the global setting every time you adjust a local setting is required.
• The audio track and the subtitle track (for Multilanguage subtitles) can be set using the VideoNode.audioTrack and VideoNode.subtitleTrack respectively. The available tracks can be found with VideoNode.availableAudioTracks and VideoNode.availableSubtitleTracks. Another useful item is roDeviceInfo.GetCurrentLocale.

• If you are using the roVideoScreen or roVideoPlayer, you should be rewriting your application in SceneGraph as the older technologies are being dropped from the firmware.

Star Button

Important notes about the  Button:

Instant Replay Button

Similarly, to closed captioning, Roku recommends that you allow us to handle use of the instant replay button  in our firmware. However, if you decide to override our built-in functionality, then your channel must offer equal levels of functionality.

While playing video, pressing  will move the play head back 20 seconds and resume playing. If the closed caption setting is set to “On-replay,” then closed captioning will appear for the duration of time until playback reaches the position where the user presses  .

The instant replay button events can be received like any other events.

Beginning with Roku OS 8, the firmware will automatically enable the closed captions during the replay interval.

Pressing  multiple times should move the play head and changes the demarcation point accordingly i.e., only the most recent replay applies. Also, if you are live streaming you can stop seeking back if the play head hit the end of the live window.

Additional Considerations

Although Closed Captioning and Subtitles are two different things and server separate functions, both functions reside within the Video node.

One important consideration with the rules outlined above is that the Roku Ad Framework (RAF) will turn off trickplay and the instant replay for the duration of an ad. If you are using server-stitched, it is up to the channel to disable this with videoplayer.enableUI.

Finally, note that the fast forward, rewind, and the left & right arrows on the direction pad should move the play head.

Use videoplayer.notificationInterval events to simplify the channel logic around this.

Related Topics

• Video node: sdkdocs.roku.com/display/sdkdoc/Video
• ifDeviceInfo: sdkdocs.roku.com/display/sdkdoc/ifDeviceInfo
• Event loops: sdkdocs.roku.com/display/sdkdoc/Event+Loops
• RAF overview: blog.roku.com/developer/2016/02/10/roku-ad-framework/

SMPTE-TT 

Roku has partially implemented the SMPTE-TT TTML spec that can be referenced here: http://www.w3.org/TR/ttaf1-dfxp/. Roku makes no claim of even minimal compliance. The link to the TTML spec is provided only for discussion on features we have implemented. Roku's TTML parser will recognize regions, styles, and spans. The captions are recognized as "p" paragraph elements with a "begin" and "end" time. Roku's TTML does not recognize the "duration" attribute for captions.

Roku's Caption rendering will always use a build in Gotham font regardless of any font specified in the TTML. Likewise, font styles (like italics or Bold) are also ignored. However, the Roku Caption rendering will make the best guess effort at choosing the corresponding font size in the system Gotham font using the specified font size in the TTML.

Roku's TTML parser recognizes sufficient stylings to render colors, positions, and alignments either on an absolute or percentage offset. Namespaces do not cause a problem for the parser, but they are not validated either.

The Roku TTML parser recognizes the following elements from Section 7 of the TTML spec that specify the structure and principal content aspects of a document instance:

• 7.1.1 tt

• 7.1.2 head

• 7.1.3 body

• 7.1.4 div

• 7.1.5 p

• 7.1.6 span

The Roku TTML parser recognizes the following elements from Section 8 of the TTML spec that specify the structure and principal styling aspects of a document instance:

• 8.1.1 styling

• 8.1.2 style

The Roku TTML parser recognizes the following styling elements from Section 8.2 of the TTML spec:

• 8.2.2 backgroundColor

• 8.2.3 color

• 8.2.6 displayAlign

• 8.2.7 extent

• 8.2.9 fontSize

• 8.2.14 origin

• 8.2.18 textAlign

The Roku TTML parser recognizes the following layout elements from Section 9 of the TTML spec:

• 9.1.1 layout

• 9.1.2 region

EIA-608

Roku supports EIA-608 closed caption data (analog TV format) encapsulated within a EIA-708 container (digital TV) in an H.264 elementary stream. EIA-608 captions are delivered as part of the video stream itself. One benefit of this caption format is that there can be multiple “channels” of captions within the stream. These separate channels could be used for different languages, for example, English captions on one channel, Spanish on another, and so forth.

To render EIA-608 captions from within BrightScript, simply set the TrackName attribute of the SubtitleConfig content metadata parameter to “eia608/n” where n is the caption channel. Also, add it to SubtitleTracks to specify the correct language.

WebVTT

Roku supports WebVTT captions if embedded in HLS streams or manifests. As with the other closed caption formats, a channel specifies WebVTT captions in the SubtitleTracks metadata. The TrackName property is set to "webvtt/track" where track specifies the index of the caption track to render.

SRT

Roku has limited support for SRT files and SSA/ASS files (converted to SRT). Any HTML tags in the text are discarded.

Closed Caption Support Summary

Below is a summary of the closed caption formats supported by the various video streaming technologies on Roku devices.