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/708 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 later 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.
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
You can use these steps to configure WebVTT captions for VOD streams in Wowza Streaming Engine manager.
- Click the Applications tab, and then click the name of your VOD application in the contents panel.
- 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 cupertinoVODCaptionsUseWebVTT property, and then set the property value to true.
- Click Save, and then restart the application.
Configure WebVTT for VOD streams in XML
You can use these steps to configure WebVTT captions for VOD streams via Application.xml.
- In a text editor, open the [install-dir]/conf/[vod-application-name]/Application.xml file.
- Locate the <Application>/<TimedText>/<Properties> container in the file.
- Copy the following property into the container:
<Property> <Name>cupertinoVODCaptionsUseWebVTT</Name> <Value>true</Value> <Type>Boolean</Type> </Property>
- Save and close the file, and then restart Wowza Streaming Engine.
Play VOD streams with WebVTT subtitles
This section describes different methods to test playback for 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/[application-name]/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/myApplication/mp4:sample.mp4/playlist.m3u8" controls>
Play using a SMIL file
To play adaptive bitrate streams using a SMIL file, the captions can be added to the SMIL file using a single textstream container element. For example, create a vod.smil file 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.vtt" system-language="eng,fra">
<param name="isWowzaCaptionStream" value="true" valuetype="data"></param>
</textstream>
</switch>
</body>
</smil>
Then, in Safari on the device, enter the following URL:
http://[wowza-ip-address]:1935/[application-name]/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.
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 are then converted to WebVTT subtitles. For more information about how to set up live closed captioning for WebVTT output, see:
- Configure CEA-608/708 captions for WebVTT output in HLS live streams
- Configure onTextData captions for WebVTT output in HLS live streams
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 for the inbound stream. The values in the SMIL file override the properties specified in Wowza Streaming Engine or in the Application.xml file. The SMIL file must be added to the [install-dir]/content folder for your Wowza Streaming Engine installation. For more, see Understanding SMIL file syntax.
In the following example SMIL file, the textstream container element 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" valuetype="data"></param>
<param name="wowzaCaptionIngestType" value="onTextData" />
</textstream>
</switch>
</body>
</smil>
Each attribute or value in the previous code snippet can be described as follows:
- 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.
To output WebVTT subtitles, you can also use a SMIL file with multiple textstream containers such as this:
<smil>
<head>
</head>
<body>
<switch>
<video src="mp4:myStream" system-bitrate="450000">
<param name="cupertinoTag.SUBTITLES" value="subs" valuetype="data"/>
</video>
<textstream src="mp4:myStream" system-language="eng">
<param name="iswowzacaptionstream" value="true" valuetype="data"/>
<param name="cupertinoTag.TYPE" value="SUBTITLES" valuetype="data"/>
<param name="cupertinoTag.GROUP-ID" value="subs" valuetype="data"/>
<param name="cupertinoTag.DEFAULT" value="YES" valuetype="data"/>
<param name="cupertinoTag.FORCED" value="NO" valuetype="data"/>>
</textstream>
<textstream src="mp4:myStream" system-language="spa">
<param name="iswowzacaptionstream" value="true" valuetype="data"/>
<param name="cupertinoTag.TYPE" value="SUBTITLES" valuetype="data"/>
<param name="cupertinoTag.GROUP-ID" value="subs" valuetype="data"/>
<param name="cupertinoTag.DEFAULT" value="NO" valuetype="data"/>
<param name="cupertinoTag.FORCED" value="NO" valuetype="data"/>
</textstream>
<textstream src="mp4:myStream" system-language="fra">
<param name="iswowzacaptionstream" value="true" valuetype="data"/>
<param name="cupertinoTag.TYPE" value="SUBTITLES" valuetype="data"/>
<param name="cupertinoTag.GROUP-ID" value="subs" valuetype="data"/>
<param name="cupertinoTag.DEFAULT" value="NO" valuetype="data"/>
<param name="cupertinoTag.FORCED" value="NO" valuetype="data"/>
</textstream>
</switch>
</body>
</smil>
With either of the previous SMIL files present in the [install-dir]/content folder for your Wowza Streaming Engine installation, you can play back your live stream using the following URL format:
http://[wowza-ip-address]:1935/[application-name]/[name-of-smil-file].smil/playlist.m3u8
Note: The examples in this section don't cover playing adaptive bitrate streams using a SMIL file.
Enable debug logging for live WebVTT streaming
To enable additional debug logging when live captions are ingested, you can set the debugCaptionLiveIngest property for your live application either in Wowza Streaming Engine Manager or directly in the Application.xml file.
Wowza Streaming Engine Manager configuration
You can use these steps to enable debug logging for live WebVTT streaming in Wowza Streaming Engine Manager.
- Click the Applications tab, and then click the name of your live application in the contents panel.
- 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.
- In the Custom section, click Edit, and then click Add Custom Property.
- 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.
- Click Add, then click Save, and then restart the application when prompted to apply the changes.
Application.xml configuration
You can use these steps to enable debug logging for live WebVTT streaming via Application.
- In a text editor, open the [install-dir]/conf/[live-application-name]/Application.xml file.
- Locate the <Application>/<TimedText>/<Properties> container in the file.
- Copy the following property into the container:
<Property> <Name>debugCaptionLiveIngest</Name> <Value>true</Value> <Type>Boolean</Type> </Property>
- 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/[application-name]/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/myApplication/myStream/playlist.m3u8" controls>
Play using a SMIL file
To play adaptive bitrate streams using a SMIL file, the caption can be added to the SMIL file using a single textstream container element. For example, create a live.smil file 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" valuetype="data"></param>
<param name="wowzaCaptionIngestType" value="onTextData" />
</textstream>
</switch>
</body>
</smil>
Then, in Safari, enter the following URL:
http://[wowza-ip-address]:1935/[application-name]/smil:live.smil/playlist.m3u8
Locate the subtitle icon in the Apple iOS player
You can use these steps to locate the subtitle icon in Apple iOS players.
- Orient the device to landscape mode.
- Tap the Full screen icon.
- Tap the screen to display the control menu. A subtitle icon should be available to the right of the seek bar.
- Tap the subtitle icon and choose a language.
More resources
- Configure closed captioning for Wowza Streaming Engine video-on-demand streams
- Configure closed captioning for Wowza Streaming Engine live streams
- Stream adaptive bitrate content with Wowza Streaming Engine
- Start streams when Wowza Streaming Engine starts
- W3C Web Video Text Tracks (WebVTT) specification
