Configure WebVTT captions for Wowza Streaming Engine iOS streams

The Apple iOS subtitling system uses Web Video Text Tracks (WebVTT), which provides more flexibility in rendering multiple languages and languages that aren't supported in iOS CEA-608 closed captioning. This article describes how to configure Wowza Streaming Engine™ media server software to convert closed captioning data in video-on-demand (VOD) and live streams to WebVTT subtitles for playback on Apple iOS devices.

Note: Wowza Streaming Engine 4.x or Wowza Media Server™ software 3.6.x is required. Apple iOS 6 or later is also required.

Configure WebVTT for VOD streams


This section describes how to control whether captions in VOD files are converted to WebVTT subtitles for streaming to iOS from Wowza Streaming Engine. You can configure streaming applications in Wowza Streaming Engine Manager or by setting properties in Application.xml. Both methods have the same result. Wowza Media Server administrators must configure streaming applications in Application.xml.

You must configure the WebVTT VODTimedTextProvider for the VOD application and provide captions in an external WebVTT-formatted companion file for the VOD asset, which will be passed on as WebVTT subtitles. For information about how to set up closed captioning for VOD, see Configure closed captioning for Wowza Streaming Engine video-on-demand streams.

Configure WebVTT for VOD streams in Wowza Streaming Engine Manager

  1. Click the Applications tab, and then click the name of your VOD application (such as vod) in the contents panel.
     
  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 the cupertinoVODCaptionsUseWebVTT property, and then set the property value to true.
     
  5. Click Save, and then restart the application.

Configure WebVTT for VOD streams in XML

  1. In a text editor, open the [install-dir]/conf/[vod-application-name]/Application.xml file and locate the <Application>/<TimedText>/<Properties> container in the file.
     
  2. Copy the following property into the container:
     
    <Property>
    	<Name>cupertinoVODCaptionsUseWebVTT</Name>
    	<Value>true</Value>
    	<Type>Boolean</Type>
    </Property>
  3. Save and close the file, and then restart Wowza Streaming Engine.

Play VOD streams with WebVTT subtitles

Play using an Apple iOS device

Note: To play your own content, copy your file into the [install-dir]/content folder and substitute its file name for sample.mp4 in the sample URLs below.

In Safari on the device, enter the following URL:

http://[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8

Play embedded in HTML on an Apple iOS device

In Safari on the device, enter the URL of the webpage. For example:

http://[domain]/index.html

The webpage should have an embedded <video> element defined, for example:

<video src="[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8" controls>

Play using a SMIL file

