How to configure closed captioning for live streaming

Wowza Streaming Engine™ media server software supports for closed captioning for live streams. It can ingest caption data and convert it to the appropriate caption format for streaming using the Apple HLS, Adobe HDS, and RTMP protocols. 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, such as JW Player and Flowplayer, can only display AMF onTextData captioning data.

Note: This article describes how to set up closed captioning in Wowza Streaming Engine™ media server software (version 4.x). If you're running Wowza Media Server™ software (version 3.6.x), see the instructions in How to configure closed captioning for live streaming (Wowza Media Server).

Contents


Supported caption types Ingesting CEA-608 captions Ingesting AMF onTextData captions Ingesting AMF onCaption captions Playback

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. The closed captioning feature in Wowza Streaming Engine for live streaming supports the following input sources and output formats.

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 Adobe HDS and RTMP live streams.
     
  • CEA-608 formatted SEI data in the video track in Apple HLS live streams.
     
  • WebVTT text tracks in Apple HLS live streams.

Supported caption translations

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

Inputs V
Adobe HDS
(onTextData)
RTMP
(onTextData)
Apple HLS
(CEA-608 in video)
Apple HLS
(WebVTT)
AMF onTextData Yes Yes Yes Yes
AMF onCaption Yes Yes Yes Yes
CEA-608 Yes Yes Yes Yes
via API Yes 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 (such as live) 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 3-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. Click Save, and then restart the application to apply the properties.
     
  7. 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 the Wowza media server 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 traditionally associated with Adobe HDS and RTMP streaming protocols 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 server-side API to inject onTextData events into live streams using the IMediaStream.sendDirect() API 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 server-side 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 (such as live) 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 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 Wowza Transcoder. If true, all CEA-608 captions are passed through.
  7. Click Save, and then restart the application to apply the properties.
     
  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 Action Message Format (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 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 (such as live) 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 when prompted.

Playback


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

To play using JW Player (RTMP)

JW Player can display captions in RTMP streams. Use version 6.5 and later or version 5.x.

You must download JW Player libraries and deploy an HTML page to a web server. Modify the JW Player playback instructions for VOD closed captioning to use your application and stream name.

For example, for JW Player 6.5, if your Wowza Streaming Engine application is named live and the live stream is named myStream, your webpage code would look like this:
<div id="sample" ></div>

<script type="text/javascript">
    jwplayer("sample").setup({
        playlist: [{
            file: 'rtmp://10.0.0.10:1935/live/myStream',
            title: 'sample',
            description: 'sample'
	}],
        height: 300,
        width: 400
});
</script>

For complete details on how to add closed captions and subtitles to the video display in JW Player 7, see Adding Closed Captions on the JW Player website.

Using the above example (application name live and stream name myStream, for JW Player 5, your webpage code would look like this:
<div id="sample" ></div>
<script type="text/javascript">
jwplayer("sample").setup({
    file: 'myStream',
    flashplayer: 'jwplayer5/player.swf',
    height: 300,
    plugins: {
        'jwplayer5/captions.swf': {}
    },
    streamer: 'rtmp://10.0.0.10:1935/live',
    width: 400
});
</script>

To play using Flowplayer (RTMP and Adobe HDS)

Flowplayer can display closed captions in RTMP and Adobe HDS streams when the appropriate plugins are used.

You must download Flowplayer libraries and deploy an HTML page to a web server. Modify the Flowplayer playback instructions for VOD closed captioning to use your application and stream name.

For example, if your Wowza Streaming Engine application is named live and the live stream is named myStream, your webpage code would look like this:
<a href="" style="display:block;width:400;height:300px" id="sample"> </a>

<script type="text/javascript">
	flowplayer("sample", "flowplayer/flowplayer-3.x.x.swf", {
		clip: {
		url: 'http://10.0.0.10:1935/live/myStream/manifest.f4m',
                urlResolvers: ['f4m'],
		provider: 'httpstreaming',
		autoPlay: false,
		autoBuffering: false,
		scaling: 'fit',
		},
	plugins: {
       		// streaming plugin configuration
		f4m: {
			url: "flowplayer/flowplayer.f4m-3.x.x.swf" 
	  	},

        	httpstreaming: {
            		url: "flowplayer/flowplayer.httpstreaming-3.x.x.swf"
        	},

		captions: {
			url: 'flowplayer/flowplayer.captions-3.x.x.swf',
			captionTarget: 'content'
			},
		content: {
			url:'flowplayer/flowplayer.content-3.x.x.swf',
			bottom: '15%',
			backgroundColor: 'transparent',
			backgroundGradient: 'none',
			border: 0,
			opacity: .90,
			textDecoration: 'outline',
			style: {
				'body': {
					fontSize: '18',
					fontFamily: 'Verdana, Arial, Helvetica',
					fontWeight: 'bold',
					textAlign: 'center',
					color: '#ffff00'
					}
				}
			}
		},
	}
);
</script>

To play using an Apple iOS device (Apple HLS)

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

In a Safari web browser on the device, enter the following URL:
http://[wowza-ip-address]:1935/[application-name]/myStream/playlist.m3u8

Originally Published: For Wowza Streaming Engine on 03-07-2014.
 

If you're having problems or want to discuss this article, post in our forum.