Configure closed captioning for Wowza Streaming Engine live streams

Updated on 12/18/2024 11:32 am PST

Wowza Streaming Engine™ media server software can ingest caption data and convert it to the appropriate caption format for streaming using HLS and RTMP. Many player technologies, including Apple iOS devices, VideoLAN VLC player, and many set-top boxes, can display CEA-608 closed captioning data embedded in live streams. Other player technologies can only display AMF onTextData captioning data.

Supported caption types

There are many types of closed caption sources, and each streaming standard may use a different format for embedding captions on the output. Wowza Streaming Engine supports the following input sources and output formats for closed captions in live streams.

Supported input sources

  • CEA-608 captions embedded in live streams.
     
  • Captions embedded as Action Message Format (AMF) onTextData in input streams.
     
  • Captions embedded as AMF onCaption and onCaptionInfo in input streams.
     
  • An API is provided to insert onTextData into a stream.

Supported outputs

The following outputs can be translated from any of the supported input sources:

  • onTextData events in RTMP live streams.
     
  • CEA-608 formatted SEI data in the video track in HLS live streams.
     
  • WebVTT text tracks in HLS live streams.

Supported caption translations

The following table summarizes the input-to-output caption translations that are supported by Wowza Streaming Engine:
 
Outputs >

Inputs v		 RTMP
(onTextData)		 HLS
(CEA-608 in video)		 HLS
(WebVTT)
AMF onTextData Yes Yes Yes
AMF onCaption Yes Yes Yes
CEA-608 Yes Yes Yes
via API Yes Yes Yes

Ingesting CEA-608 captions

This section describes how to set up your live application to monitor live streams for CEA-608 captions, decode the captions, and convert them to onTextData events.

Configuring CEA-608 captions

  1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your live application in the contents panel.
     
  2. In the application Setup page, click Edit. Scroll down to the Closed Caption Sources area and select Embedded CEA-608 captions in live streams. Click Save, and then restart the application when prompted.
     
  3. Click the Properties tab, and then click Closed Captions in the Quick Links bar.
     
    Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
  4. In the Closed Captions section, click Edit.
     
  5. Enable each of the properties detailed in the table below and set their values to the corresponding table values.
     
    Name
    Value
    Description
    captionUndefinedLanguageId eng The language code to use for the caption if the language ID provided isn't recognized. If not specified, defaults to the three-letter locale of the server.
    ccIngestCEA608EnableField1 true Specifies if CEA-608 field 1 is enabled. The default value is true (enabled). Typically, either field 1 or field 2 is enabled, not both.
    ccIngestCEA608EnableField2 false Specifies if CEA-608 field 2 is enabled. The default value is false (disabled).
    ccIngestCEA608LogCaptions true Specifies if the parsed captions are logged. The default value is true (enabled).
    ccIngestCEA608VerboseLogging false Enables verbose logging of the CEA-608 parser. The default value is false (disabled).
  6. (Optional) Use the ccIngestCEA608RemoveExistingCEA608 custom property to control the transcoded output of the live stream with CEA-608 captions.
    1. On the Properties tab, click Custom in the Quick Links bar.
    2. In the Custom section, click Edit.
    3. Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:
      Path
      Name
      Type
      Description
      /Root/Application/TimedText ccIngestCEA608RemoveExistingCEA608 Boolean Enables the removed of the ingested CEA-608 captions. The default value, false, preserves the ingested CEA-608 captions in the transcoded output. To remove the existing CEA-608 captions, set to true.
  7. Click Save, and then restart the application.
     
  8. Publish your live stream with CEA-608 captions from an encoder to the live application. For this example, we'll use the stream name myStream.
 
Note: Due to the differing nature of CEA-608 captions versus captions in a streaming server, some caption modes are decoded better than others. Pop-on captions (captions that appear anywhere on the screen as a whole, followed by another caption or no captions) are best. Other caption modes (such as scroll-up captions that draw directly to the screen) may exhibit some delay. This is due to the fact that CEA-608 draws directly to the device, while Wowza Streaming Engine must detect the end of each caption in order to capture it and send it with the outgoing stream.

When considering how to send captions to Wowza Streaming Engine in live streams:
 
  • Use pop-on captions where possible.
     
  • If using other caption modes, if possible, minimize the amount of time between the start of caption drawing and the end of the caption.

Ingesting AMF onTextData captions

This section describes how to set up your live application to monitor live streams for Action Message Format (AMF) onTextData captions, decode the captions, and convert them to CEA-608 captions.

AMF onTextData events are commonly associated with RTMP and used to carry closed caption or subtitle information. An onTextData event usually includes the following fields:
 
  • text – Carries the UTF-8 encoded text for the event.
     
  • lang – The three-letter language ID for the event (for example, eng).
     
  • trackid – (Optional) For on-demand streaming, this is the ID of the text track in the video file. For live streaming, this field is either omitted or set to 99.
