How to configure closed captioning language selection for video on demand streaming

A video on demand (VOD) asset can have multiple closed captioning or subtitling language tracks associated with it. Captions are either embedded in the asset file itself or in a separate companion file. This article describes how to configure Wowza Streaming Engine™ media server software to make each of these caption language tracks available to various players.

  • Wowza Streaming Engine software or Wowza Media Server™ software (3.5.0 or later) is required.
  • Wowza Streaming Engine can ingest multiple languages but can only provide one caption language track at a time in the output stream.
  • While Wowza Streaming Engine can make captions available to various players; however, only iOS devices using Apple HLS (Cupertino) streaming will support CEA-608 captions in MP4 assets.


Supported language codes
Caption language selection Multi-language caption files
More resources

Supported language codes

Wowza Streaming Engine generally supports language codes specified as ISO 639-1, ISO 639-2/T, or ISO 639-2/B codes (for example, "fr", "fra", "fre"). User selection and server configuration of language codes specifically require that you use 3-letter ISO 639-2/T or 639-2/B codes; however, input caption files may specify other language code formats, including 2-letter (ISO 639-1) and 4+ letter formats. To support legacy caption files, when Wowza Streaming Engine ingests 4+ letter format caption data, it will truncate anything after the first two characters of the provided language code and treat the remainder as a 2-letter ISO 639-1 code, and then convert that to a 3-character ISO 639-2/T code for storage and playback.

For best results, we recommend using three-character ISO 639-2/T language IDS when possible.

Caption language selection

The caption language that's provided depends on a combination of specific client selections and Wowza Streaming Engine media server configuration.

Specifying a caption language with URL parameters

The caption language can be specified in the URL that is used by a player. The wowzacaptionlanguages URL parameter will overwrite language codes defined in your application'scaption language properties. For example:

Specifying a caption language in Wowza Streaming Engine Manager

To set up closed captioning language selection:
  1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your vod application (such as vod).
  2. 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.
  3. In the Closed Captions section, click Edit.
  4. Enable captionLanguages and set its value to a 3-letter language code or a comma-separated list of language codes. Wowza Streaming Engine will use the first language in the list that contains caption data.
    Note: You can also enable and set a backup language with the captionUnidentifiedLanguageID property. Wowza Streaming Engine looks for captions with this language if no language is set in the stream URL or asset file and the languages specified in captionLanguages aren't recognized. If captionUnidentifiedLanguageID isn't defined, the media server's locale's 3-character language code is used.
  5. Click Save, and then restart the application to apply the changes. 
Note: If no caption language is defined in the stream URL or in the application's properties, Wowza Streaming Engine uses the first caption language it finds in the first caption source it checks within the source media. The caption source it checks first is based on the order of Closed Caption Sources in the application's Setup tab). For more information on configuring caption sources, see How to configure closed captioning for video on demand streaming.

Specifying a caption language in Application.xml

Note: If you specified caption languages in Wowza Streaming Engine Manager above, skip this section. If you make changes to Application.xml and you're using the Wowza Streaming Engine™ software, any supported settings will be displayed in the manager the next time it's started. Wowza Media Server™ software doesn't support Wowza Streaming Engine Manager, so you must edit Application.xml in a text editor if you're running Wowza Media Server.
To specify a list of caption languages:
  1. In a text editor, open the [install-dir]/conf/Application.xml file and locate the <Application>/<TimedText>/<Properties> container in the file. The sample code below uses English, Spanish, and Dutch languages.
    <!-- Properties for TimedText -->
    The captionLanguages property can be set to any 3-character ISO-639 code (for example, eng) or a prioritized list of language codes. Wowza Streaming Engine will use the first language in the list that contains caption data.
  2. Save and close the file, and then restart the media server to apply the changes.
Note: When captionLanguages isn't defined (or is set to *) and a language isn't defined in the stream URL, the media server will use the first caption language it finds in the first caption source it checks within the source media. The caption source it checks first is based on the order of caption providers in the VODTimedTextProviders list and on the order of the languages found when the captions are ingested from these providers. For more information on configuring timed text providers, see How to configure closed captioning for video on demand streaming.

Specifying caption languages per-protocol

Video on demand caption languages can also be specified on a per-protocol basis by adding the cupertinoCaptionLanguages, rtmpCaptionLanguages, and sanJoseCaptionLanguages properties to your application. Set the value of these properties to a 3-character ISO-639 code (for example, eng) or a prioritized list of language codes. Wowza Streaming Engine will use the first language in the list that contains caption data.

