Closed captioning configuration reference for video on demand streaming

This article describes the closed captioning properties that you can adjust for video on demand (VOD) streaming with Wowza™ media server software. Configuration properties allow you to modify the default behavior of specific VOD closed captioning functionality. Debug properties allow you to enable debug logging for specific components of the VOD closed captioning features.

Note: Wowza Streaming Engine™ software or Wowza Media Server™ software (version 3.5.0 or later) is required.

Contents


Adding properties to your application Configuration properties Debug properties More resources

Adding properties to your application


Adding properties in Wowza Streaming Engine Manager

To add any of the properties described in this article to your application:
 
  1. In Wowza Streaming Engine Manager, click the Applications tab, and then click the name of your vod application (such as vod).
     
  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 and configure properties as needed. Click Save, and then restart the application to apply the properties.

Adding properties to Application.xml

Note: If you configured caption properties in Wowza Streaming Engine Manager, you don't need to configure them in the Application.xml file. If you make changes to Application.xml and you're using the Wowza Streaming Engine™ software, any supported settings will be displayed in the manager the next time it's started. Wowza Media Server™ software doesn't support Wowza Streaming Engine Manager, so you must edit Application.xml in a text editor if you're running Wowza Media Server.
To add any of the properties described in this article:
 
  1. Use a text editor to open [install-dir]/conf/Application.xml and add the <Property> definition code including the Name, Type, and Value to the <Application>/TimedText/<Properties> container (unless otherwise mentioned).
     
  2. Save and close the file, and then restart the media server to apply the changes.

Configuration properties


This section describes the closed captioning properties for video on demand (VOD) streaming that can be defined in the Closed Captions properties in Wowza Streaming Engine Manager or in the Application/TimedText/Properties section in [install-dir]/conf/Application.xml. These properties allow you to adjust VOD closed captioning functionality in Wowza media server software.

Enabling and disabling captions

vodCaptionsEnabled
Enables VOD captions for all supported protocols. This option controls whether embedded 3GPP and companion file captions are inserted into output streams. Embedded CEA-608 captions aren't affected by this option, and as such, are always passed through to Apple HLS (Cupertino) streams. Default value is true.
 
Note: VOD captions can be enabled on a per-protocol basis using the cupertinoVODCaptionsEnabled, rtmpVODCaptionsEnabled, and sanJoseVODCaptionsEnabled properties; however, these properties can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>vodCaptionsEnabled</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
cupertinoVODCaptionsEnabled
Enables VOD captions for Apple HTTP Live Streaming (Cupertino). Default value is true.

This option controls whether embedded 3GPP and companion file captions are inserted into Cupertino streams. Embedded CEA-608 captions aren't affected by this option, and as such, are always be passed through to Cupertino streams.
<Property>
    <Name>cupertinoVODCaptionsEnabled</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
rtmpVODCaptionsEnabled
Enables VOD captions for RTMP streaming. Default value is true.

This option controls whether embedded 3GPP and companion file captions are inserted into RTMP streams.
<Property>
    <Name>rtmpVODCaptionsEnabled</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
sanJoseVODCaptionsEnabled
Enables VOD captions for Adobe HDS (San Jose) streaming. Default value is true.

This option controls whether embedded 3GPP and companion file captions are inserted into Adobe HDS (San Jose) streams.
<Property>
    <Name>sanJoseVODCaptionsEnabled</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>

Preferred caption language(s)

captionUndefinedLanguageId
Defines a single language to be used if no caption language is specified by the asset file and if the language IDs provided in captionLanguages aren't recognized. Language IDs must be in 3-character ISO-639 format (for example, eng). If no language is defined in the asset file or with any caption language property, the media server's location is used to select a language.
<Property>
    <Name>captionUndefinedLanguageId</Name>
    <Type>String</Type>
    <Value>eng</Value>
