# Properties Reference

Properties are used to set values that affect platform behavior. Properties apply to their parent element and all the descendants of the parent. A property at a lower level overrides a property at a higher level.

Note that the properties in `defaults.vxml` will be (re)set as documented below only when a system is fresh-installed. If you simply upgrade from a previous release, the old values will be preserved. This means that any manual configuration of `defaults.vxml` will be saved when you upgrade. Unfortunately, it also means that when moving to newer versions in which VoiceGenie uses different default values, the defaults will not be reset unless you fresh-install (rather than upgrade).

Note that properties are not case-sensitive.

Speech Recognizer Properties

Property | Description | Default Value
confidencelevel | Specifies the speech recognition confidence level. Values range from 0.0 (minimum confidence) to 1.0 (maximum confidence). Recognition results are rejected (a `nomatch` event is thrown) if the confidence level of the results is below this threshold. | 0.5
sensitivity | Specifies the level of sensitivity to speech. Values range from 0.0 (least sensitive to noise) to 1.0 (highly sensitive to quiet input). | 0.5
speedvsaccuracy | A hint specifying the desired balance between speed vs. accuracy when processing a given utterance. Values range from 0.0 (fastest recognition) to 1.0 (best accuracy). | 0.5
completetimeout | The length of silence required following user speech before the speech recognizer finalizes a result (either accepting it or throwing a `nomatch` event). The completetimeout is used when the speech is a complete match of an active grammar and no further words can be spoken. (Not used if `com.voicegenie.tddparaminuse` is set to true.) | 0.4s
incompletetimeout | The length of silence required following user speech before the speech recognizer finalizes a result (either accepting it or throwing a `nomatch` event). In contrast to `completetimeout`, the incompletetimeout is used when the speech is an incomplete match to an active grammar, or when the speech is a match but it is possible to speak further. May not work correctly if set to 10s or more. (Not used if `com.voicegenie.tddparaminuse` is set to true.) | 1s
maxspeechtimeout | The maximum duration of user speech. If this time elapsed before the user stops speaking, the `maxspeechtimeout` event is thrown. SpeechWorks allows values in {1ms,99999ms} For Watson, 0 means no limit | 20s (OSR) 0 (Watson)
maxnbest | Maximum number of results returned by the recognizer. Also represents the maximum size of the `application.lastresult$[i]` array. With the `com.voicegenie.STRICTCONFORMANCE` property set to `FALSE`), the `application.lastresult$` array may be filled with more results than specified by this property (if more results are available from the ASR engine). | 1
asrinittimeout (extension) | The maximum length of time for ASR loading. (Note that "ASR loading" is not the same as "grammar loading". Instead, it has to do with the engine getting ready for ASR sessions. The platform may be configured for this to happen only at the beginning of the first recognition session, or once for each recognition session.) If the maximum is reached, an `error.asr` will be thrown. | 30s

DTMF Recognizer Properties

Property | Description | Default Value
interdigittimeout | The timeout period allowed between each digit when recognizing DTMF input. | 3s
termtimeout | The terminating timeout to use when recognizing DTMF input. | 0s
termchar | The terminating DTMF character for DTMF input recognition. | #

Prompt and Collect Properties

