This article describes the closed captioning properties that you can adjust for video-on-demand (VOD) streaming with Wowza Streaming Engine™ 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.
Add properties to a Wowza Streaming Engine application
Add properties in Wowza Streaming Engine Manager
- Click the Applications tab, and then click the name of your VOD application.
- 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 and configure properties as needed.
- Click Save, and then restart the application.
Add properties in XML
Note: If you configured caption properties in Wowza Streaming Engine Manager, you don't need to configure them in Application.xml. If you make changes to Application.xml, any supported settings will be displayed in Wowza Streaming Engine Manager the next time it's started.
- 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).
- Save and close the file, and then restart Wowza Streaming Engine.
Configuration properties
This section describes the closed captioning properties for 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.
Enabling and disabling captions
- vodCaptionsEnabled – Enables VOD captions for all supported protocols. 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 or rtmpVODCaptionsEnabled properties; however, these properties can't be configured in Wowza Streaming Engine Manager.
- cupertinoVODCaptionsEnabled – Enables VOD captions for Apple HTTP Live Streaming (Cupertino). Default value is true. 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.
- rtmpVODCaptionsEnabled – Enables VOD captions for RTMP streaming. Default value is true. Controls whether embedded 3GPP and companion file captions are inserted into RTMP streams.
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 Apple HLS (Cupertino) 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 – 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).
- cea608CaptionConverterCharsPerLine – Specifies the maximum number of characters per line in the default CEA caption converter. The default is 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 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}.
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 – Defines the maximum caption duration in milliseconds. The default value is 10000.
- captionLanguageQueryParameter – Specifies the query string parameter used for caption language selection. The default value is 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.
