• How to configure closed captioning for video on demand streaming

    Wowza Media Server includes support for closed captioning for video-on-demand (VOD) streams. It can ingest caption data from a variety of in-stream and file-based sources and convert it to the appropriate caption format for on-demand video streaming using the Apple HTTP Live Streaming (Apple HLS), Adobe HTTP Dynamic Streaming (Adobe HDS), and RTMP protocols.

    Note: Wowza Media Server™ 3.5 or later is required.

    Contents



    Introduction
    How It Works

    Configuration
    Supported Players

    Playback

    Troubleshooting
    More resources

    Introduction



    There are many types of closed caption sources, and each streaming standard may use a different format for embedding captions on the output side. The closed captioning feature in Wowza Media Server for VOD supports the following input sources and output formats.

    Supported input sources

    • Captions embedded within a VOD file:
      • 3GPP/MPEG-4 Timed Text tracks
      • CEA-608 captions as SEI data within a video track. This caption data is passed-through to the output video streams.
        Note: Only Apple iOS-based players support interpretation of SEI data as CEA-608 captions; therefore, they are the only players that can render these captions.
        Note: iOS players don't support multi-byte languages.

    • Captions defined in an external companion file:

    Supported outputs (translated from any of the supported input sources)

    • CEA-608-formatted SEI data within the video track in Apple HLS (Cupertino) VOD streams
    • onTextData events in Adobe HDS (San Jose) and RTMP VOD streams


    The following table summarizes the input-to-output caption translations that are supported by Wowza Media Server:

    Supported caption translations

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

    Future releases of Wowza Media Server may support additional input and output sources/formats.

    How It Works



    Wowza Media Server supports VOD closed captioning through VODTimedTextProviders. Each provider knows how to ingest the timed text from a specific source type into Wowza's generic timed text data model. Wowza Media Server includes providers for assets with embedded 3GPP/MPEG-4 captions and one for assets with external companion files. An application can be configured to include the provider(s) required to ingest the desired sources (For more information, see Configuration). Note that the 3GPP provider is "enabled" by default in released configuration files.

    TTML example

    The following example shows a simple TTML file. This file (sample.ttml) would be placed in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL param is specified in the client URL, the TTML file must have the same name as the asset file, differing only in the file extension.
    <?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. This file (sample.srt) would be placed in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL param is specified in the client URL, the SRT file must have the same name as the asset file, differing only in the file extension.
    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. This file (sample.vtt) would be placed in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL param is specified in the client URL, the WebVTT file must have the same name as the asset file, differing only in the file extension.
    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. This file (sample.scc) would be placed in the same content directory as its associated VOD asset file (sample.mp4). Note that unless the wowzacaptionfile URL param is specified in the client URL, the SCC file must have the same name as the asset file, differing only in the file extension.
    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
    Note: Support for SCC files was added to Wowza Media Server 3.6.

    Configuration



    Configuring Application.xml

    The [install-dir]/conf/[application]/Application.xml file contains a <TimedText> section to allow configuration of the closed captioning "providers" and functionality. The following providers can be defined for use:

    • vodcaptionprovidermp4_3gpp. Pulls captions directly from 3GPP tracks (codecID "tx3g") that are embedded in MP4 VOD assets. This option is enabled by default in the Application.xml file.
    • vodcaptionproviderttml. Pulls captions from an external TTML-formatted caption file that sits next to VOD asset.
    • vodcaptionprovidersrt. Pulls captions from an external SRT-formatted caption file that sits next to VOD asset.
    • vodcaptionproviderwebvtt. Pulls captions from an external WebVTT-formatted caption file that sits next to VOD asset.
    • vodcaptionproviderscc. Pulls captions from an external SCC-formatted caption file that sits next to 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>
    Multiple timed text providers can be specified as shown in the following 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>
    Configuring TimedTextProviders.xml

    The default TimedTextProviders configuration should be sufficient for most closed captioning scenarios and shouldn't need to be modified under normal circumstances. For more information about Timed Text Provider configuration, see the Wowza Media Server Configuration Reference.

    Supported Players



    • iOS players can display captions from CEA-608 messages in Apple HLS (Cupertino) streams after enabling closed captioning on the device. Go to Settings > Video, and set Closed Captioning to ON.
    • JW Player can display captions in RTMP streams when the appropriate captioning plugin is used. For more information, see To play using JW Player (RTMP).
    • Flowplayer can display captions in RTMP and Adobe HDS (San Jose) streams when the appropriate captioning and streaming plugins are used. For more information, see To play using Flowplayer (RTMP and Adobe HDS/San Jose).


    Playback



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

    Note: To enable captioning for a VOD asset using an external caption file, remember to do the following:
    1. Place the TTML (.ttml), SRT (.srt), or SCC (.scc) caption file next to the video asset file in the [install-dir]/content folder and ensure that the root filename 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.
    2. In your Application.xml file, define the appropriate VODTimedTextProvider for the caption file type. For more information, see Configuring Application.xml.

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

    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 6 can display closed captions in RTMP streams natively with no plugins. The following recommended 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 Longtail's JWPlayer5 Captions plugin. This plugin can be enabled 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 (right-click on the Flash window > Global Settings > Advanced > Trusted Location Settings).

    To play using Flowplayer (RTMP and Adobe HDS/San Jose)


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

    For RTMP streaming, the following Flowplayer plugins are required:

    • 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.

    These plugins can be enabled 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.2.15.swf", {
        clip: {
            provider: 'rtmp',
            autoPlay: false,
            autoBuffering: false,
            scaling: 'fit',
            url: 'mp4:sample.mp4',
            },
        plugins: {
            // streaming plugin configuration
            rtmp: {
                url: "flowplayer/flowplayer.rtmp-3.2.11.swf",
                netConnectionUrl: 'rtmp://localhost:1935/vod'
            },
    
            captions: {
                url: 'flowplayer/flowplayer.captions-3.2.9.swf',
                captionTarget: 'content'
            },
            content: {
                url:'flowplayer/flowplayer.content-3.2.8.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>
    For Adobe HDS (San Jose) streaming, the following Flowplayer plugins are required:

    • f4m. Resolves the media URL contained in a Adobe F4M manifest file.
    • httpstreaming. Provides support for Adobe HDS (San Jose) 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.

    These plugins can be enabled 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.2.15.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.2.9.swf" 
            },
            httpstreaming: {
                url: "flowplayer/flowplayer.httpstreaming-3.2.9.swf"
            },
            captions: {
                url: 'flowplayer/flowplayer.captions-3.2.9.swf',
                captionTarget: 'content'
            },
            content: {
                url:'flowplayer/flowplayer.content-3.2.8.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/Cupertino)


    Enter the following URL in a Safari web browser:
    http://[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8
    Note: This stream can also be played by using the Safari web browser or QuickTime 10 on a computer that's running OS X Snow Leopard version 10.6 or later.

    Note: The iPhone 3GS (and older) and iPod touch devices require that the video be encoded using H.264 format (Baseline Profile level 3 or lower) and AAC or MP3 stereo audio.

    To play embedded in HTML on Apple iOS (Cupertino/Apple HTTP Live Streaming)


    Enter the URL of the webpage in a Safari web browser. 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>

    Specifying a specific caption file


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

    Troubleshooting



    TimedText Properties for Debug


    The following example shows some basic debug properties that can be defined 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>
            </Properties>
    For a complete list of Timed Text configuration options, see Closed captioning configuration reference for video on demand streaming.


    Originally Published: 11-08-2012.
    Updated: For Wowza Media Server 3.6.0 on 05-28-2013.

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