• 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>
    [h3]Caption file determination[/h3debugVODCaptionFileDetermination
    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-8-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.