This interface is deprecated.

Beginning July 1st, 2017, any new channels using this component will be rejected during certification.

Beginning January 1st, 2018, any updates to existing channels using this component will be rejected during certification.

Implemented By

Supported Methods

Description of Methods

SetMode(mode as Integer) as Void

Sets the rendering mode for the roCaptionRenderer.  Possible values are:

1The Roku firmware does all of the closed caption rendering.  The BrightScript code only needs to call SetScreen and / or UpdateCaptions, depending on the type of screen being used
2The BrightScript code is responsible for all caption rendering operations.

If the mode is 1, the BrightScript must call SetScreen() to tell the firmware where to draw.  Additionally, if the channel is rendering captions in an roScreen instance (as opposed to an roImageCanvas instance) the script must also call UpdateCaption() to tell the firmware to draw the caption text.  An roScreen should call UpdateCaption() in response to the isCaptionUpdateRequest event.

If the mode is 2, regardless of whether captions are to be rendered in an roScreen or an roImageCanvas instance, the BrightScript code is responsible for doing all of the caption text rendering.

SetScreen(screen as Object) as Void

Set the roScreen or roImageCanvas instance associated with this caption renderer.  This function only needs to be called if the roCaptionRenderer mode is set to 1 (the default value.)  In this case, the Roku firmware is responsible for all of the closed caption text rendering, and thus must know what screen to draw on.  If the mode is set to 2, the BrightScript channel is responsible for all of the caption drawing, and thus the firmware does not need to be informed as to what screen is being rendered on.

SetMessagePort(port as Object) as Void

Set the roMessagePort that should receive roCaptionRendererEvents from the roCaptionRenderer.

ShowSubtitle(enable as Boolean) as Void

This method tells the roCaptionRenderer whether to display captions or not.  This function behaves the same as ifVideoScreen.ShowSubtitle().

UpdateCaption() as Void

For roCaptionRenderer instances with mode set to 1, this method tells the firmware to render the current caption.  If mode is 2, this function does nothing.

GetSubtitleTracks() as Object

This function returns an roArray of roAssociativeArrays, one per closed caption track found in the stream.  This function can also be used to retrieve caption URLs for external (side loaded) caption files.  Each of these roAssociativeArrays contains track information similar to that specified in the SubtitleTracks content metadata structure.  Specifically:

LanguageSpecifies the ISO 639.2B 3 character language code of the corresponding text track.
DescriptionDescription specifies the text that will be shown for the corresponding track in the closed caption configuration dialog.

TrackName contains the name of the caption track. This string is a concatenation of the track source and track id, separated by a "/". Valid track sources are: "ism", "mkv", "eia608", and "dvb". For example if a smooth stream manifest file has a caption track called “textstream_eng” the TrackName value would be "ism/textstream_eng”. For side-loaded caption tracks the TrackName is the url from where the caption track is downloaded. If the track source is "dvb", "_sdh" is appended for subtitles for the deaf and hard of hearing (for example, "dvb/eng_sdh" specifies subtitles for the deaf and hard of hearing in English, "dvb/nor" specifies Norwegian subtitles, and so forth). 

ChangeSubtitleTrack(track as String) as Void

When content playback starts, the subtitle track specified in the TrackIdSubtitle content metadata value is used to determine which set of captions to display.  The ChangeSubtitleTrack function is used to change the caption source after playback has begun.  One of the 608 channels or ttml text tracks can be selected with this function. The 608 channels are specified as 'eia608/<n>' where <n> is 1, 2, 3, or 4. The ttml text tracks are specified as 'ism/<track_name>'.