Table of Contents
The Roku platform supports the following closed caption formats:
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.
Closed Caption tracks specification
Use the Content-Meta-Data property SubtitleTracks that specify language, description and track name for each subtitle track. The SubtitleConfig property should not be used – unless overriding the caption track that is automatically selected based on user caption language preference. When specifying a track in SubtitleConfig – be sure to also specify it in SubtitleTracks so that the language and description are clear. Omitting the description will cause the UI to display the language in the closed caption menu. A description should at least contain the language.
The Video Node has additional fields related to closed captioning.
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 thekey 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
Note that Captions have following three values:
- “on-replay,” and
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.
Important notes about the Button:
button.All Roku devices (express, premier, premier+, premier Ultra) plus all TVs handle the
Beginning with Roku OS 8, the Options overlay slides in whenever the button is pressed, the Video node is in focus, and the OnKeyEvent() handler is fired. When the Video node is not in focus, the Options overlay does not slide in and the OnKeyEvent() handler is fired.
If you are running the Video Node on older Roku devices, then the button can only be detected at the channel level. As a result, you will not be able to disable the default UI on any of the older Roku devices.
Instant Replay Button
Similarly, to closed captioning, Roku recommends that you allow us to handle use of the instant replay buttonin our firmware. However, if you decide to override our built-in functionality, then your channel must offer equal levels of functionality.
While playing video, pressingwill 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.
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.
- 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/
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:
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:
The Roku TTML parser recognizes the following styling elements from Section 8.2 of the TTML spec:
The Roku TTML parser recognizes the following layout elements from Section 9 of the TTML spec:
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.
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.
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.
|MP4 VOD||Yes (external file only)||Yes (in stream only for all manifests containing AVC streams)||No||Yes (external file only)|
|HLS VOD||Yes (external file only)||Yes (in stream only for all manifests containing AVC streams)||Yes (In a separate stream described in the manifest ( playlist forhls))||Yes (external file only)|
|HLS Live||No||Yes (in stream only for all manifests containing AVC streams)||Yes (In a separate stream described in the manifest ( playlist forhls))||No|
|Smooth VOD||Yes (in stream or external file)||Yes (in stream only for all manifests containing AVC streams)||No||Yes (external file only)|
|Smooth Live||Yes (in stream only)||Yes (in stream only for all manifests containing AVC streams)||No||No|
|DASH VOD||Yes (external file only)||Yes (in stream only for all manifests containing AVC streams)||No||Yes (external file only)|
Yes (in stream only)
Yes (in stream only for all manifests containing AVC streams)
Yes (in a separate unencapsulated stream described in the manifest)