Closed captioning property reference for video-on-demand streams

This article describes the available closed captioning properties for video-on-demand (VOD) streaming with Wowza Streaming Engine™ (WSE) media server software. These properties allow you to modify specific VOD closed captioning functionality. The debugging properties allow you to enable logging for specific components of the VOD closed captioning features.

Add properties to an app

You can configure closed captioning in a VOD app using WSE Manager, or by directly editing the app's configuration file.

Add properties in WSE Manager

1. Open WSE Manager.
2. Click the Applications tab.
3. Click the name of your VOD application.
    
4. Click the Properties tab.
5. In the Quick Links bar, click Closed Captions.
6. Click Edit.
    
7. Configure properties as needed.
8. Click Save.
9. Restart the application.

Add properties in XML

1. Open your apps's [install-dir]/conf/[app-name]/Application.xml configuration file.
2. Navigate to the <Application> container element.
3. Navigate to the <TimedText> element.
4. Navigate to the <Properties> element.
5. Add or update the desired configuration <Property> including its Name, Type, and Value.
    
6. Save and close the file.
7. Restart Wowza Streaming Engine.

Configuration properties

This section describes the available closed captioning properties for VOD streaming.

Enable  captions

• vodCaptionsEnabled: Set to true to insert captions into output streams, regardless of the protocol. Default: true.

• cupertinoVODCaptionsEnabled: Set to true to insert captions into HLS streams. Set to true to enable VOD captions for HLS streams. Default: true. (Note: This property cannot currently be configured in WSE Manager.)
• rtmpVODCaptionsEnabled: Set to true to insert captions into RTMP streams. Set to true to enables VOD captions for RTMP streaming. Default: true. (Note: This property cannot currently be configured in WSE Manager.)
• publisherTimedTextEnabled: Set to true to insert captions on a VOD or live stream.

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 three-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.
• captionLanguages: Defines the language to be selected by default if no languages are specified in the stream URL. The default value (*) makes Wowza Streaming Engine 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 Specify a closed captioning language for Wowza Streaming Engine video-on-demand streams.

Language IDs must be in three-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 or rtmpCaptionLanguages properties.

• cupertinoCaptionLanguages: Defines the language to be presented by default for HLS streaming if no languages are specified in the player connection URL. For more information, see Specify a closed captioning language for Wowza Streaming Engine video-on-demand streams.

Note: This property can't be configured in Wowza Streaming Engine Manager.

Language IDs must be in three-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 Specify a closed captioning language for Wowza Streaming Engine video-on-demand streams.

Note: This property can't be configured in Wowza Streaming Engine Manager.

Language IDs must be in three-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>

Caption conversion for CEA-608 output

• cea608CaptionConverterColor: The text color in the default CEA caption converter. (Default: 0) Available values:
  • 0 (white)
  • 2 (green)
  • 4 (blue)
  • 6 (cyan)
  • 8 (red)
  • 10 (yellow)
  • 12 (magneta).
• cea608CaptionConverterCharsPerLine: The maximum number of characters per line in the default CEA caption converter. (Default: 31).

Note: 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:

• ${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}.

Note: This property can't be configured in Wowza Streaming Engine Manager.

<Property>
    <Name>captionFileNamingRule</Name>
    <Type>String</Type>
    <Value>${SourceStreamName}.${FileExtension}</Value>
</Property>

• maximumCaptionDuration: The maximum caption duration in milliseconds. (Default: 10000.)
• captionLanguageQueryParameter: The query string parameter used for caption language selection. (Default:  wowzacaptionlanguages)

Note: This property 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 or rtmpDebugVODCaptionLanguageSelection 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.

Note: 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.

Note: This property can't be configured in Wowza Streaming Engine Manager.

<Property>
  <Name>rtmpDebugVODCaptionLanguageSelection</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 or rtmpDebugVODCaptionProviderDetermination properties.
• cupertinoDebugVODCaptionProviderDetermination: Enables caption provider determination logging for Apple HLS (Cupertino) streaming.

Note: 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.

Note: This property can't be configured in Wowza Streaming Engine Manager.

<Property>
  <Name>rtmpDebugVODCaptionProviderDetermination</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.
• debugTTMLVODCaptionFileDetermination: Enables TTML caption companion file determination logging.

TTML

• debugTTMLCaptionParser: Enables TTML caption parser logging.
• debugTTMLVODCaptionFileDetermination: Enables TTML caption companion file determination logging.

3GPP

• debug3GPPCaptionParser: Enables 3GPP caption parser logging.

More resources

• Configure closed captioning for Wowza Streaming Engine video-on-demand streams
• Specify a closed captioning language for Wowza Streaming Engine video-on-demand streams