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

Updated on 08/11/2026 9:41 am PDT

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

Supported caption types

There are many types of closed caption sources. Streaming standard may use a different format for embedding captions on the output. WSE supports the following input sources and output formats for closed captions in VOD streams.

Supported input sources

Embedded captions:

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

Captions defined in an external file:

  • Timed Text Markup Language (TTML)
  • SubRip Text (SRT)
  • Web Video Text Tracks (WebVTT)
  • Scenarist Closed Caption (SCC) 
Notes:
  • WSE does not support using multiple caption languages with SRT and SCC caption sources for VOD streams.
  • iOS-based players support interpretation and rendering of SEI data as CEA-608 captions, other players do not.
  • 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 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 ˅		 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

A closed caption provider ingests the timed text from a specific source type into the media server's generic timed text data model. A provider may source 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. See the closed captions configuration section below for steps to configure your close caption provider. (Note: 3GPP provider is enabled by default.)

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 example below shows a TTML file (sample.ttml) located in the same content directory as its 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: WSE 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: WSE 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

WSE 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 using WSE Manager or by directly editing your app's configuration file. (Note: 3GPP is enabled by default.)

Configure CC using WSE Manager

  1. Open WSE Manager.
  2. Click the Applications tab.
  3. Click the name of your VOD application.
     
  4. In the Setup tab, click Edit.
  5. Scroll down to the Closed Captions section and select your stream's caption provider(s)  (3GPP, TTML, SRT, WebVTT, or SCC).
     
  6. Click Save.
  7. Restart the application.

Configure CC by editing Application.xml

An app's closed caption configuration settings are stored in the <TimedText> element of its Application.xml file. Changes made directly to an app's Application.xml file will be displayed in WSE Manager the next time it's started.

To select one or more caption provider(s), add the provider or a comma-separated list of providers to the <VODTimedTextProviders> element inside <TimedText>.

The following caption providers are supported:

  • vodcaptionprovidermp4_3gpp: Source captions from 3GPP tracks (codecID "tx3g") embedded in the MP4 asset. (Default)
  • vodcaptionproviderttml: Source captions from an external TTML caption file.
     
  • vodcaptionprovidersrt: Source captions from an external SRT caption file.
  • vodcaptionproviderwebvtt: Source captions from an external WebVTT caption file..
     
  • vodcaptionproviderscc: Source captions from an external SCC caption file.
<!-- Source captions from a 3GPP track directly embedded in the mp4 file -->

<TimedText>
  <VODTimedTextProviders>vodcaptionprovidermp4_3gpp</VODTimedTextProviders>
</TimedText>


<!-- Support multiple caption sources -->

<TimedText>
  <VODTimedTextProviders>vodcaptionprovidermp4_3gpp,vodcaptionproviderttml,vodcaptionproviderwebvtt,vodcaptionprovidersrt,vodcaptionproviderscc</VODTimedTextProviders>	
</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 or disable caption rendering and select the caption language.
  • 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 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

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 is 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 containing 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.

  1. Open WSE Manager.
  2. Click the Applications tab.
  3. Click the name of your VOD application.
     
  4. Click the Properties tab.
  5. In the Quick Links bar, click Closed Captions.

  6. Click Edit.
     
  7. 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.
  8. Click Save, and then restart the application.

Alternatively, 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.

More resources

Was this article helpful?
Thank you for your feedback!
User Icon

Thank you for providing feedback to help us improve our documentation!

© 2007–2025 Wowza Media Systems™, LLC. All rights reserved.   Security & Privacy PolicyLegalSystem Status