Roku SDK Documentation : Closed Caption Support

Table of Contents

The Roku platform supports the following closed caption formats:

  • EIA-608/708
  • WebVTT
  • SRT


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.

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:

sub init()
end sub


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,”
  • “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:


All Roku devices (express, premier, premier+, premier Ultra)  plus all TVs handle the button.

 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 thbutton 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 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 forwardrewind, 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

Non-Legacy Platforms

The non-legacy Roku platforms also include a closed captions setting menu (under the Settings menu option) which allows Roku users to control how closed captions are rendered on the device. These settings let users turn closed captions on and off, and to customize various caption properties such as font size, color, etc. These settings are available to developers via APIs defined on the roDeviceInfo component. It is not necessary for channels to implement their own closed caption settings UI, as the state of the global settings can be queried using these new API functions. Details of the global closed caption settings APIs can be found here.


Roku has partially implemented the SMPTE-TT TTML spec that can be referenced here: 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:

The Roku TTML parser recognizes the following basic timing attributes for use with timed elements:


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 VODYes (external file only)Yes (in stream only for all manifests containing AVC streams)NoYes (external file only)
HLS VODYes (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 LiveNoYes (in stream only for all manifests containing AVC streams)Yes  (In a separate stream described in the manifest ( playlist forhls))No
Smooth VODYes (in stream or external file)Yes (in stream only for all manifests containing AVC streams)NoYes (external file only)
Smooth LiveYes (in stream only)Yes (in stream only for all manifests containing AVC streams)NoNo
DASH VODYes (external file only)Yes (in stream only for all manifests containing AVC streams)NoYes (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)



caption_dialog.png (application/octet-stream)
architecture.png (application/octet-stream)
fig1.png (application/octet-stream)
fig2.png (application/octet-stream)
fig3.png (application/octet-stream)
fig4.png (application/octet-stream)
fig5.png (application/octet-stream)
architecturecrppd.png (image/png)
Channel_Checklist_v_1_14.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)
Roku-remote-control-star-button.png (image/png)
image2017-7-13 8:40:18.png (image/png)
image2017-7-13 8:40:0.png (image/png)
image2017-7-13 10:42:14.png (image/png)
Roku-remote-control-replay-button.png (image/png)
Roku-remote-control-4-button.png (image/png)
Roku-remote-control-star-button.png (image/png)
Roku-remote-control-star-button.png (image/png)