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