Closed captioning for Wowza VOD streams

Wowza Streaming Engine™ media server software can ingest caption data from a variety of in-stream and file-based sources, and then convert that caption data to the appropriate format for video-on-demand (VOD) streaming using Apple HLS or RTMP.

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. Wowza Streaming Engine supports the following input sources and output formats for closed captions in VOD streams.

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:

Wowza Streaming Engine does not support using multiple caption languages with SRT and SCC caption sources for VOD streams.
Only iOS-based players support interpretation and rendering of SEI data as CEA-608 captions.
iOS players don't support multibyte 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 RTMP VOD streams

Supported caption translations

The following table summarizes the input-to-output caption translations that are supported by Wowza Streaming Engine.

Outputs ˃ Inputs ˅	Apple HLS (CEA-608 in video)	RTMP (onTextData)
Embedded 3GPP tracks	√	√
Embedded CEA-608	√	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 Streaming Engine 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 or sample.smil). 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) located in the same content directory as its associated VOD asset file (sample.mp4 or sample.smil). 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 Specify the caption file to use in playback URLs.

Note: Wowza Streaming Engine supports timed text markers in the following format: hh:mm:ss:mss.

<?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:03'>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 or sample.smil). 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 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 or sample.smil). 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 Specify the caption file to use in playback URLs.

Note: Wowza Streaming Engine does not support closed captioning in MPEG-DASH streams.

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 or sample.smil). 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 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 Streaming Engine 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

In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your VOD application.
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).
Click Save and then restart the application.

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, any supported settings will be displayed in Wowza Streaming Engine Manager the next time it's started.

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 property reference for Wowza Streaming Engine video-on-demand streams.

Playback

Notes:

Each player may have unique user controls to enable/disable caption rendering and/or caption language selection.
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.

Play on an Apple iOS device (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 Safari on the device, enter the following URL:

http://[address]:1935/[application-name]/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 Safari or QuickTime 10.x on a computer that's running OS X Snow Leopard version 10.6 or later.

Play embedded in HTML on Apple iOS (HLS)

In Safari, 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="[address]:1935/myApplication/mp4:sample.mp4/playlist.m3u8" controls>

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 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://[address]:1935/[application-name]/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.

Specify the caption file to use in SMIL files

For adaptive bitrate streaming with captions, you can't use URL query parameters. Instead, you must define your captions within the SMIL file. The following example defines TTML captions in a SMIL file that provides English and French content. It's added as a single entry at the end of your SMIL file, just above the closing switch (</switch>):

<textstream src="myStream" system-language="eng,fra">
<param name="isWowzaCaptionStream" value="true" valuetype="data"></param>
<param name="wowzaCaptionIngestType" value="onTextData" />
</textstream>

Note: To specify multiple caption languages for TTML or WebVTT, the languages must also be specified in the caption file, and the value of system-language in the SMIL file must match. Wowza Streaming Engine does not support using multiple caption languages with SRT and SCC caption sources for VOD streams.

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, click the Applications tab, and then click the name of your VOD application.
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.
In the Closed Captions section, click Edit.

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	Enable TTML caption parser logging.
debug3GPPCaptionParser	Enable 3GPP caption parser logging.

Click Save, and then restart the application.

As an alternative, you can define the properties in the application's configuration file (Application.xml) using a text editor. 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 property reference for Wowza Streaming Engine video-on-demand streams.

Configure closed captioning for Wowza Streaming Engine video-on-demand streams

Supported caption types

Supported input sources

Supported outputs

Supported caption translations

How it works

External companion file setup

TTML example

SRT example

WebVTT example

SCC example

Closed captions configuration

Configuring closed caption sources

Wowza Streaming Engine Manager configuration

Application.xml configuration

Playback

Play on an Apple iOS device (HLS)

Play embedded in HTML on Apple iOS (HLS)

Specify the caption file to use in playback URLs

Specify the caption file to use in SMIL files

Troubleshooting

Closed caption properties for debug logging

More resources

Popular Video Topics

Video Resources

Partners

Company

Stay Connected

Stay Up to Date with the Blog