The live application in Wowza Streaming Engine monitors a live stream for onTextData events, extracts the text field, formats it as CEA-608 closed-caption data, and then injects it into the video stream as SEI NAL units. Many player technologies, including Apple iOS devices, VideoLAN VLC player, and many set-top boxes, can then display the embedded closed-captioning data.
 
Note: You can use the Wowza Streaming Engine Java API to inject onTextData events into live streams using the IMediaStream.sendDirect() call (see Example module for publishing onTextData captions to download the PublishOnTextData package, which uses this API). This enables a publisher that passes closed-caption data in the form of timed text events or SMPTE events to use the Wowza Streaming Engine Java API to inject onTextData into a live stream. The onTextData is intercepted and injected into the stream as CEA-608 events.

Configuring onTextData captions

  1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your live application in the contents panel.
     
  2. In the application Setup page, click Edit. Scroll down to the Closed Caption Sources area and select onTextData events in live streams. Click Save, and then restart the application when prompted.
     
  3. Click the Properties tab, and then click Closed Captions in the Quick Links bar.
     
    Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
  4. In the Closed Captions section, click Edit.
     
  5. Enable the property detailed in the table below.
     
    Name
    Value
    Description
    closedCaptionLiveMaxDisplayTime 10000 Maximum time, in milliseconds, that a CEA-608 closed caption is displayed on the screen.
  6. (Optional) You can add the optional custom properties in the following table to customize the application configuration. To add a custom property:
     
    1. On the Properties tab, click Custom in the Quick Links bar.
       
    2. In the Custom section, click Edit, and then click Add Custom Property.
       
    3. In the Add Custom Property dialog box, enter the information for an optional property from the following table, and then click Add.
     
    Path
    Name
    Type
    Value
    /Root/Application/TimedText closedCaptionLiveCommandsPerFrame Integer Maximum number of closed caption commands to send per-frame (maximum is 31).
    /Root/Application/TimedText closedCaptionLiveChannel Integer Close captioning channel. Valid values are 0 (CC1) and 1 (CC2). (Note: Only CC1 seems to work with Apple iOS devices.)
    /Root/Application/TimedText closedCaptionLiveColor Integer Color of closed caption text. Valid values are 0 (white), 2 (green), 4 (blue), 6 (cyan), 8 (red), 10 (yellow), and 12 (magenta).
    /Root/Application/TimedText closedCaptionLiveCharacterSet String Closed caption character set to use when converting onTextData text data to caption data. For example, UTF-8.
    /Root/Application/TimedText closedCaptionLiveLogOnTextDataEvents Boolean Controls logging of individual onTextData events. If true, all onTextData events are logged.
    /Root/Application/TimedText closedCaptionLiveEnableTranscoderResults Boolean Controls whether CEA-608 captions are passed through Transcoder. If true, all CEA-608 captions are passed through.
  7. Click Save, and then restart the application.
     
  8. Publish your live stream with onTextData captions from an encoder to the live application. For this example, we'll use the stream name myStream.
Example module for publishing onTextData captions

You can download a package that includes an example module (ModulePublishOnTextData) that injects onTextData events into a live stream. This module takes caption data from a flat text file and injects an onTextData event into the live stream every 6.5 seconds. This module is only for testing purposes and is an example of how to inject onTextData events into a live stream. Download PublishOnTextData.zip.

Ingesting AMF onCaption captions

This section describes how to set up your live application to ingest AMF onCaption captions. Wowza Streaming Engine supports two kinds of AMF onCaption events.

The first contains:

  • An onCaptionInfo event that defines the speakers and tracks caption information. This information may contain an array of speakers and an array of tracks.
     
  • onCaption events that have the actual captions. This includes an array of captions and an optional speaker index, which refers to the onCaptionInfo speaker array.

The second contains an onCaptionInfo event with a 708 caption type. This caption type contains Base64-encoded CEA-608 or CEA-708 caption data. Wowza Streaming Engine ingests only the CEA-608 caption data (in paint-on, roll-up, or pop-on styles).

Configuring onCaption captions

  1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your live application in the contents panel.
     
  2. In the application Setup page, click Edit. Scroll down to the Closed Caption Sources area and select onCaptionInfo events in live streams. Click Save, and then restart the application.

Playback

Note: Each player may have unique user controls to enable/disable caption rendering and/or caption language selection.

Play using an Apple iOS device (HLS)

iOS players can display captions from CEA-608 messages in HLS streams after enabling closed captioning on the device: Open Settings and tap General > Accessibility > Subtitles & Captioning. Then, turn on Closed Captions + SDH.

In Safari on the device, enter the following URL:

http://[address]:1935/[application-name]/myStream/playlist.m3u8

Was this article helpful?
Thank you for your feedback!
User Icon

<p align="left">Thank you for providing feedback to help us improve our documentati

© 2007–2024 Wowza Media Systems™, LLC. All rights reserved.   Security & Privacy PolicyLegalSystem Status