• 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 in Wowza Media Server. 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 implementation.

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

    Contents



    Configuration Properties

    Debug Properties

    More resources

    Configuration Properties



    This section describes the closed captioning-related properties for video on demand (VOD) streaming that can be defined in the Application/TimedText/Properties section in [install-dir]/conf/Application.xml. These properties allow specific VOD closed captioning functionality to be adjusted in Wowza Media Server.

    Enabling/Disabling captions


    vodCaptionsEnabled
    Enables VOD captions for all supported protocols. Default value is true.

    This option controls whether embedded 3GPP and companion file captions are inserted into output streams. Embedded CEA-608 captions are not affected by this option, and as such, are always passed through to Apple HLS (Cupertino) streams.

    VOD captions can be enabled on a per-protocol basis using the cupertinoVODCaptionsEnabled, rtmpVODCaptionsEnabled, and sanJoseVODCaptionsEnabled properties.
                <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 are not 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 the language ID to be used if:
    1. No caption language is specified by the asset file
      -or-
    2. The language ID provided is not recognized

    Language IDs must be in 3-character ISO-639 format, and the value should define only a single language ID (for example, "eng").

    If this property is not defined in one of the above mentioned scenarios, then the locale's 3-character language code is used by default.
                <Property>
                    <Name>captionUndefinedLanguageId</Name>
                    <Type>String</Type>             
                    <Value>eng</Value>
                </Property>
    captionLanguages
    Defines the language to be selected/presented by default if none is specified in the player connection URL (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").

    The default value is "*", which means that the first caption language found is used.

    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 selected/presented by default for Apple HLS (Cupertino) streaming if none is specified in the player connection URL (for more information, see How to configure closed captioning language selection for video on demand streaming).

    The semantics for this property are the same as for the captionLanguages property.
                <Property>
                    <Name>cupertinoCaptionLanguages</Name>
                    <Type>String</Type>             
                    <Value>*</Value>
                </Property>
    rtmpCaptionLanguages
    Defines the language to be selected/presented by default for RTMP streaming if none is specified in the player connection URL (for more information, see How to configure closed captioning language selection for video on demand streaming).

    The semantics for this property are the same as for the captionLanguages property.
                <Property>
                    <Name>rtmpCaptionLanguages</Name>
                    <Type>String</Type>             
                    <Value>*</Value>
                </Property>
    sanJoseCaptionLanguages
    Defines the language to be selected/presented by default for Adobe HDS (San Jose) streaming if none is specified in the player connection URL (for more information, see How to configure closed captioning language selection for video on demand streaming).

    The semantics for this property are the same as for the captionLanguages property.
                <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.
                <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}.
                <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 to the HTTPStreamers.xml file under each streamer type.
                <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.
                <Property>
                    <Name>cupertinoDebugVODCaptionLanguageSelection</Name>
                    <Type>Boolean</Type>             
                    <Value>true</Value>
                </Property>
    rtmpDebugVODCaptionLanguageSelection
    Enables language selection logging for RTMP streaming.
                <Property>
                    <Name>rtmpDebugVODCaptionLanguageSelection</Name>
                    <Type>Boolean</Type>             
                    <Value>true</Value>
                </Property>
    sanJoseDebugVODCaptionLanguageSelection
    Enables language selection logging for Adobe HDS (San Jose) streaming.
                <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.
                <Property>
                    <Name>cupertinoDebugVODCaptionProviderDetermination</Name>
                    <Type>Boolean</Type>             
                    <Value>true</Value>
                </Property>
    rtmpDebugVODCaptionProviderDetermination
    Enables caption provider determination logging for RTMP streaming.
                <Property>
                    <Name>rtmpDebugVODCaptionProviderDetermination</Name>
                    <Type>Boolean</Type>             
                    <Value>true</Value>
                </Property>
    sanJoseVODDebugCaptionProviderDetermination
    Enables caption provider determination logging for Adobe HDS (San Jose) streaming.
                <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>


    Updated: For Wowza Media Server 3.6.0 on 05-28-2013

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