</Property>
captionLanguages
Defines the language to be selected by default if no languages are specified in the stream URL. The default value (*) makes the Wowza media server use the first caption language found in the source media depending on the configuration of your application's closed caption sources. For more information, see How to configure closed captioning language selection for video on demand streaming.

Language IDs must be in 3-character ISO-639 format, and the value can define either a single language ID (for example, eng) or a prioritized ordered list of language IDs (for example, eng,spa,fra).

VOD caption languages can be specified on a per-protocol basis using the cupertinoCaptionLanguages, rtmpCaptionLanguages, and sanJoseCaptionLanguages properties.
 
<Property>
    <Name>captionLanguages</Name>
    <Type>String</Type>
    <Value>*</Value>
</Property>
cupertinoCaptionLanguages
Defines the language to be presented by default for Apple HLS (Cupertino) streaming if no languages are specified in the player connection URL. For more information, see How to configure closed captioning language selection for video on demand streaming. This property can't be configured in Wowza Streaming Engine Manager.

Language IDs must be in 3-character ISO-639 format, and the value can define either a single language ID (for example, eng) or a prioritized ordered list of language IDs (for example, eng,spa,fra).
<Property>
    <Name>cupertinoCaptionLanguages</Name>
    <Type>String</Type>
    <Value>*</Value>
</Property>
rtmpCaptionLanguages
Defines the language to be selected by default for RTMP streaming if no languages are specified in the player connection URL (for more information, see How to configure closed captioning language selection for video on demand streaming). This property can't be configured in Wowza Streaming Engine Manager.

Language IDs must be in 3-character ISO-639 format, and the value can define either a single language ID (for example, eng) or a prioritized ordered list of language IDs (for example, eng,spa,fra).
<Property>
    <Name>rtmpCaptionLanguages</Name>
    <Type>String</Type>
    <Value>*</Value>
</Property>
sanJoseCaptionLanguages
Defines the language to be selected by default for Adobe HDS (San Jose) streaming if no languages are specified in the stream URL. For more information, see How to configure closed captioning language selection for video on demand streaming. This property can't be configured in Wowza Streaming Engine Manager.

Language IDs must be in 3-character ISO-639 format, and the value can define either a single language ID (for example, eng) or a prioritized ordered list of language IDs (for example, eng,spa,fra).
<Property>
    <Name>sanJoseCaptionLanguages</Name>
    <Type>String</Type>
    <Value>*</Value>
</Property>

Caption conversion for CEA-608 output


cea608CaptionConverterColor
Changes the text color in the default CEA caption converter. Valid values are: 0 (white), 2 (green), 4 (blue), 6 (cyan), 8 (red), 10 (yellow), and 12 (magneta). The default is 0 (white).
<Property>
    <Name>cea608CaptionConverterColor</Name>
    <Type>Integer</Type>
    <Value>0</Value>
</Property>
cea608CaptionConverterCharsPerLine
Specifies the maximum number of characters per line in the default CEA caption converter. The default is 31. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>cea608CaptionConverterCharsPerLine</Name>
    <Type>Integer</Type>
    <Value>31</Value>
</Property>

General properties

captionFileNamingRule
Changes the logic that determines the file-naming scheme for the caption companion file. This is used to find the caption file for a given VOD asset. The string value is comprised of two variables: ${var1}.{var2}.

Valid variables include:
 
  • ${SourceStreamName} - The base name of the VOD file
  • ${FileExtension} - Registered file extensions with the Timed Text provider
