• How to configure closed captioning for video on demand streaming

    Wowza™ media server software includes support for closed captioning for on-demand (VOD) streams. It can ingest caption data from a variety of in-stream and file-based sources and convert that caption data to the appropriate caption format for on-demand video streaming using Apple HLS, Adobe HDS, or RTMP streaming protocols.

    Note: Wowza Streaming™ Engine software or Wowza Media Server™ software (version 3.5.0 or later) is required.

    Contents


    Supported caption types
    External companion file setup
    Closed captions configuration
    Playback
    TroubleshootingMore resources

    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 media server for VOD streaming supports the following input sources and output formats.

    Supported input sources

    For captions embedded in a VOD file, use the following caption sources:
    • 3GPP/MPEG-4 Timed Text tracks
    • CEA-608 captions as SEI data in a video track. This caption data is passed through to the output video streams.

    For captions defined in an external companion file, use the following caption sources:
    • Timed Text Markup Language (TTML)
    • SubRip Text (SRT)
    • Web Video Text Tracks (WebVTT)
    • Scenarist Closed Caption (SCC)

    Notes:
    • Only iOS-based players support interpretation and rendering of SEI data as CEA-608 captions.

    • iOS players don't support multi-byte languages.

    Supported outputs

    Outputs are translated from any of the supported input sources to certain output types depending on the streaming protocol used:

    • CEA-608-formatted SEI data in the video track in Apple HLS VOD streams
    • onTextData events in Adobe HDS and RTMP VOD streams

    Supported caption translations

    The following table summarizes the input-to-output caption translations that are supported by Wowza media server software.

    Outputs ˃
    Inputs ˅
    Apple HLS
    (CEA-608 in video)
    RTMP
    (onTextData)
    Adobe HDS
    (onTextData)
    Embedded 3GPP tracks
    Embedded CEA-608 no no
    TTML file
    SRT file
    WebVTT file
    SCC file

    Note: For specifications and documentation on different supported closed caption sources, see More resources.

    How it works

    Wowza media server software supports VOD closed captioning through VODTimedTextProviders. Each provider knows how to ingest the timed text from a specific source type into the media server's generic timed text data model. A provider is included for assets with embedded 3GPP/MPEG-4 captions and another for assets with external companion files. You can configure an application to include the provider(s) required to ingest the desired sources (For more information, see Closed captions configuration. Note that the 3GPP provider is "enabled" by default in released configuration files.

    External companion file setup


    Place the TTML (.ttml), SRT (.srt), WebVTT (.vtt), or SCC (.scc) caption file next to the video asset file in the [install-dir]/content folder and ensure that the root file name of the caption file is the same as that of the asset file (for example, sample.ttml and sample.mp4). This allows the corresponding VODTimedTextProvider to find the file and ingest it for caption insertion during playback.

    TTML example

    The following example shows a simple TTML file (sample.ttml). This file is placed in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL parameter is specified in the client URL, the TTML file must have the same name (and different file extension) as the asset file (for more information, see To specify the caption file to use in playback URLs).
    <?xml version='1.0' encoding='UTF-8'?>
    <tt xmlns='http://www.w3.org/ns/ttml' 
        xmlns:tt='http://www.w3.org/ns/ttml' 
        xmlns:ttm='http://www.w3.org/ns/ttml#metadata' 
        xmlns:tts='http://www.w3.org/ns/ttml#styling' 
        xmlns:ttp='http://www.w3.org/ns/ttml#parameter' 
        xml:lang='eng'>
      <head>
        <ttm:title>Sample caption file</ttm:title>
        <metadata>
          <ttm:title>sampleTitle</ttm:title>
          <ttm:desc>This a sample TTML file.</ttm:desc>
          <ttm:copyright>Public Domain</ttm:copyright>
        </metadata>
      </head>
      <body>
        <div> 
        <p region='speaker' begin='00:00:00' end='00:00:031'>Caption 1 at 00:00:00</p>  
        </div>
        <div> 
        <p region='speaker' begin='00:00:05' end='00:00:08'>Caption 2 at 00:00:05</p>  
        </div>
        <div> 
        <p region='speaker' begin='00:00:10' end='00:00:13'>Caption 3 at 00:00:10</p>  
        </div>
        <div> 
        <p region='speaker' begin='00:00:15' end='00:00:18'>Caption 4 at 00:00:15</p>  
        </div>
      </body>
    </tt>

    SRT example

    The following example shows a simple SRT file (sample.srt) located in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL parameter is specified in the client URL, the SRT file must have the same name (and different file extension) as the asset file (for more information, see To specify the caption file to use in playback URLs).
    1
    00:00:00,000 --> 00:00:3,000
    SRT (0)
    
    2
    00:00:05 --> 00:00:08.000
    English (5)
    
    3
    00:00:10,000 --> 00:00:15,
    SRT (10)
    
    4
    00:00:20,000 --> 00:00:24,400
    Text at 20 seconds

    WebVTT example

    The following example shows a simple WebVTT file (sample.vtt) located in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL parameter is specified in the client URL, the WebVTT file must have the same name (and different file extension) as the asset file (for more information, see To specify the caption file to use in playback URLs).
    WEBVTT
    
    0
    00:00:04.000 --> 00:00:09.500
    First cue
    
    1
    00:00:10.000 --> 00:00:15.000
    Lorem
    
    2
    00:00:25.000 --> 00:00:30.500
    ipsum
    
    3
    00:01:05.500 --> 00:01:25.501
    Fourth caption

    SCC example

    The following example shows a simple SCC file (sample.scc) located in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL parameter is specified in the client URL, the WebVTT file must have the same name (and different file extension) as the asset file (for more information, see To specify the caption file to use in playback URLs).
    Scenarist_SCC V1.0
    
    00:00:01:09	9420 1370 9723 d04f d020 4fce 2043 c1d0 5449 4fce d380 94d0 9723 d04f d020 4fce 20c1 cec4 204f 4646 2054 c845 20d3 4352 4545 ceae 9420 942c 942f 9420 1370 97a2 54c8 45d9 20c1 5245 20d5 d345 c420 5749 54c8 20d0 524f c752 c1cd d380 94d0 97a2
    
    00:00:02:27	5749 54c8 20cd d54c 5449 d04c 4520 43c8 c152 c143 5445 52d3 ae80

    Closed captions configuration


    Configuring closed caption sources

    Wowza media server software supports VOD closed captioning through VODTimedTextProviders. Each provider ingests the timed text from a specific source type into the media server's generic timed text data model. Providers are included for assets with embedded 3GPP/MPEG-4 captions and external companion files. You can configure an application to include the providers required to ingest the desired sources. Note that the 3GPP provider is enabled by default.

    Wowza Streaming Engine Manager configuration


    1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your vod application (such as vod).

    2. In the Setup tab of the application details page, click Edit. Scroll down to the Closed Caption Sources section and select the caption providers you're using in your stream (3GPP, TTML, SRT, WebVTT, or SCC).

    3. Click Save and then restart the application when prompted.


    Application.xml configuration


    Note: If you configured captions in Wowza Streaming Engine Manager, skip this section. If you make changes to Application.xml and you're using the Wowza Streaming Engine™ software, any supported settings will be displayed in the manager the next time it's started. Wowza Media Server™ software doesn't support Wowza Streaming Engine Manager, so you must edit Application.xml in a text editor if you're running Wowza Media Server.
    The [install-dir]/conf/[application]/Application.xml file contains a <TimedText> container that allows you to configure the closed captioning providers and functionality. You can add the following caption providers:

    • vodcaptionprovidermp4_3gpp: Pulls captions directly from 3GPP tracks (codecID "tx3g") that are embedded in MP4 VOD assets. This option is enabled by default in Application.xml.

    • vodcaptionproviderttml: Pulls captions from an external TTML-formatted caption file in the same location as the VOD asset.

    • vodcaptionprovidersrt: Pulls captions from an external SRT-formatted caption file in the same location as the VOD asset.

    • vodcaptionproviderwebvtt: Pulls captions from an external WebVTT-formatted caption file in the same location as the VOD asset.

    • vodcaptionproviderscc: Pulls captions from an external SCC-formatted caption file in the same location as the VOD asset.

    <TimedText>
    	<!-- VOD caption providers (separate with commas): vodcaptionprovidermp4_3gpp, vodcaptionproviderttml, vodcaptionproviderwebvtt,  vodcaptionprovidersrt, vodcaptionproviderscc -->
    	<VODTimedTextProviders>vodcaptionprovidermp4_3gpp</VODTimedTextProviders>
    	
    	<!-- Properties for TimedText -->
    	<Properties>
    	</Properties>		
    </TimedText>
    You can specify multiple timed text providers. For example:
    <TimedText>
    	<!-- VOD caption providers (separate with commas): vodcaptionprovidermp4_3gpp, vodcaptionproviderttml, vodcaptionproviderwebvtt,  vodcaptionprovidersrt, vodcaptionproviderscc -->
    	<VODTimedTextProviders>vodcaptionprovidermp4_3gpp,vodcaptionproviderttml,vodcaptionproviderwebvtt,vodcaptionprovidersrt,vodcaptionproviderscc</VODTimedTextProviders>
    	
    	<!-- Properties for TimedText -->
    	<Properties>
    	</Properties>		
    </TimedText>
    For more information about timed text provider configuration, see Closed captioning configuration reference for video on demand streaming.

    Playback


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

    • Adobe Flash Player (RTMP) doesn't support closed captions natively.

    • To play your own content, copy it into the [install-dir]/content folder and substitute its file name for the sample.mp4 file in the sample URLs below.

    To play using JW Player (RTMP)

    Captioning plugins for RTMP streams may be required depending on the JW Player version.

    JW Player 6 (or later) can display closed captions in RTMP streams natively with no plugins. The following basic example specifies the full RTMP URL as the file property inside a playlist object:
    <div id="mediaplayer" ></div>
    <script type="text/javascript">
        jwplayer("mediaplayer").setup({
            playlist: [{
                file: 'rtmp://localhost:1935/vod/mp4:sample.mp4',
                title: 'sample.mp4',
            }],
            width: 854,
            height: 480,
        });
    </script>
    JW Player 5 can display closed captions in RTMP streams when you use the Longtail JWPlayer5 Captions plugin. Enable this plugin for your JW Player configuration by including it in the plugins declaration in the jwplayer() call in your webpage, as shown in the following example:
    <div id="mediaplayer" ></div>
    <script type="text/javascript">
        jwplayer("mediaplayer").setup({
            width: 854,
            height: 480,
            file: 'mp4:sample.mp4',
            streamer: 'rtmp://localhost:1935/vod',
            flashplayer: 'jwplayer/player.swf',
            plugins: {
                "jwplayer/captions.swf": {}
            }
        });
    </script>
    Because JW Player uses Flash, if you're running locally (as shown in the above examples), you must make the jwplayer/ folder accessible via Flash. To do this, right-click in the Flash window, and then select Global Settings > Advanced > Trusted Location Settings.

    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.

    RTMP streaming requires the following Flowplayer plugins:

    • rtmp: Provides support for RTMP streaming.
    • content: Defines a content region in which to place captions, either on top of or next to the video screen.
    • captions: Renders captions in the stream in the content region.

    Enable these plugins for your Flowplayer configuration by including them in the plugins declaration in the flowplayer() call in your webpage, as shown in the following example:
    <script type="text/javascript">
        flowplayer("flowplayer", "flowplayer/flowplayer-3.x.x.swf", {
        clip: {
            provider: 'rtmp',
            autoPlay: false,
            autoBuffering: false,
            scaling: 'fit',
            url: 'mp4:sample.mp4',
            },
        plugins: {
            // streaming plugin configuration
            rtmp: {
                url: "flowplayer/flowplayer.rtmp-3.x.x.swf",
                netConnectionUrl: 'rtmp://localhost:1935/vod'
            },
            captions: {
                url: 'flowplayer/flowplayer.captions-3.x.x.swf',
                captionTarget: 'content'
            },
            content: {
                url:'flowplayer/flowplayer.content-3.x.x.swf',
                bottom: '15%',
                width: '80%',
                height: 55,
                backgroundColor: 'transparent',
                backgroundGradient: 'none',
                border: 0,
                opacity: .90,
                textDecoration: 'outline',
                style: {
                    'body': {
                        fontSize: '18',
                        fontFamily: 'Verdana, Arial, Helvetica',
                        fontWeight: 'bold',
                        textAlign: 'center',
                        color: '#ffff00'
                        }
                    }
                }
            },
        logo: { 
            url: ''
            },
        }
    );
    </script>
    Adobe HDS streaming requires the following Flowplayer plugins:

    • f4m: Resolves the media URL contained in an Adobe F4M manifest file.
    • httpstreaming: Provides support for Adobe HDS streaming.
    • content: Defines a content region in which to place captions, either on top of or next to the video screen.
    • captions: Renders captions in the stream in the content region.

    Enable these plugins for your Flowplayer configuration by including them in the plugins declaration in the flowplayer() call in your webpage, as shown in the following example:
    <script type="text/javascript">
        flowplayer("flowplayer", "flowplayer/flowplayer-3.x.x.swf", {
        clip: {
            url: 'http://localhost:1935/vod/mp4:sample.mp4/manifest.f4m',
                    urlResolvers: ['f4m'],
            provider: 'httpstreaming',
            autoPlay: true,
            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%',
                width: '80%',
                height: 55,
                backgroundColor: 'transparent',
                backgroundGradient: 'none',
                border: 0,
                opacity: .90,
                textDecoration: 'outline',
                style: {
                    'body': {
                        fontSize: '18',
                        fontFamily: 'Verdana, Arial, Helvetica',
                        fontWeight: 'bold',
                        textAlign: 'center',
                        color: '#ffff00'
                        }
                    }
                }
            },
        logo: { 
            url: ''
            },
        }
    );
    </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. (Navigate to Settings > Video, and then set Closed Captioning to ON.)

    In a Safari web browser on the device, enter the following URL:
    http://[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8
    Notes:
    • The Apple iPhone 3GS (and older) and iPod touch devices require that video be encoded using H.264 format (Baseline profile level 3 or lower) and AAC or MP3 stereo audio.

    • This stream can also be played by using the Safari web browser or QuickTime 10.x on a computer that's running OS X Snow Leopard version 10.6 or later.

    To play embedded in HTML on Apple iOS (Apple HLS)

    In a Safari web browser, enter the URL of the webpage. For example:
    http://[website]/index.html
    The webpage should have an embedded <video> element defined, such as the following:
    <video src="[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8" controls>

    To specify the caption file to use in playback URLs

    Typically, the caption file used is the one in the [install-dir]/content directory with the same suffix (file name) as the VOD asset. You can specify that a caption file with a different name be used during playback. For example, to use a TTML caption file with a different name on an iOS device, you would enable the TTML timed text provider in your application configuration, and then from the command line add the wowzacaptionfile URL parameter:
    http://[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8?wowzacaptionfile=otherFile.ttml
    Note that language selection URL parameters still apply but only this file is parsed to determine the available languages.

    Troubleshooting


    Closed caption properties for debug logging

    You can add properties to your application to enable debug logging of closed captioning functionality.

    In Wowza Streaming Engine Manager, do the following:

    1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your vod application (such as vod).

    2. 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.
    3. In the Closed Captions section, click Edit.

    4. Enable the desired debug logging properties.

      Property
      Description
      debugVODCaptionLanguageSelection Enable/disable logging regarding caption language selection.
      debugVODCaptionProviderDetermination Enable/disable logging regarding caption provider determination for the VOD asset.
      debugVODCaptionFileDetermination Enable/disable logging regarding caption companion file determination for the VOD asset.
      debugTTMLCaptionParser Enables TTML caption parser logging.
      debug3GPPCaptionParser Enables 3GPP caption parser logging.

    5. Click Save, and then restart the application to apply the properties.


    As an alternative, you can define the properties in the application's configuration file (Application.xml) using a text editor. (If you're using Wowza Media Server software, you must use this method.) The following example shows the debug properties that you can define in the <Application>/<TimedText>/<Properties> section of the Application.xml file to enable useful debug logging:
    <!-- Properties for TimedText -->
    <Properties>
        <Property>
            <!-- Enable/disable logging regarding caption language selection -->
            <Name>debugVODCaptionLanguageSelection</Name>
            <Type>Boolean</Type>             
            <Value>true</Value>
        </Property>
        <Property>
            <!-- Enable/disable logging regarding caption provider determination for a given VOD asset -->
            <Name>debugVODCaptionProviderDetermination</Name>
            <Type>Boolean</Type>             
            <Value>true</Value>
        </Property>
        <Property>
            <!-- Enable/disable logging regarding caption companion file determination for a given VOD asset -->
            <Name>debugVODCaptionFileDetermination</Name>
            <Type>Boolean</Type>             
            <Value>true</Value>
        </Property>
        <Property>
            <!-- Enable/disable TTML caption parser logging -->
            <Name>debugTTMLCaptionParser</Name>
            <Type>Boolean</Type>             
            <Value>true</Value>
        </Property>
        <Property>
            <!-- Enable/disable 3GPP caption parser logging -->
            <Name>debug3GPPCaptionParser</Name>
            <Type>Boolean</Type>             
            <Value>true</Value>
        </Property>
    </Properties>
    For a complete list of Timed Text configuration options, see Closed captioning configuration reference for video on demand streaming.

    More resources



    Originally Published: 11-08-2012.
    Updated: For Wowza Streaming Engine 03-07-2014.

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