Programming Closed Captioning in Player V3 Using JavaScript

Closed Captioning (CC) APIs enable you to get/set supported closed captions and localize the Player UI language.

The Ooyala Player V3 supports closed captioning (also known as subtitles) for VOD and Live Streams. Ooyala supports closed captions for VOD in our iOS and Android SDKs and for Flash and iOS Web. For live streams, closed captions are supported for Flash-based devices.
  • iOS Web - Because of the way that closed captions are supported in iOS, we are not able to add closed caption data for iOS web for remote assets.
  • Live Streaming - For live streaming on HTML5 players, if closed caption data is available in the stream and the underlying platforms supports it (as iOS does) then closed captions are displayed. The player does not facilitate the display of closed captions. If closed captions already exist in the stream, the player will not prevent them from appearing during playback.

For closed captioning to work with live streams, you need to run the broadcast stream through your encoder to convert the stream and include Adobe Flash onCuePoint Data. The onCuePoint Data can be inserted by many encoders, such as the Cisco 8100 series media encoders. You must configure the source encoder to convert the CEA format to the cue points format to include closed captions and to have them work properly. The process begins with the capture and encoding of the live stream. The live stream is also converted to have include the Flash cue points inside the stream. The stream is passed as an RTMP stream (as is) or as an Akamai HD2 live stream and is then passed to the Ooyala player.

JavaScript Closed Captioning APIs enable you to get supported closed captions and set closed caption languages. In live streaming mode, the closed caption languages are derived from the stream itself. The Closed Caption functions are:

Note: The default behavior of closed captions in the V3 Player is "Off". You can enable closed captions with setClosedCaptionsLanguage().

The player supports a number of LTR and RTL languages for close captioning and UI localization. You can review this list in the topic "Supported Closed Caption Languages".

Note: When the closed caption file is uploaded, not played, Ooyala uses a strict XML parser for handling Closed Captioning. Your closed caption files at minimum need to work with your browser’s parser.

Live Stream Closed Captions with Custom OPF Modules

If you are working with an Ooyala Player Framework (OPF) module (Player V3 Flash-based) that you want to include in Player V3 and include live stream closed captioning, you will need to use the Ooyala Closed Caption APIs. For more information about creating OPF modules, contact Sales, your Customer Success Manager, or Technical Support.

Note: Closed captioning for live streams only works with the Flash-based OPF module. The custom module available with Player V3 is a JavaScript-based module and only supports closed captioning for VOD.
During live stream playback with a custom OPF module, Ooyala will first fire a OoyalaAPIConstants.CLOSED_CAPTIONS_TEXT_READY when we receive Closed Caption information on the first cue point. If you have a third party OPF UI module:
  1. The module needs to check the available languages whenever this event goes off during live stream playback.
  2. Use getCurrentItemClosedCaptionsLanguages() to perform this check.
  3. If the live stream happens to add more languages to their available languages in the middle of stream playback, Ooyala also fires CLOSED_CAPTIONS_TEXT_READY.
  4. You can then enable closed captions as you would with VOD closed captions, using the setClosedCaptionsLanguage()function.

Was this article helpful?