• How to stream WebVTT subtitles to iOS for closed captioning

    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™ media server software to convert closed captioning data in on-demand (VOD) and live streams to WebVTT subtitles for playback on Apple iOS devices.

    Note: Wowza Streaming Engine™ (version 4.x) or Wowza Media Server™ (version 3.6.x) and Apple iOS (version 6 or later) is required.

    Contents

    WebVTT configuration for on-demand (VOD) streams
    WebVTT configuration for live streams
    Finding the Subtitle button in the Apple iOS player
    More resources

    WebVTT configuration for on-demand (VOD) streams


    This section describes how to control whether captions in on-demand video files are converted to WebVTT subtitles for iOS WebVTT streaming from on-demand applications in Wowza media server software. Wowza Streaming Engine software administrators can configure streaming applications by using UI options in Wowza Streaming Engine Manager or by setting properties in Application.xml. Both configuration methods have the same result. Wowza Media Server software administrators must configure streaming applications in the Application.xml file.

    You must configure the WebVTT VODTimedTextProvider for the on-demand application AND provide captions in an external WebVTT-formatted companion file for the on-demand video file, which will be passed on as WebVTT subtitles. For more information about how to set up on-demand closed captioning in Wowza media server software, see How to configure closed captioning for video on demand streaming.

    Configure VOD WebVTT streaming in Wowza Streaming Engine Manager

    1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your on-demand 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 when prompted to apply the changes.


    Configure VOD WebVTT streaming in Application.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 to the container:
      <Property>
      	<Name>cupertinoVODCaptionsUseWebVTT</Name>
      	<Value>true</Value>
      	<Type>Boolean</Type>
      </Property>
    3. Save and close the file, and then restart the media server to apply the changes.

    Playback VOD streams with WebVTT subtitles

    To 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 a Safari web browser on the device, enter the following URL:
    http://[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8

    To play embedded in HTML on an Apple iOS device


    In a Safari web browser on the device, enter the URL of the webpage. For example:
    http://[website]/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>

    To play using a SMIL file


    To play adaptive bitrate (ABR) streams using a SMIL file, the caption info must be added to the SMIL file using a textstream tag. 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 a Safari web browser on the device, enter the following URL:
    http://[wowza-ip-address]:1935/vod/smil:vod.smil/playlist.m3u8

    WebVTT configuration for live streams


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

    The inbound live stream must contain proper Action Message Format (AMF) onTextData events for any specified languages. This is what provides the captions to the stream, which will be converted to WebVTT subtitles. For more information about how to set up live closed captioning in Wowza media server software, see How to configure closed captioning for live streaming.

    Configure live WebVTT streaming in Wowza Streaming Engine Manager

    1. In Wowza Streaming Engine Manager, 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 Wowza media server computer locale language.

    6. Click Save, and then restart the application when prompted to apply the changes.


    Configure Live WebVTT streaming in Application.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 expect to be delivered in the live stream. You can also leave the value blank to use the Wowza media server computer locale language.

    3. Save and close the file, and then restart the media server to apply the changes.


    Override live caption ingest behavior using a SMIL file

    If a live stream is published with a SMIL file, either using StartupStreams.xml or the SMIL Files feature in Wowza Streaming Engine Manager, the SMIL file can be used to specify the caption information that's found in the inbound stream. The values in the SMIL file will override the equivalent properties mentioned 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 must match a source stream that's published via the video tag.
    • system-language is a comma-separated list of ISO-639 3-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. In Wowza Streaming Engine Manager, 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 captionLiveIngestUseStreamNameGroups.
      • 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>captionLiveIngestUseStreamNameGroups</Name>
      	<Value>true</Value>
      	<Type>Boolean</Type>
      </Property>
    3. Save and close the file, and then restart the media server to apply the changes.

    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. In Wowza Streaming Engine Manager, 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 the media server to apply the changes.

    Playback live streams with WebVTT subtitles

    To play using an Apple iOS device


    In a Safari web browser, enter the following URL:
    http://[wowza-ip-address]:1935/live/myStream/playlist.m3u8

    To play embedded in HTML on Apple iOS device


    In a Safari web browser, enter the URL of the webpage. For example:
    http://[website]/index.html
    The webpage should have an embedded <video> element defined, for example:
    <video src="[wowza-ip-address]:1935/live/myStream/playlist.m3u8" controls>

    To play using a SMIL file


    To play adaptive bitrate (ABR) streams using a SMIL file, the caption info must be added to the SMIL file using a textstream tag. 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 a Safari web browser, enter the following URL:
    http://[wowza-ip-address]:1935/live/smil:live.smil/playlist.m3u8

    Finding the Subtitle button in the Apple iOS player


    The Subtitle button isn't always available in the player. To find it:

    1. Orient the device to landscape mode.

    2. Click the Full screen button.

    3. Click on the screen to display the Seek and Pause menu. A Subtitle menu should be available on the right side of the button bar.


    4. Click the Subtitle icon and choose your language.

    More resources


    How to configure closed captioning for video on demand streaming
    How to configure closed captioning for live streaming
    How to do adaptive bitrate streaming
    How to start streams at server startup
    W3C Web Video Text Tracks (WebVTT) specification
    Originally Published: 05-28-2013.
    Updated: For Wowza Streaming Engine on 03-07-2014.

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