• How to serve sidecar caption files for video on demand streaming

    Some player technologies allow a caption file to be specified as a URL and served as a separate HTTP request to the player. This article describes how to use the HTTPProviderCaptionFile HTTP provider in Wowza Media Server to enable the server to serve pull the requested caption file from its [install-dir]/content folder and serve the file to the player.

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

    Contents



    Configuration

    Players

    Configuration



    Configuring VHost.xml


    In Wowza Media Server, add the following HTTPProviderCaptionFile section to the [install-dir]/conf/VHost.xml file under VHost/HostPortList/HostPort/HTTPProviders. Put it under the port that you want to use (for example, port 1935). Note that the HTTPServerVersion section must come AFTER the HTTPProviderCaptionFile section.
    <HTTPProvider>
        <BaseClass>com.wowza.wms.timedtext.http.HTTPProviderCaptionFile</BaseClass>
        <RequestFilters>*.ttml|*.srt|*.scc|*.vtt</RequestFilters>
        <AuthenticationMethod>none</AuthenticationMethod>
    </HTTPProvider>
    Add the file extensions that you want to be returned in <RequestFilters>. In the above example, the HTTP provider will look for caption files with .ttml, .srt, .scc, and .vtt file extensions.

    Now add any caption files to the Wowza Media Server [install-dir]/content folder.

    Testing the provider


    You should test this outside of the player to verify that the caption file is returned. After starting Wowza Media Server, request the caption file with the proper http syntax. For example, you could use Wget or cURL from a command-line to see if the file contents are returned.
    curl http://[wowza-ip-address]:1935/vod/myCaptions.srt

    Specifying subdirectories


    If you want to store files in subdirectories of the the [install-dir]/content folder, be aware that the request URL must contain the application instance, which is typically "_definst_". For example, if sample.ttml is placed in the [install-dir]/content/subdir folder, it would be accessed via /vod/_definst_/subdir/sample.ttml.

    To test it:
    curl http://[wowza-ip-address]:1935/vod/_definst_/subdir/sample.ttml

    Players



    Specifying external caption files in JW Player


    JW Player 5 or later can also specify external caption files, using the SRT format. The HTML script code to embed JW Player using external code to embed a VOD asset streamed with Apple HLS, with 2 separate SRT caption files served from Wowza Media Server, would look like this:
    <script type="text/javascript">
    jwplayer("mediaplayer").setup({
        file: 'mp4:sample.mp4',
        flashplayer: 'jwplayer5/player.swf',
        height: 300,
        plugins: {
        'jwplayer5/captions.swf': {
           files: "http://[wowza-ip-address]:1935/vod/sample_eng.srt,http://[wowza-ip-address]:1935/sample_vod/sample_kor.srt",
           labels: "English,Korean",
        }
        },
        streamer: 'rtmp://[wowza-ip-address]:1935/vod',
        width: 400
    });
    </script>

    Specifying external caption files in HTML5


    Note: Currently the only browser that we think supports data tracks in HTML5 video tags is Safari on OS X.

    Note: HTML5 video support is still in flux. Different browsers support different functionality for the video tag. LongTail Video has a great The State of HTML5 Video webpage where you can get more information.

    The HTML code to embed a VOD asset streamed with Apple HLS, with 2 separate WebVTT caption files served from Wowza Media Server, would look like this:
    <video width=400 height=300
            src="http://[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8">
        <track kind="subtitles" label="English subtitles" 
                src="http://[wowza-ip-address]:1935/vod/sample_eng.vtt" srclang="eng" default></track>
        <track kind="subtitles" label="Korean subtitles" 
                src="http://[wowza-ip-address]:1935/vod/sample_kor.vtt" srclang="kor"></track>
    </video>

    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.