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 software to enable the server to pull the requested caption file from its [install-dir]/content folder and stream the caption text to the player.

Note: Wowza Streaming Engine™ 4.7.1 or later is required.


Configuring Wowza media server to use external caption files Playback

Configuring Wowza media server to use external caption files

Configuring the HTTP provider in VHost.xml

  1. Use a text editor to open the [install-dir]/conf/VHost.xml file and add the following HTTPProviderCaptionFile definition to the <VHost>/<HostPortList>/<HostPort>/<HTTPProviders> container. Be sure to put the HTTP provider in the <HostPort> container with the <Port> value that you want to use (for example, port 1935). You must place the new HTTPProviderCaptionFile definition before the HTTPServerVersion HTTP provider definition.
  2. Add the file extensions to be returned in <RequestFilters>. Separate each file extension with a pipe (|) character. In the above example, the HTTP provider will look for caption files with .ttml, .srt, .scc, and .vtt file extensions.
  3. Save and close the VHost.xml file, and then restart the media server to apply the changes.
  4. Add your caption files to the Wowza media server content folder ([install-dir]/content).

Storing caption files in subdirectories

If you want to store files in subdirectories in [install-dir]/content, add the application instance (_definst_ by default) and the name of the subdirectory folder after the application name in the stream URL. The following example uses a caption file named myCaptions.ttml located in [install-dir]/content/subdir:

Testing caption file return

Test your HTTP provider configuration outside of players to verify that the caption file is returned correctly. To do this, use a Wget or cURL command from a command line. For example:
curl http://[wowza-ip-address]:1935/vod/
To test for correct caption file return when using a subdirectory, use a cURL command with the following format:
curl http://[wowza-ip-address]:1935/vod/_definst_/subdir/myCaptions.ttml


Specifying external caption files in JW Player

JW Player 5 and later can specify external caption files using the SRT format. The following example HTML code uses JW Player and external caption code to embed a VOD asset with two SRT caption files streamed with Apple HLS from a Wowza media server.
<script type="text/javascript">
    file: 'mp4:sample.mp4',
    flashplayer: 'jwplayer5/player.swf',
    height: 300,
    plugins: {
    'jwplayer5/captions.swf': {
       files: "http://[wowza-ip-address]:1935/vod/,http://[wowza-ip-address]:1935/sample_vod/",
       labels: "English,Korean",
    streamer: 'rtmp://[wowza-ip-address]:1935/vod',
    width: 400

Specifying external caption files in an HTML5 <video> tag

Use the <track> HTML tag to specify subtitles or captions in a <video> object. The following example HTML code embeds a VOD asset with two WebVTT caption files streamed over Apple HLS from a Wowza media server.
<video width=400 height=300
    <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>

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