• 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 configure the server for ingestion of AMF onCaption captions.

    About onCaption captions

    There are two kinds of Action Message Format (AMF) onCaption events that are supported.

    The first type of AMF onCaption events contains:

    • 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 contain the actual captions. This includes an array of captions and an optional speaker index, which refers to the onCaptionInfo speaker array.


    The second type of AMF onCaption events contains:

    • onCaptionInfo with a type of "708". This caption type contains Base-64 encoded CEA-608 or CEA-708 caption data. Wowza Streaming Engine will ingest only the CEA-608 style captions (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).

    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.

    3. Click the Properties tab, and then click Custom 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 Custom section, click Edit.

    5. Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:

      • Path - Select /Root/Application/TimedText.

      • Name - Enter captionLiveIngestType.

      • Type - Select String.

      • Value - Enter onCaption.

    6. Click Save, and then restart the application.

    Playback


    To play on an Apple iOS device

    Apple iOS players can display captions from CEA-608 messages in Apple HLS streams.

    • Enable closed-captioning in the iOS device. To do this, go to Settings > Video, and then set Closed Captioning to ON.

    • Enter the following URL into the Safari web browser on the device:

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

    To play using JW Player (RTMP)

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

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

    For example, if you were playing an application called cclive and a stream named myStream, your webpage code would look like this for JWPlayer 5:
    <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/cclive',
        width: 400
    });
    </script>
    Using the above example (cclive and myStream as application and stream names, respectively), your webpage code would look like this for JWPlayer 6:
    <div id="sample" ></div>
    
    <script type="text/javascript">
        jwplayer("sample").setup({
            playlist: [{
                file: 'rtmp://10.0.0.10:1935/cclive/myStream4',
                title: 'sample',
                description: 'sample'
    	}],
            height: 300,
            width: 400
    });
    </script>

    To play using Flowplayer (RTMP and Adobe HDS

    Flowplayer can display captions in RTMP and Adobe HDS streams when you add the appropriate captioning and streaming plugins to the player.

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

    For example, if you were playing an application called cclive and a stream 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/cclive/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>

    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.