Use external caption files with Wowza Streaming Engine video-on-demand streams

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 Streaming Engine™ 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.

Configure the HTTP provider


  1. Open the [install-dir]/conf/VHost.xml file in a text editor.
  2. 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.
<HTTPProvider>
    <BaseClass>com.wowza.wms.timedtext.http.HTTPProviderCaptionFile</BaseClass>
    <RequestFilters>*.ttml|*.srt|*.scc|*.vtt</RequestFilters>
    <AuthenticationMethod>none</AuthenticationMethod>
</HTTPProvider>

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.

  1. Save and close VHost.xml, and then restart Wowza Streaming Engine.
  2. Add your caption files to the Wowza Streaming Engine content folder at [install-dir]/content.

Store 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:

http://[wowza-ip-address]:1935/vod/_definst_/subdir/myCaptions.ttml

Test the caption file


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/myCaptions.srt

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

Specify 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">
jwplayer("mediaplayer").setup({
file: 'mp4:sample.mp4',
flashplayer: 'jwplayer5/player.swf',
height: 300,
plugins: {
'jwplayer5/captions.swf': {
files: "http://[<em>wowza-ip-address</em>]:1935/vod/sample_eng.srt,http://[<em>wowza-ip-address</em>]:1935/sample_vod/sample_kor.srt",
labels: "English,Korean",
}
},
streamer: 'rtmp://[<em>wowza-ip-address</em>]:1935/vod',
width: 400
});
</script>

Specify external caption files in HTML5


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 Wowza Streaming Engine.

<video width=400 height=300
src="http://[<em>wowza-ip-address</em>]:1935/vod/mp4:sample.mp4/playlist.m3u8">
<track kind="subtitles" label="English subtitles"
src="http://[<em>wowza-ip-address</em>]:1935/vod/sample_eng.vtt" srclang="eng" default></track>
<track kind="subtitles" label="Korean subtitles"
src="http://[<em>wowza-ip-address</em>]:1935/vod/sample_kor.vtt" srclang="kor"></track>
</video>