Property | Description | Default Value
inputmodes | Determines which input methods to use. Value is a space separated list of input methods: dtmf - allows DTMF sequences as input voice - allows voice as input tdd - allows TDD as input (extension; only supported if the platform is provisioned with the Dialogic TDD recognizer). | dtmf voice
timeout | Once the prompt has finished playing, the length of time to wait, if no speech or dtmf input occurs, before throwing a `noinput` event. | 10s
universals | Specifies universal command grammars to activate. Value is a space-separated list of all or fewer of the following command grammars: cancel - If this grammar is activated, and the caller says "cancel" (or equivalent phrase configured for another language), the `cancel` event is thrown. exit - If this grammar is activated, and the caller says "exit" (or equivalent phrase configured for another language), the `exit` event is thrown. help - If this grammar is activated, and the caller says "help" (or equivalent phrase configured for another language), the `help` event is thrown. A setting of "none" disables universal commands. A setting of "all" can be used as a short form for activating all 3 command grammars. | none
asrengine (extension) | Specifies the name of the ASR (Automatic Speech Recognition) engine to use. The name is configured in the VXML 2.0 Provisioning text field through the Media Server > VXML page in the Web UI. It is valid to specify a particular engine only if that engine is installed for the platform running the application. Otherwise, an `error.asr.unknownengine` event will be thrown. See the IP Media Server Release Notes for the list of currently supported engines and languages. Note: The configured name for SpeechWorks OSR must be "SPEECHWORKS", otherwise a recognition error will occur. | platform-specific
ttsengine (extension) | Specifies the name of the TTS (Text-to-Speech) engine to use (i.e. the voice). The name is configured in the VXML 2.0 Provisioning text field through the Media Server > VXML page in the Web UI. It is valid to specify a particular engine only if that engine is installed for the platform running the application. Otherwise, an `error.tts.unknownengine` event will be thrown. | platform-specific
com.voicegenie.grammartype.<asrengine> For example: com.voicegenie.grammartype.speechworks com.voicegenie.grammartype.watson (extension) | Changes the grammar type to be used as the inline default when using <asrengine>, so that the specified grammar type can be used without including the `type` attribute. It is valid to specify a particular grammar type only if the <asrengine> supports that grammar type. | platform-specific
endbeep (extension) | Specifies whether or not a beep should be played at the end of prompts in fields, when bargein is disabled. When bargein is enabled, this attribute has no effect (there is never a beep). | false
com.voicegenie.fieldobject (extension) | Specifies the format used when a set of slot/value pairs to a field `name` or `<name>``$.interpretation` variable, or to the `application.lastresult$[i].interpretation` variables. If set to true, each applicable variable is set to an ECMAScript object, containing a property for each slot name, and a property value for each corresponding slot value. If set to false, they will be set to strings with the format +[?]slot1:value1[:score1]+[?]slot2:value2[:score2]+... Note: This property does not affect variables that are being assigned a single string value, rather than a set of slot/value pairs. | true
com.voicegenie.saveutterance (extension) | Set to true to enable user utterance to be recorded. Set to false otherwise. Upon completion of user input, the shadow variables that may be set are `utteranceaudio`/`recording`, `size`, and `duration`. Note: With the implementation of the VoiceXML 2.1 `recordutterance` property, the use of this property is discouraged. | false
com.voicegenie.utterancedest (extension) | Specifies the path of the directory to use for saved utterance audio files. The value will be resolved relative to the `/usr/local/phoneweb/utterance/` directory. Can be used with either the `com.voicegenie.saveutterance` or `recordutterance` property. | files are written to the tmp directory (may or may not be saved)
recordutterance (VoiceXML 2.1 feature) | This property tells the platform to enable recording while simultaneously gathering input from the user. Set to true to enable user utterance to be recorded. Set to false otherwise. Upon completion of user input, the shadow variables that will be set are `recording`, `recordingsize`, and `recordingduration`. Note that the `<vxml>` `version` attribute must be specified as 2.1 (or higher) to use this property. | false
recordutterancetype (VoiceXML 2.1 feature) | This property specifies the audio format to use for recording utterances. Only used with the `recordutterance` property. VoiceGenie currently supports the following types: audio/basic - Raw (headerless) 8kHz 8-bit mono mu-law [PCM] single channel. (G.711) audio/x-alaw-basic - Raw (headerless) 8kHz 8-bit mono A-law [PCM] single channel. (G.711) audio/x-wav - WAV (RIFF header) 8kHz 8-bit mono mu-law [PCM] single channel. audio/x-wav - WAV (RIFF header) 8kHz 8-bit mono A-law [PCM] single channel. | audio/basic
com.voicegenie.asr.get_swi_literaltimings (extension) | Set to true to allow the special OSR variable, SWI_literalTimings, to be accessed through the `application.lastresult$` variable. (Requires `com.voicegenie.fieldobject` to be set to true.) See SWI_literalTimings for more details. (Available with SpeechWorks ASR only.) | false
swiep_*/swirec_* (extension) | Many of OSR's swiep_*/swirec_* configuration parameters can also be set as VoiceXML properties. To find out whether a particular parameter can be set as a property, look it up in the OSR Reference Manual. If the line under the parameter name includes "API" (and if the description mentions `SWIepSetParameter()` or `SWIrecRecognizerSetParameter()`), then it can be set as a property. Some of the parameters that are commonly used are: swirec_suppress_event_logging swirec_suppress_waveform_logging swirec_audio_environment (OSR 2.0+ only) swirec_backward_compatible_confidence_scores (OSR 2.0+ only) (Available with SpeechWorks OSR only.) | parameter-specific
com.voicegenie.serverselect (extension) | Specifies the IP address of a particular ASR server to switch to, or the name of a configured group of ASR servers from which to pick a server to switch to. (Available with SpeechWorks OSR 2.0+ only.) | (no default value)
com.att.asr.useActive (extension) | Set to false to support large directory/grammar enhancement to the Watson engine. This property can only be defined in the platform defaults file. (Available with Watson ASR only.) | false