To play adaptive-bitrate streams using a SMIL file, the captions must be added to the SMIL file using a single textstream tag (SMIL files don't support multiple textstream tags). For example, create a vod.smil with the following content:

<smil>
    <head>
    </head>
    <body>
        <switch>
            <video src="mp4:sample.mp4" system-bitrate="300000" width="424" height="240">
                <param name="videoCodecId" value="avc1.66.30" valuetype="data"/>
                <param name="audioCodecId" value=" mp4a.40.2" valuetype="data"/>
            </video>
            <video src="mp4:sample2.mp4" system-bitrate="500000" width="424" height="240">
                <param name="videoCodecId" value="avc1.66.30" valuetype="data"/>
                <param name="audioCodecId" value=" mp4a.40.2" valuetype="data"/>
            </video>
            <textstream src="sample.ttml" system-language="eng,fra">
                <param name="isWowzaCaptionStream" value="true" />
            </textstream>
        </switch>
    </body>
</smil>

Then, in Safari on the device, enter the following URL:

http://[wowza-ip-address]:1935/vod/smil:vod.smil/playlist.m3u8

Configure WebVTT for live streams


This section describes how to control whether captions in live streams are converted to WebVTT subtitles for streaming to iOS from Wowza Streaming Engine. You can configure streaming applications in Wowza Streaming Engine Manager or by setting properties in Application.xml. Both methods have the same result. Wowza Media Server software administrators must configure streaming applications in Application.xml.

The inbound live stream must contain proper Action Message Format (AMF) onTextData events for any specified languages. This provides the captions to the stream, which will be converted to WebVTT subtitles. For more information about how to set up live closed captioning, see Configure closed captioning for Wowza Streaming Engine live streams.

Configure WebVTT for live streams in Wowza Streaming Engine Manager

  1. Click the Applications tab, and then click the name of your live application (such as live) in the contents panel.
     
  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 the cupertinoLiveCaptionsUseWebVTT property, and then set the property value to true.
     
  5. Enable the captionLiveIngestLanguages property, and then set the property value to a comma-separated list of ISO-639 language codes for the subtitle languages that you expect to be delivered in the live stream. You can also leave the value blank to use the locale language of the computer that's running Wowza Streaming Engine.
     
  6. Click Save, and then restart the application.

Configure WebVTT for live streams in XML

  1. In a text editor, open the [install-dir]/conf/[live-application-name]/Application.xml file and locate the <Application>/<TimedText>/<Properties> container in the file.
     
  2. Copy the following properties into the container:
     
    <Properties>
    <Property>
    <Name>cupertinoLiveCaptionsUseWebVTT</Name>
    <Value>true</Value>
    <Type>Boolean</Type>
    </Property>
    <Property>
    <Name>captionLiveIngestLanguages</Name>
    <Value>eng,fra</Value>
    <Type>String</Type>
    </Property>
    </Properties>

    Be sure to set the captionLiveIngestLanguages property value (eng,fra in the sample code) to the comma-separated list of ISO-639 language codes for the subtitle languages that you're delivering in the live stream. You can also leave the value blank to use the locale language of the computer that's running Wowza Streaming Engine.

  3. Save and close the file, and then restart Wowza Streaming Engine.

Override live caption ingest behavior using a SMIL file

If a live stream is published with a SMIL file, the SMIL file can specify the caption information in the inbound stream. The values in the SMIL file will override the properties specified in Wowza Streaming Engine or in Application.xml as described above. In the following example SMIL file, the textstream tag identifies that the incoming published stream contains captions:

<smil>
<head>
</head>
<body>
<switch>
<video src="myStream" system-bitrate="500000"/>

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

</switch>
</body>
</smil>

Where:

  • src matches a source stream that's published via the video tag.
  • system-language is a comma-separated list of ISO-639 three-letter language codes. The incoming stream should contain captions in the specified language(s).
  • isWowzaCaptionStream is set to true to indicate that the stream has live captions to be ingested.
  • wowzaCaptionIngestType identifies where the captions are found in the stream. The only supported value is onTextData, which denotes that captions are found in AMF onTextData events.

You must set the captionLiveIngestUseStreamNameGroups property for your live application, either in Wowza Streaming Engine Manager or directly in the Application.xml file, to control whether SMIL files are used during publishing to specify caption ingest behavior.

Wowza Streaming Engine Manager configuration

  1. Click the Applications tab, and then click the name of your live application (such as live) in the contents panel.
  2. Click the Properties tab, and then click Custom in the Quick Links bar.
Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
  1. In the Custom section, click Edit, and then click Add Custom Property.
  2. Enter the following information in the Add Custom Property dialog box:
     
    • In Path, select /Root/Application/TimedText.
    • In Name, enter captionLiveIngestUseStreamNameGroups.
    • In Type, select Boolean.
    • In Value, select true.
  3. Click Add, then click Save, and then restart the application.

Application.xml configuration 

  1. In a text editor, open the [install-dir]/conf/[live-application-name]/Application.xml file and locate the <Application>/<TimedText>/<Properties> container in the file.
     
  2. Copy the following property into the container:
     
    <Property>
        <Name>captionLiveIngestUseStreamNameGroups</Name>
        <Value>true</Value>
        <Type>Boolean</Type>
    
    </Property>
  3. Save and close the file, and then restart Wowza Streaming Engine.

Enable debug logging for live WebVTT streaming

You can set the debugCaptionLiveIngest property for your live application, either in Wowza Streaming Engine Manager or directly in the Application.xml file, to enable additional debug logging when live captions are ingested.

Wowza Streaming Engine Manager configuration

  1. Click the Applications tab, and then click the name of your live application (such as live) in the contents panel.
     
  2. Click the Properties tab, and then click Custom 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 Custom section, click Edit, and then click Add Custom Property.
     
  4. Enter the following information in the Add Custom Property dialog box:
     
    • In Path, select /Root/Application/TimedText.
    • In Name, enter debugCaptionLiveIngest.
    • In Type, select Boolean.
    • In Value, select true.
  5. Click Add, then click Save, and then restart the application when prompted to apply the changes.

Application.xml configuration

  1. In a text editor, open the [install-dir]/conf/[live-application-name]/Application.xml file and locate the <Application>/<TimedText>/<Properties> container in the file.
     
  2. Copy the following property into the container:
     
    <Property>
    <Name>debugCaptionLiveIngest</Name>
    <Value>true</Value>
    <Type>Boolean</Type>
    </Property>
  3. Save and close the file, and then restart Wowza Streaming Engine.

Play live streams with WebVTT subtitles

Play using an Apple iOS device

In Safari, enter the following URL:

http://[wowza-ip-address]:1935/live/myStream/playlist.m3u8

Play embedded in HTML on Apple iOS device

In Safari, enter the URL of the webpage. For example:

http://[domain]/index.html

The webpage should have an embedded <video> element defined, for example:

<video src="[wowza-ip-address]:1935/live/myStream/playlist.m3u8" controls>

Play using a SMIL file

To play adaptive-bitrate streams using a SMIL file, the caption must be added to the SMIL file using a single textstream tag (SMIL files don't support multiple textstream tags). For example, create a live.smil with the following content:

<smil>
<head>
</head>
<body>
<switch>
<video src="myStream1" system-bitrate="685362" width="424" height="240">
<param name="videoCodecId" value="avc1.66.30" valuetype="data"/>
<param name="audioCodecId" value=" mp4a.40.2" valuetype="data"/>
</video>
<video src="myStream1" system-bitrate="64000">
<param name="audioOnly" value="TRUE" valuetype="data"/>
</video>
<video src="myStream2" system-bitrate="385362" width="424" height="240">
<param name="videoCodecId" value="avc1.66.30" valuetype="data"/>
<param name="audioCodecId" value=" mp4a.40.2" valuetype="data"/>
</video>

<textstream src="myStream1" system-language="eng,kor">
<param name="isWowzaCaptionStream" value="true" />
<param name="wowzaCaptionIngestType" value="onTextData" />
</textstream>

</switch>
</body>
</smil>

Then, in Safari, enter the following URL:

http://[wowza-ip-address]:1935/live/smil:live.smil/playlist.m3u8

Locate the subtitle icon in the Apple iOS player


  1. Orient the device to landscape mode.
     
  2. Tap the Full screen icon.
     
  3. Tap the screen to display the control menu. A subtitle icon should be available to the right of the seek bar.

    ;
     
  4. Tap the subtitle icon and choose a language.

More resources