Standard variables are:
 
  • ${com.wowza.wms.context.VHost}
  • ${com.wowza.wms.context.Application", appInstance.getApplication().getName()}
  • ${com.wowza.wms.context.ApplicationInstance", appInstance.getName()}
The default value is ${SourceStreamName}.${FileExtension}. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>captionFileNamingRule</Name>
    <Type>String</Type>
    <Value>${SourceStreamName}.${FileExtension}</Value>
</Property>
maximumCaptionDuration
Defines the maximum caption duration in milliseconds. The default value is 10000.
<Property>
    <Name>maximumCaptionDuration</Name>
    <Type>Integer</Type>
    <Value>10000</Value>
</Property>
captionLanguageQueryParameter
Specifies the query string parameter used for caption language selection. The default value is wowzacaptionlanguages. This property must be added under each streamer type in the HTTPStreamers.xml file found in your Wowza Media Server installation directory and can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>captionLanguageQueryParameter</Name>
    <Type>String</Type>
    <Value>wowzacaptionlanguages</Value>
</Property>

Debug properties


This section describes the properties that can be defined in the Application/TimedText/Properties section in [install-dir]/conf/Application.xml to enable informational debug logging for specific areas of VOD closed captioning functionality. The default for all debug properties is false.

Language selection

debugVODCaptionLanguageSelection
Enables language selection logging for all supported protocols. VOD caption language selection logging can be enabled on a per-protocol basis using the cupertinoDebugVODCaptionLanguageSelection, rtmpDebugVODCaptionLanguageSelection, and sanJoseDebugVODCaptionLanguageSelection properties.
<Property>
    <!-- Enables language selection logging for all supported protocols -->
    <Name>debugVODCaptionLanguageSelection</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
cupertinoDebugVODCaptionLanguageSelection
Enables language selection logging for Apple HLS (Cupertino) streaming. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>cupertinoDebugVODCaptionLanguageSelection</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
rtmpDebugVODCaptionLanguageSelection
Enables language selection logging for RTMP streaming. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>rtmpDebugVODCaptionLanguageSelection</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
sanJoseDebugVODCaptionLanguageSelection
Enables language selection logging for Adobe HDS (San Jose) streaming. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>sanJoseDebugVODCaptionLanguageSelection</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>

Provider determination

debugVODCaptionProviderDetermination
Enables caption provider determination logging for all supported protocols. VOD caption provider determination logging can be enabled on a per-protocol basis using the cupertinoDebugVODCaptionProviderDetermination, rtmpDebugVODCaptionProviderDetermination, and sanJoseVODDebugCaptionProviderDetermination properties.
<Property>
    <Name>debugVODCaptionProviderDetermination</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
cupertinoDebugVODCaptionProviderDetermination
Enables caption provider determination logging for Apple HLS (Cupertino) streaming. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>cupertinoDebugVODCaptionProviderDetermination</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
rtmpDebugVODCaptionProviderDetermination
Enables caption provider determination logging for RTMP streaming. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>rtmpDebugVODCaptionProviderDetermination</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
sanJoseVODDebugCaptionProviderDetermination
Enables caption provider determination logging for Adobe HDS (San Jose) streaming. This property can't be configured in Wowza Streaming Engine Manager.
<Property>
    <Name>sanJoseVODDebugCaptionProviderDetermination</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>

Caption file determination

debugVODCaptionFileDetermination
Enables caption companion file determination logging for a given VOD asset for all supported protocols.

<Property>
    <Name>debugVODCaptionFileDetermination</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
debugTTMLVODCaptionFileDetermination
Enables TTML caption companion file determination logging.
<Property>
    <Name>debugTTMLVODCaptionFileDetermination</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>

TTML

debugTTMLCaptionParser
Enables TTML caption parser logging.
<Property>
    <Name>debugTTMLCaptionParser</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>
debugTTMLVODCaptionFileDetermination
Enables TTML caption companion file determination logging.
<Property>
    <Name>debugTTMLVODCaptionFileDetermination</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>

3GPP

debug3GPPCaptionParser
Enables 3GPP caption parser logging.
<Property>
    <Name>debug3GPPCaptionParser</Name>
    <Type>Boolean</Type>
    <Value>true</Value>
</Property>

More resources



Originally Published: 11-08-2012.
Updated: For Wowza Streaming Engine on 03-07-2014.
 

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