Prompt and Collect Properties - Barge-in

Property | Description | Default Value
bargein | Controls whether or not user input can be collected before prompts have finished playing: true - Any user input can barge in during prompts. false - No user input can barge in during prompts. dtmf - Only DTMF input can barge in during prompts; speech input is ignored until the completion of the prompts; both speech and DTMF input can be collected after the completion of the prompts. With the `com.voicegenie.STRICTCONFORMANCE` property set to `FALSE`, a prompt with `bargein="true"` will cause bargein to remain enabled for all the remaining queued prompts, within a given input item. | true
bargeintype | Specifies the bargein type: energy - Any noise can barge in the prompt. speech - Any user utterance can barge in the prompt. recognition - Only user input that matches a grammar can barge in on the prompt. hotword (equivalent to recognition) - Only user input that matches a grammar can barge in on the prompt. Note: Not all bargeintypes are supported with all ASR engines. | speech
bargeinlevel (extension) | The confidence level required for bargein to work. Values range from 0.0 (minimum confidence) to 1.0 (maximum confidence). (Available with Watson ASR only; applied to portions of utterances that have been labeled with `_BargeIn` syntax to allow them to trigger bargein.) | 0.5
com.voicegenie.recognitionbargeinminimum (extension) | Minumum duration of the bargein phrase if `bargeintype` is set to recognition. (Value must be 0s-2s.) | 0.3s
com.voicegenie.recognitionbargeinmaximum (extension) | Maximum duration of the bargein phrase if `bargeintype` is set to recognition. (Value must be 0.5s-10s.) | 1.7s

Prompt and Collect Properties - Wakeup Word Spotting Recognition Mode

Note that this feature is supported only with ScanSoft (previously Nuance) Open Speech Recognizer (OSR).

Property | Description | Default Value
com.voicegenie.wakeupword (VoiceGenie extension) | Specifies whether or not Wakeup Word Spotting should be used for input in fields, menus, and initials. If set to true, recognition is only performed if input length is between a minimum and maximum length, and (only with Nuance OSR 2.0+) if input matches a grammar. [Available with ScanSoft (previously Nuance) OSR only.] | false
com.voicegenie.wakeupwordminimum (VoiceGenie extension) | If `com.voicegenie.wakeupword` is set to true, this specifies the minimum length that input must be in order for recognition to be performed. |
com.voicegenie.wakeupwordmaximum (VoiceGenie extension) | If `com.voicegenie.wakeupword` is set to true, this specifies the maximum length that input may be in order for recognition to be performed. |
com.voicegenie.wakeupwordranges (VoiceGenie extension) | Specifies range(s) of input lengths that trigger(s) recognition to be performed, if `com.voicegenie.wakeupword` is set to true. The value must have the following format: `min1``[ms|s]-max1[ms|s],...,minn[ms|s]-maxn[ms|s]` where `mini` and `maxi` are integers; `mini` must be less than `maxi`; the unit (`ms` or `s`) is optional (the default is milliseconds) Note: If all three of the wakeupword length properties are specified, then `com.voicegenie.wakeupwordranges` will take precedence over the others. This is not supported with ScanSoft (Nuance) OSR 2.0+. |

Prompt and Collect Properties - Magic Word / Selective Barge-in Recognition Modes

