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 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
- 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
- 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.
- 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
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 must be added to the SMIL file using a single textstream container element (SMIL files don't support multiple textstream elements). 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. You can configure streaming applications in Wowza Streaming Engine Manager or by setting properties in Application.xml. Both methods have the same result.
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
- Click the Applications tab, and then click the name of your live 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 cupertinoLiveCaptionsUseWebVTT property, and then set the property value to true.
- 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.
- Click Save, and then restart the application.
Configure WebVTT for live streams in XML
- 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.
- 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.
- 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 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>
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.
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
- 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
- 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.
- 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 must be added to the SMIL file using a single textstream container element (SMIL files don't support multiple textstream elements). 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
- 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
