• How to stream WebVTT subtitles to iOS for closed captioning

    Apple iOS 6 offers the ability to enable subtitles. The 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 caption data in video on demand (VOD) and live streams to WebVTT subtitles for playback on Apple iOS 6 devices.

    Note: Wowza Media Server™ 3.6 or later is required.

    Contents


    VOD and WebVTT configuration
    Live and WebVTT configuration
    More resources

    VOD and WebVTT configuration


    VOD configuration properties

    This section describes the closed captioning-related properties for iOS WebVTT streaming that can be defined in the Application/TimedText/Properties section in [install-dir]/conf/Application.xml.

    cupertinoVODCaptionsUseWebVTT


    This property controls whether captions are converted to WebVTT subtitle format. If enabled (Value = true), WebVTT subtitles are created. If disabled (Value = false), CEA-608 captions are created. The default value is false.
    <Property>
    	<Name>cupertinoVODCaptionsUseWebVTT</Name>
    	<Type>Boolean</Type>             
    	<Value>true</Value>
    </Property>
    For a complete list of Timed Text configuration options, see Closed captioning configuration reference for video on demand streaming.

    VOD playback

    To play using an Apple iOS 6 device


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

    • To enable captioning for a VOD asset using an external caption file, remember to do the following:

      1. Place the TTML (.ttml), SRT (.srt), or SCC (.scc) caption file next to the video asset file in the [install-dir]/content folder and ensure that the root file name of the caption file is the same as that of the asset file (for example, sample.ttml and sample.mp4). This allows the corresponding VODTimedTextProvider to find the file and ingest it for caption insertion during playback.

      2. In your Application.xml file, define the appropriate VODTimedTextProvider for the caption file type. For more information, see Configuring Application.xml in How to configure closed captioning for video on demand streaming.
    Enter the following URL in a Safari web browser:
    http://[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8
    The Subtitle button isn't always available in the player. To find it:

    1. Orient the device in landscape mode.

    2. Click on 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. Select it and choose your language.


    To play embedded in HTML on Apple iOS 6 (Cupertino/Apple HTTP Live Streaming)


    Enter the URL of the webpage in a Safari browser. For example:
    http://[website]/index.html
    The webpage should have an embedded <video> element defined, such as the following:
    <video src="[wowza-ip-address]:1935/vod/mp4:sample.mp4/playlist.m3u8" controls>

    VOD ABR playback

    Note: Available starting with Wowza Media Server 3.6.2, build 6596 or later.

    To play using a SMIL file


    To play using a SMIL file, the caption info must be added to the SMIL file using a textstream tag. For example, create vod.smil:
    <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 use the following URL:
    http://[wowza-ip-address]:1935/vod/smil:vod.smil/playlist.m3u8

    Live and WebVTT configuration


    Live configuration properties

    This section describes the closed captioning-related properties for iOS WebVTT streaming that can be defined in the Application/TimedText/Properties section in [install-dir]/conf/Application.xml. The inbound stream must contain proper Action Message Format (AMF) onTextData events for the specified languages. This is what provides the live captions to the stream. See More resources above.

    cupertinoLiveCaptionsUseWebVTT
    This property controls whether live AMF onTextData events are converted to WebVTT subtitle format. If enabled (Value = true), WebVTT subtitles are created. If disabled (Value = false), CEA-608 captions are created. The default value is false.
    <Property>
    	<Name>cupertinoLiveCaptionsUseWebVTT</Name>
    	<Type>Boolean</Type>			
    	<Value>true</Value>
    </Property>
    captionLiveIngestLanguages
    This property determines what subtitle languages are expected to be delivered. If not specified, the language is based on the Wowza Media Server computer locale. The language codes should be based on ISO-639.

    The following code snippet enables English and French:
    <Property>
    	<Name>captionLiveIngestLanguages</Name>
    	<Type>String</Type>			
    	<Value>eng,fra</Value>
    </Property>
    debugCaptionLiveIngest
    This property enables additional debug logging when live captions are ingested. The default value is false.
    <Property>
    	<Name>debugCaptionLiveIngest</Name>
    	<Type>Boolean</Type>			
    	<Value>true</Value>
    </Property>
    captionLiveIngestUseStreamNameGroups
    This property controls whether SMIL files are used during publishing to specify caption ingest behavior. The default value is true (SMIL files are used). For more information about how to use SMIL files to specify caption ingest behavior, see Overriding properties using a SMIL file.
    <Property>
    	<Name>captionLiveIngestUseStreamNameGroups</Name>
    	<Type>Boolean</Type>			
    	<Value>false</Value>
    </Property>

    Overriding caption ingest behavior using a SMIL file

    If a live stream is published with a SMIL file, either using StartupStreams.xml or Stream Manager, the SMIL file can be used to specify the caption information that's found in the inbound stream. The values found in the SMIL file override the equivalent properties mentioned above.

    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">
    			     <param name="isWowzaCaptionStream" value="true" />
    			     <param name="wowzaCaptionIngestType" value="onTextData" />
    			</textstream>
    
    		</switch>
    	</body>
    </smil>
    • 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).

    • The param isWowzaCaptionStream set to true specifies that this stream has live captions to be ingested.

    • The param wowzaCaptionIngestType identifies where the captions are found in the stream. Currently the only valid value is onTextData, which denotes that captions are found in AMF onTextData events.

    Live playback

    To play using an Apple iOS 6 device


    Enter the following URL in a Safari web browser:
    http://[wowza-ip-address]:1935/live/myStream/playlist.m3u8
    The Subtitle button isn't always available in the player. To find it:

    1. Orient the device in landscape mode.

    2. Click on 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. Select it and choose your language.


    To play embedded in HTML on Apple iOS 6 (Cupertino/Apple HTTP Live Streaming)


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

    Live ABR playback

    Note: Available with Wowza Media Server 3.6.2, build 6596 or later.

    To play using a SMIL file


    To play using a SMIL file, the caption info must be added to the SMIL file using a textstream tag. For example, create live.smil:
    <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 use the following URL:
    http://[wowza-ip-address]:1935/live/smil:live.smil/playlist.m3u8

    Originally Published: 05-28-2013.
    Updated: 10-31-2014.

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