Property | Description | Default Value
COM.VOICEGENIE.ASR.Recognition-Mode (VoiceGenie extension) | Set to 'hotword' to enable the OSR selective barge-in or magic word recognition mode: Selective Barge-in: Only user input that matches a grammar can barge in on the prompt. (This mode is enabled if `COM.VOICEGENIE.ASR.Hotword-Max-Duration` is set to 0.) Magic Word: Only user input that matches a grammar, and whose duration is between a minimum and maximum length, can barge in on the prompt. For example:
    <property
    name="COM.VOICEGENIE.ASR.Recognition-Mode"
    value="&quot;hotword&quot;"/>
(Available with ScanSoft (Nuance) SWMS 3.1.4+ only.) |
COM.VOICEGENIE.ASR.Hotword-Min-Duration (VoiceGenie extension) | If `COM.VOICEGENIE.ASR.Recognition-Mode` is set to hotword, this specifies the minimum length (in ms) that input must be in order for recognition to be performed. For example:
    <property
    name="COM.VOICEGENIE.ASR.Hotword-Min-Duration"
    value="&quot;50&quot;"/>
If `COM.VOICEGENIE.ASR.Hotword-Max-Duration` is set to 0, this property will be ignored. |
COM.VOICEGENIE.ASR.Hotword-Max-Duration (VoiceGenie extension) | If `COM.VOICEGENIE.ASR.Recognition-Mode` is set to hotword, this specifies the maximum length (in ms) that input may be in order for recognition to be performed. For example:
    <property
    name="COM.VOICEGENIE.ASR.Hotword-Max-Duration"
    value="&quot;2000&quot;"/>
If this property is set to 0, the OSR selective barge-in mode will be enabled (i.e. no minimum and maximum duration constraints are used, so `COM.VOICEGENIE.ASR.Hotword-Min-Duration` will be ignored). Otherwise, the OSR magic word mode will be enabled (i.e. the minimum and maximum duration constraints specified by `COM.VOICEGENIE.ASR.Hotword-Min-Duration` and `COM.VOICEGENIE.ASR.Hotword-Max-Duration` will be used). |
COM.VOICEGENIE.ASR.Hotword-Confidence-Threshold (VoiceGenie extension) | If `COM.VOICEGENIE.ASR.Recognition-Mode` is set to hotword, this specifies the speech recognition confidence level that should be used. Values range from 0 (minimum confidence) to 1000 (maximum confidence). Recognition results are rejected (a `nomatch` event is thrown) if the confidence level of the results is below this threshold. For this property to take effect, you must also set the standard confidencelevel property to an equivalent decimal percentage. For example:
    <property
    name="COM.VOICEGENIE.ASR.Hotword-Confidence-Threshold"
    value="&quot;100&quot;"/>
    <property name="confidencelevel" value="0.1"/>

Fetching Properties

Property | Description | Default Value
audiofetchhint | Defines when audio files can be fetched: prefetch - audio file may be downloaded when the page is loaded safe - only load the audio file when needed stream - allows audio streaming with HTTP. | prefetch
audiomaxage | Defines maximum acceptable age, in seconds, of cached audio resources. | undefined
audiomaxstale | Defines maximum staleness, in seconds, of expired cached audio resources. | undefined
documentfetchhint | Defines when next document can be fetched: safe - only load the next document when needed | safe
documentmaxage | Defines maximum acceptable age, in seconds, of cached documents. | undefined
documentmaxstale | Defines maximum staleness, in seconds, of expired cached documents. | undefined
grammarfetchhint | Defines when grammar files can be fetched: prefetch - grammar file may be downloaded when the page is loaded safe - only load the grammar file when needed This is not supported with SpeechWorks OSR. | prefetch
grammarmaxage | Defines maximum acceptable age, in seconds, of cached grammar resources. SpeechWorks OSR 1.x does not support this. If `grammarmaxage` is specified, an appropriate value for `caching` will be passed to the OSR engine instead. | undefined
grammarmaxstale | Defines maximum staleness, in seconds, of expired cached grammar resources. SpeechWorks OSR 1.x does not support this. If `grammarmaxstale` is specified, an appropriate value for `caching` will be passed to the ASR engine instead. | undefined
objectfetchhint | Defines when objects can be fetched: prefetch - object may be downloaded when the page is loaded safe - only load the object when needed | prefetch
objectmaxage | Defines maximum acceptable age, in seconds, of cached object resources. | undefined
objectmaxstale | Defines maximum staleness, in seconds, of expired cached object resources. | undefined
scriptfetchhint | Defines when scripts can be fetched: prefetch - script may be downloaded when the page is loaded safe - only load the script when needed | prefetch
scriptmaxage | Defines maximum acceptable age, in seconds, of cached script resources. | undefined
scriptmaxstale | Defines maximum staleness, in seconds, of expired cached script resources. | undefined
fetchaudio | The URI of audio to play while waiting for documents to be fetched. | builtin:background_audio.wav
fetchaudiodelay | The length of time to wait at the start of a fetch delay before playing `fetchaudio`. | 1s
fetchaudiominimum | The minimum length of time to play `fetchaudio`, once started, even if the fetch result arrives in the meantime. | 0s
fetchtimeout | Timeout for fetches. The fetchtimeout property setting in the platform defaults file will be used when fetching: root documents the initial document of a call the initial document used by a forked instance any pages to which the platform is redirected (with an HTTP 3xx response code) An `error.badfetch` is thrown when a fetch duration exceeds fetchtimeout. | 30s