To specify closed caption languages to use for a specific streaming protocol:
  1. Use a text editor to open the [install-dir]/conf/Application.xml file for your on-demand application and add the appropriate caption language property to the <Application>/<TimedText>/<Properties> container. Be sure to add it to the correct <Properties> container in Application.xml as there are several such containers in the file.
  2. Save and close the file, and then restart the media server to apply the changes. 

Caption languages for Apple HLS streams

cupertinoCaptionLanguages defines the default language to be used for Apple HLS (Cupertino) streaming if you don't define a language in the stream URL. The value can contain a prioritized list of language codes (such as eng, spa, dut).
<!-- Properties for TimedText -->

Caption languages for RTMP streams

rtmpCaptionLanguages defines the default language to be used for RTMP streaming if you don't define a language in the stream URL. The value can contain a prioritized list of language codes (such as eng, spa, dut).
<!-- Properties for TimedText -->

Caption languages for Adobe HDS streams

sanJoseCaptionLanguages defines the default language to be used for Adobe HDS (San Jose) streaming if you don't define a language in the stream URL. The value can contain a prioritized list of language codes (such as eng, spa, dut).
<!-- Properties for TimedText -->

Using multi-language caption files

The following example shows a complete TTML caption file containing multiple sets of caption languages. For this example, the TTML caption file reader in Wowza Streaming Engine ingests all five language renditions (eng, fra, spa, deu, and nor) and makes them available for playback.
<?xml version="1.0" encoding="utf-8"?>
<tt xmlns="" xmlns:ttp="" ttp:timeBase="media" xmlns:tts="" xmlns:ttm="">
      <style id="s0" tts:backgroundColor="black" tts:fontStyle="normal" tts:fontSize="16" tts:fontFamily="sansSerif" tts:color="white" />
  <body tts:textAlign="center" style="s0">
    <div xml:lang="eng">
      <p begin="00:00:03.680" id="p0" end="00:00:04.480">one man</p>
      <p begin="00:00:04.480" id="p1" end="00:00:05.280">on a motorcycle</p>
      <p begin="00:00:05.280" id="p2" end="00:00:06.880">around the world</p>
      <p begin="00:00:06.880" id="p3" end="00:00:08.480">in</p>
      <p begin="00:00:08.480" id="p4" end="00:00:12.480">A Quest for Gameplay</p>
      <p begin="00:00:13.000" id="p5" end="00:00:14.800">Hello I'm Tim Hull.</p>
      <p begin="00:00:15.000" id="p6" end="00:00:18.000">I believe the games we play<br />are a fundamental building block</p>
      <p begin="00:00:18.040" id="p7" end="00:00:19.600">of our civilisation.</p>
      <p begin="00:00:19.960" id="p8" end="00:00:23.160">I've set out on a global journey<br />that is my personal mission</p>
      <p begin="00:00:23.200" id="p9" end="00:00:25.920">to seek out, uncover, observe</p>
      <p begin="00:00:25.960" id="p10" end="00:00:27.280">and play games.</p>
      <p begin="00:00:27.800" id="p11" end="00:00:32.280">I'm searching for games that tell<br />us about our history culture and psyche.</p>
      <p begin="00:00:33.200" id="p12" end="00:00:38.000">During my journey I'll reveal stories<br />of the greatest games ever conceived</p>
      <p begin="00:00:38.040" id="p13" end="00:00:39.600">and why they are still with us today.</p>
      <p begin="00:00:40.200" id="p14" end="00:00:44.040">From the school playground<br />to the home console I will learn firsthand</p>
      <p begin="00:00:44.080" id="p15" end="00:00:47.200">what makes a great game,<br />why games are good for us</p>
      <p begin="00:00:47.240" id="p16" end="00:00:49.040">and what they tell us about ourselves</p>
      <p begin="00:00:49.240" id="p17" end="00:00:51.800">as well as being lots of fun.</p>
    <div xml:lang="fra">
      <p begin="00:00:03.680" id="p0" end="00:00:04.480">Un homme</p>
      <p begin="00:00:04.480" id="p1" end="00:00:05.280">sur une moto</p>
      <p begin="00:00:05.280" id="p2" end="00:00:06.880">autour du monde</p>
      <p begin="00:00:06.880" id="p3" end="00:00:08.480">en</p>
      <p begin="00:00:08.480" id="p4" end="00:00:13.000">quête de jeux</p>
      <p begin="00:00:13.000" id="p5" end="00:00:15.000">Bonjour. Je suis Tim Hull.</p>
      <p begin="00:00:15.000" id="p6" end="00:00:18.040">Je crois que les jeux auxquels<br />nous jouons sont un pilier fondamental</p>
      <p begin="00:00:18.040" id="p7" end="00:00:19.960">de notre civilisation.</p>
      <p begin="00:00:19.960" id="p8" end="00:00:23.200">Je me suis lancé dans un voyage<br />global qui est ma mission personnelle</p>
      <p begin="00:00:23.200" id="p9" end="00:00:25.960">pour rechercher, découvrir, observer</p>
      <p begin="00:00:25.960" id="p10" end="00:00:27.800">et jouer.</p>
      <p begin="00:00:27.800" id="p11" end="00:00:33.200">Je suis à la recherche de jeux qui nous<br />racontent de notre histoire, culture et psyché.</p>
      <p begin="00:00:33.200" id="p12" end="00:00:38.040">Pendant mon voyage je dévoilerai<br />les plus grands jeux que l’homme ait conçu</p>
      <p begin="00:00:38.040" id="p13" end="00:00:40.200">et de pourquoi ils perdurent jusqu’à ce jour.</p>
      <p begin="00:00:40.200" id="p14" end="00:00:44.080">De la cour de récréation à la console informatique,<br />je vais apprendre de première main</p>
      <p begin="00:00:44.080" id="p15" end="00:00:47.240">ce qui fait un grand jeu,<br />pourquoi les jeux nous font du bien</p>
      <p begin="00:00:47.240" id="p16" end="00:00:49.240">et ce qu’ils nous révèlent de nous-mêmes,</p>
      <p begin="00:00:49.240" id="p17" end="00:00:51.800">tout en étant super amusants.</p>
    <div xml:lang="spa">
      <p begin="00:00:03.680" id="p0" end="00:00:04.480">un hombre</p>
      <p begin="00:00:04.480" id="p1" end="00:00:05.280">en moto</p>
      <p begin="00:00:05.280" id="p2" end="00:00:06.880">dando la vuelta al mundo</p>
      <p begin="00:00:06.880" id="p3" end="00:00:08.480">en</p>
      <p begin="00:00:08.480" id="p4" end="00:00:13.000">búsqueda de juegos</p>
      <p begin="00:00:13.000" id="p5" end="00:00:15.000">Hola! soy Tim Hull.</p>
      <p begin="00:00:15.000" id="p6" end="00:00:18.040">Estoy convencido de que los juegos<br />son cimientos fundamentales</p>
      <p begin="00:00:18.040" id="p7" end="00:00:19.960">de nuestra civilización.</p>
      <p begin="00:00:19.960" id="p8" end="00:00:23.200">Emprendí este viaje alrededor<br />del mundo como una misión personal</p>
      <p begin="00:00:23.200" id="p9" end="00:00:25.960">para buscar, descubrir, observar</p>
      <p begin="00:00:25.960" id="p10" end="00:00:27.800">y jugar a juegos.</p>
      <p begin="00:00:27.800" id="p11" end="00:00:33.200">Estoy buscando juegos que nos hablen<br />de nuestra historia, cultura y psique.</p>
      <p begin="00:00:33.200" id="p12" end="00:00:38.040">Durante mi viaje desvelaré historias<br />de los mejores juegos jamás concebidos</p>
      <p begin="00:00:38.040" id="p13" end="00:00:40.200">y de la razón para que aún sigan con nosotros</p>
      <p begin="00:00:40.200" id="p14" end="00:00:44.080">Del patio del colegio hasta la consola,<br />aprenderé de sus protagonistas</p>
      <p begin="00:00:44.080" id="p15" end="00:00:47.240">aquello que hace que un juego sea fenomenal,<br />lo que los hace buenos para nosotros</p>
      <p begin="00:00:47.240" id="p16" end="00:00:49.240">lo que expresan sobre nosotros mismos</p>
      <p begin="00:00:49.240" id="p17" end="00:00:51.800">y también porqué son tan divertidos.</p>
    <div xml:lang="deu">
      <p begin="00:00:03.680" id="p0" end="00:00:04.480">Ein Mann</p>
      <p begin="00:00:04.480" id="p1" end="00:00:05.280">auf einem Motorrad</p>
      <p begin="00:00:05.280" id="p2" end="00:00:06.880">rund um die Welt</p>
      <p begin="00:00:06.880" id="p3" end="00:00:08.480">auf</p>
      <p begin="00:00:08.480" id="p4" end="00:00:13.000">einer Suche nach Spielen</p>
      <p begin="00:00:13.000" id="p5" end="00:00:15.000">Hallo, ich heiße Tim Hull.</p>
      <p begin="00:00:15.000" id="p6" end="00:00:18.040">Ich glaube, dass unsere Spiele<br />ein wichtiger Grundstein</p>
      <p begin="00:00:18.040" id="p7" end="00:00:19.960">unserer Zivilisation sind.</p>
      <p begin="00:00:19.960" id="p8" end="00:00:23.200">Ich reise rund um die Welt,<br />und es ist meine Mission,</p>
      <p begin="00:00:23.200" id="p9" end="00:00:25.960">Spiele zu entdecken, zu beobachten</p>
      <p begin="00:00:25.960" id="p10" end="00:00:27.800">und zu spielen.</p>
      <p begin="00:00:27.800" id="p11" end="00:00:33.200">Ich suche Spiele, die etwas über unsere<br />Geschichte, Kultur und Psyche erzählen.</p>
      <p begin="00:00:33.200" id="p12" end="00:00:38.040">Unterwegs entdecke ich Geschichten<br />über die besten Spiele, die es jemals gab</p>
      <p begin="00:00:38.040" id="p13" end="00:00:40.200">und finde heraus, warum es sie bis heute noch gibt.</p>
      <p begin="00:00:40.200" id="p14" end="00:00:44.080">Vom Spielplatz bis zur ersten<br />Heimspielkonsole lerne ich aus erster Hand,</p>
      <p begin="00:00:44.080" id="p15" end="00:00:47.240">was ein gutes Spiel auszeichnet,<br />warum Spiele für uns wichtig sind,</p>
      <p begin="00:00:47.240" id="p16" end="00:00:49.240">was sie über uns aussagen,</p>
      <p begin="00:00:49.240" id="p17" end="00:00:51.800">und warum sie so viel Spaß machen.</p>
    <div xml:lang="nor">
      <p begin="00:00:03.680" id="p0" end="00:00:04.480">en mann</p>
      <p begin="00:00:04.480" id="p1" end="00:00:05.280">på en motorsykkel</p>
      <p begin="00:00:05.280" id="p2" end="00:00:06.880">rundt i verden</p>
      <p begin="00:00:06.880" id="p3" end="00:00:08.480">på</p>
      <p begin="00:00:08.480" id="p4" end="00:00:13.000">Jakt Etter Leker</p>
      <p begin="00:00:13.000" id="p5" end="00:00:15.000">Hei, jeg er Tim Hull.</p>
      <p begin="00:00:15.000" id="p6" end="00:00:18.040">Jeg tror at lekene vi utøver<br />er fundamentale byggestener</p>
      <p begin="00:00:18.040" id="p7" end="00:00:19.960">for vår sivilisasjon.</p>
      <p begin="00:00:19.960" id="p8" end="00:00:23.200">Jeg har lagt ut på en<br />reise der mitt personlige mål er</p>
      <p begin="00:00:23.200" id="p9" end="00:00:25.960">å lete etter, avdekke, observere</p>
      <p begin="00:00:25.960" id="p10" end="00:00:27.800">og leke.</p>
      <p begin="00:00:27.800" id="p11" end="00:00:33.200">Jeg er på utkikk etter leker som forteller<br />oss om vår historie, kultur og tenkemåte.</p>
      <p begin="00:00:33.200" id="p12" end="00:00:38.040">Gjennom reisen min vil jeg avdekke<br />historier om de beste lekene som har oppstått</p>
      <p begin="00:00:38.040" id="p13" end="00:00:40.200">og hvorfor de fortsatt er med oss i dag.</p>
      <p begin="00:00:40.200" id="p14" end="00:00:44.080">Fra skolegården til hjemmets fire<br />vegger skal jeg hente førstehåndslæring</p>
      <p begin="00:00:44.080" id="p15" end="00:00:47.240">om hva som gjør en lek god,<br />hvorfor leker er bra for oss</p>
      <p begin="00:00:47.240" id="p16" end="00:00:49.240">og hva de forteller om oss selv</p>
      <p begin="00:00:49.240" id="p17" end="00:00:51.800">i tillegg til å gi oss mye glede.</p>

More resources

Originally Published: 11-08-2012.
Updated: For Wowza Streaming Engine on 03-07-2014.

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