Audio Control Properties

The Audio Control Feature is an extension to VoiceXML.

Usage Note: These properties won't work if audio is being streamed.
Usage Note: Audio control functions are only applied to the currently playing prompt, and not across the queued prompt list.

Property | Description | Default Value
com.voicegenie.noaudiocontrol (extension) | If this property is set (to any value), the `com.voicegenie.audiocontrol` property is disabled. | undefined
com.voicegenie.audiocontrol (extension) | (Only used if `com.voicegenie.noaudiocontrol` is undefined.) Set to true to enable Audio Control during playing of audio. Set to false to disable the feature. | true
com.voicegenie.audio.skipduration (extension) | Sets the duration of audio to be skipped when using the `skipahead`/`skipback` features. The default unit is milliseconds. | 6000ms
com.voicegenie.audio.skipahead (extension) | Sets the DTMF button for skipping ahead in the audio file/TTS. The duration skipped depends on the value of the `com.voicegenie.audio.skipduration` property. If set to "-" or undefined, this feature is disabled. | undefined
com.voicegenie.audio.skipback (extension) | Sets the DTMF button for rewinding the audio file/TTS. The duration rewound depends on the value of the `com.voicegenie.audio.skipduration` property. If set to "-" or undefined, this feature is disabled. | undefined
com.voicegenie.audio.louder (extension) | Sets the DTMF button for turning volume up. If set to "-" or undefined, this feature is disabled. | undefined
com.voicegenie.audio.softer (extension) | Sets the DTMF button for turning volume down. If set to "-" or undefined, this feature is disabled. | undefined
com.voicegenie.audio.pause (extension) | Sets the DTMF button for pausing playback temporarily, until the pause button is pressed a second time. If set to "-" or undefined, this feature is disabled. | undefined
com.voicegenie.audio.stop (extension) | Sets the DTMF button for stopping all queued audio playback. If set to "-" or undefined, this feature is disabled. | undefined
com.voicegenie.audio.next (extension) | Sets the DTMF button for interrupting the current audio playback, and starting the next audio playback in the queue. If set to "-" or undefined, this feature is disabled. | undefined
com.voicegenie.audio.faster (extension) | Sets the DTMF button for increasing the rate of audio playback. If set to "-" or undefined, this feature is disabled. The IP Media Server does not currently support this property. | undefined
com.voicegenie.audio.slower (extension) | Sets the DTMF button for decreasing the rate of audio playback. If set to "-" or undefined, this feature is disabled. The IP Media Server does not currently support this property. | undefined
vgaudiocontrol (extension) | Deprecated. Use `com.voicegenie.audiocontrol` instead. | true
vgaudioskipahead (extension) | Deprecated. Use `com.voicegenie.audio.skipahead` instead. | undefined
vgaudioskipback (extension) | Deprecated. Use `com.voicegenie.audio.skipback` instead. | undefined
vgaudiolouder (extension) | Deprecated. Use `com.voicegenie.audio.louder` instead. | undefined
vgaudiosofter (extension) | Deprecated. Use `com.voicegenie.audio.softer` instead. | undefined
vgaudiopause (extension) | Deprecated. Use `com.voicegenie.audio.pause` instead. | undefined
vgaudiostop (extension) | Deprecated. Use `com.voicegenie.audio.stop` instead. | undefined

Miscellaneous Properties

Property | Description | Default Value
loglevel (extension) | Limits execution of `<log>` elements to the ones whose `level` attribute have a value up to (including) the loglevel value. This property can only be defined in the document scope or higher (i.e. as an immediate child of <vxml>). | 1
metricslevel (extension) | Controls the amount of detail logged to the metrics file (`pw_metricsfile`) on the platform. Here's the general type of metrics information at each level: 0 - inbound/outbound call states, and `<log>` content (see note below) 1 - level 0 detail + page compilation and application name 2 - level 1 detail + application end, prompt ends, and errors 3 - level 2 detail + document fetching, application traversal/states/events, prompts, and warnings 4 - level 3 detail + resource fetching (other than VoiceXML pages) 5 - level 4 detail + variable/script/expression evaluation Note that if `<log>`s are executed (which depends on the `loglevel`), their content is only written to the metrics file if specified by their `dest` attribute. This property can only be defined in the document scope or higher (i.e. as an immediate child of <vxml>). | 1
com.voicegenie.disablerecord (extension) | If this property is set (to any value), the `dest` attribute of the `<record>` element is disabled. This property can only be defined in the platform defaults file. | undefined
com.voicegenie.maxeventcount (extension) | Used to detect an infinitely looping event (to limit platform resource usage if a phone is left off the hook while an application is running). This property should be set to an integer value, to define the maximum count for any one event counter. Once the maximum is exceeded, the call will end. If undefined, there is no limit on the event counters. | 200
com.voicegenie.xmlencoding (extension) | An integer bit field to turn on/off encoding of various types of content before passing it to the ASR/TTS engines. This property can only be defined in the document scope or higher (i.e. as an immediate child of <vxml>). bit0 - Set to 1 to turn on encoding of SSML attribute values (or 0 to turn off). bit1 - Set to 1 to turn on encoding of SSML PCDATA (or 0 to turn off). bit2 - Set to 1 to turn on encoding of XML grammar attribute values (or 0 to turn off). bit3 - Set to 1 to turn on encoding of XML grammar PCDATA (or 0 to turn off). To use this property, take the desired setting for each of the 4 bits above (use 1 for any, if unsure), and put them together to get the 4-digit binary number <bit3><bit2><bit1><bit0>. Convert that to a decimal number and then to a hexadecimal number <hex#>. Finally, set the property value to "0x<hex#>". For example, to encode SSML attributes, SSML data, and XML grammar data, but not XML grammar attributes, the binary number is 1011, which is decimal 11, and hexadecimal b. So the property value should be "0xb". (Note that the default is "0xf". That is because the default for each bit is 1, so the binary default is 1111, which is decimal 15, and hexadecimal f.) | 0xf
com.voicegenie.useconnectionevent (extension) | Set to true to specify that the IP Media Server should throw `*connection*` events, where applicable. Set to false to specify that the platform should throw `*telephone*` events, instead. See Call-Related Events, for details. This property can only be defined in the document scope or higher (i.e., as an immediate child of <vxml>). | platform-specific
com.voicegenie.strictconformance (extension) | Set to true to specify that the interpreter should conform strictly to the VoiceXML 2.0 specification in certain scenarios, requiring a set of behaviour changes from previous versions. Set to false to choose not to make the set of changes. This property can be configured through the Media Server > VXML menu in the Dialogic(r) IP Media Server Web User Interface. See Strict Conformance for details. | platform-specific

Platform Properties

The following properties are specific to the IP Media Server platform. The first three are useful for debugging purposes.

Property | Description | Default Value
disablesavetmpfiles (extension) | If this property is set (to any value), the `savetmpfiles` property is disabled. This property can only be defined in the document scope or higher (i.e., as an immediate child of <vxml>). | undefined
savetmpfiles (extension) | (Only used if `disablesavetmpfiles` is undefined.) Saves all temporary files generated by the interpreter. See the FAQs for details. This property can only be defined in the document scope or higher (i.e., as an immediate child of <vxml>). Saving of temporary files should never be enabled on deployed systems except under the direction of Technical Support. | 0
com.voicegenie.maxrecordtime (extension) | Defines the default (also the upper limit) for the `maxtime` attribute of the `<record>` element. If not specified, the unit for the value is minutes. | 10 minutes