Tuning

Overview

Tuning parameters modify the default processing behavior of media platform components like speech recognition or speech synthesis. You can use common settings defined in VoiceXML or you can use proprietary settings of the media platform, both for applications running in the voice or video channel. In addition, some VoiceObjects specific parameters exist that apply to the text and Web channel mainly.
Each setting can be dynamically set at call time by specifying layer settings for language, input mode, media platform driver, channel, or by defining a custom layer.

Tuning parameters defined in Module objects may be inherited by the objects that are part of the Module object’s sequence (see Options).

The paragraph Tuning Definition describes how to define tuning using VoiceObjects Desktop. For information on how to define it using VoiceObjectsXML refer to the VoiceObjectsXML Definition paragraph. The table of available predefined tuning parameters covers both VoiceObjects Desktop and VoiceObjectsXML notation.

Tuning Definition

Tuning parameters can be defined in the Tuning section of the respective object editors (entered by clicking it in the Outline in Desktop for Eclipse; represented by a tab in Desktop for Web).

For each Parameter you can specify the following properties:

Property	Description
Label	Optional setting to identify the tuning parameter in a list.
Layer	Specifies a layer via a Variable, Expression, Layer, or Script object to dynamically enable or disable the tuning parameter.
Channel	Specifies a channel as an optional filter condition for the parameter.
Language	Specifies a language as an optional filter condition for the parameter.
Input mode	Specifies an input mode as an optional filter condition for the parameter.
Driver	Specifies a media platform driver as an optional filter condition for the parameter.
Parameter	Choose a predefined parameter or select Custom to define a custom or proprietary parameter. If you choose a predefined parameter its description will be displayed in the text field below (respectively to the right in Desktop for Web). The description holds the name of the parameter followed by the actual tuning property written into the VoiceXML code (in parentheses), for applications run in the voice or video channel. All parameters apply to the voice and video channel only, unless stated otherwise. For a list of all available predefined parameters see Tuning Parameters below. If you choose Custom in the Parameter field, enter a custom parameter in the Custom field (displayed dynamically in Desktop for Eclipse). This can be done by either typing it in or specifying it via a Variable, Expression, Layer, or Script object.
Value	A valid value for the parameter. This can be provided by either typing it in or specifying it via a Variable, Expression, Layer, or Script object.

Options

Tuning parameters defined in Module objects are inherited by the objects that are part of the Module object’s sequence.

Inheritance can be disabled (False) or enabled (True, the default) within the Options section.

VoiceObjectsXML Definition

Tuning parameters are defined using the <tuning> element. It provides the inheritance attribute indicating whether tuning settings from a parent object should be used (true, the default) or not (false). In addition, it uses one or more <tuningItem> elements as children to define the individual tuning settings.

The <tuningItem> element provides the following seven attributes:

· label
A text string providing a name for the tuning item.

· parameter [required]
The name of the tuning parameter to be set. Can either be one of the predefined parameters or a custom parameter.
For a list of all available predefined parameters see Tuning Parameters below.

· value [required]
The value for the tuning parameter. May be a constant value or a reference to an Expression, Script, or Variable object.

· language
Defines the relevant language for the tuning item. Can be default or a valid language code (e.g. de-DE, en-US, etc.). If not specified, defaults to default.
Appendix A – Language Codes contains a list of all language codes available in VoiceObjects together with the respective language they represent.

· inputMode
Defines the input mode for which this tuning item is valid. Can be default, voice, dtmf, or voicedtmf. If not specified, defaults to default.

· layer
Defines the layer for the tuning item. Can either be a reference to a Collection, Expression, Script, or Variable object; or a layer state reference of the form “Layer=State” or “Layer!=State” where “State” is the label of a state for the layer “Layer”.

· driver
Defines the media platform driver for which the tuning setting is applicable. The list is provided in the Document Type Definition (DTD).
If not specified, defaults to default.

· channel
Defines the channel for which the tuning setting is applicable. Can be voice, video, text, web, voiceVideo, or textWeb. If not specified, defaults to default.

Tuning Parameters

The following table lists all available predefined tuning parameters with a description of what you can use them for.

The Parameter column mentions the names as listed in VoiceObjects Desktop, followed by the names used in VoiceObjectsXML.

In the Description column you can find the actual tuning property written into the VoiceXML code (in parentheses), for applications run in the voice or video channel.

Parameter	Description
Infostore – Input State Name VoiceObjectsXML: INFInputStateName	The parameter Input State Name optionally defines the name under which an input state is logged in Infostore. By default, the name of the object generating the input state is used.
Input – Barge-in Type VoiceObjectsXML: ASRBargeinType	The parameter Barge-in Type (bargeintype) indicates what kind of input from the caller can interrupt the playback of a prompt or audio output. Possible values for this parameter are dependent on the media platform used. Example values for the VoiceGenie media platform are: energy - any noise can barge in on a prompt; speech (default value) - any caller utterance can barge in on a prompt; recognition - only barges in on a prompt when the caller input matches a grammar.
Input – Complete Timeout VoiceObjectsXML: ASRCompleteTimeout	The parameter Complete Timeout (completetimeout) specifies the amount of time to wait for additional input from the caller after the speech recognition engine has recognized speech input matching one of the input grammars. A long complete timeout value delays the recognition completion and therefore makes the application response slow. A short complete timeout may lead to a grammar utterance being broken up inappropriately. Reasonable complete timeout values are typically in the range of 0.3 to 1.5 seconds. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 0.5s or 700ms). The default value is media platform dependent.
Input – Confidence Level VoiceObjectsXML: ASRConfidenceLevel	The parameter Confidence Level (confidencelevel) is specified with a float value in the range of 0.0 (minimum confidence) to 1.0 (maximum confidence). Speech recognition results are rejected when the recognition confidence is below the specified threshold. Setting this parameter higher will result in fewer false recognitions at the cost of more No Match events. Setting it lower will reduce the number of No Match events at the risk of more false recognitions. The default value is 0.5.
Input – DTMF Inter-Digit Timeout VoiceObjectsXML: DTMFInterDigitTimeout	The parameter DTMF Inter-Digit Timeout (interdigittimeout) is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 3s or 2500ms). It controls the amount of time that the speech recognition engine waits for another DTMF input before it decides that the caller has finished entering digits and returns a recognition or a No Match event. The default value is media platform dependent.
Input – DTMF Termination Key VoiceObjectsXML: DTMFTermChar	The parameter DTMF Termination Key specifies the (optional) terminating character for DTMF recognition. If this parameter is set, the caller can finalize the DTMF input with the specified key press. The default value is the hash character.
Input – DTMF Termination Timeout VoiceObjectsXML: DTMFTermTimeout	The parameter DTMF Termination Timeout (termtimeout) is a time designation expressed as an unsigned number by s for time in seconds; ms for time in milliseconds (e.g. 2s or1500ms). It specifies the terminating timeout to use when recognizing DTMF input. The timeout is activated when the last DTMF input has brought the grammar to a termination point at which no additional DTMF input is allowed by the grammar. If a DTMF termination key is defined, the caller can enter this DTMF key within the given timeout. If the caller fails to enter this optional DTMF key, the DTMF recognition ends and the recognized value is returned. The default timeout value is 0s.
Input – Incomplete Timeout VoiceObjectsXML: ASRIncompleteTimeout	The parameter Incomplete Timeout (incompletetimeout) specifies the amount of time to wait for additional speech input when the caller has begun speaking but the input does not yet match a complete grammar. Once the timeout is activated, the partial recognition result is rejected by the media platform with a No Match event. A long incomplete timeout value delays the recognition completion and therefore makes the application response slow. A short incomplete timeout may lead to an in-grammar utterance being broken up inappropriately. The incomplete timeout is usually longer than the complete timeout to allow the caller to pause mid-utterance (for example, to breathe). Reasonable incomplete timeout values are typically in the range of 0.3 to 1.5 seconds. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 0.5s or 700ms). The default value is media platform dependent.
Input – Input modes VoiceObjectsXML: ASRInputModes	The parameter Input Modes (inputmodes) determines which input modality to use: DTMF and/or voice. Speech recognition is disabled when setting the value to dtmf. DTMF recognition is disabled when setting the value to voice. Both modes are enabled when using the value dtmf voice or voice dtmf, which is the default for media platforms that support both input modes.
Input – Max N-Best VoiceObjectsXML: ASRMaxNBest	The parameter Max N-Best (maxnbest) controls the maximum number of N-best results returned by the speech recognition engine. It is an integer value greater than or equal to 1. Note that the actual number of N-best results returned by the speech recognition engine may be smaller than the value provided by Max N-Best.
Input – Max Speech Duration VoiceObjectsXML: ASRMaxSpeechTimeout	The parameter Max Speech Duration (maxspeechtimeout) controls the maximum duration of speech input from the caller. If this time elapses before the caller stops speaking, the event ASR – Max Speech Duration is thrown by the media platform. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 6s or 4500ms). The default duration is media platform dependent.
Input – Recognition Speed vs. Accuracy VoiceObjectsXML: ASRSpeedVsAccuracy	The Recognition Speed vs. Accuracy (speechvsaccuracy) parameter is a float value between 0.0 (fastest recognition) and 1.0 (best accuracy). It lets you control the trade-off between speed and accuracy in the speech recognition engine. Lower values cause potential recognition results with a low probability to be pruned early in the search process, resulting in faster recognition speed. Higher values retain potential recognition results longer, resulting in slower but more accurate recognitions. The default value is 0.5.
Input – Sensitivity Level VoiceObjectsXML: ASRSensitivity	The parameter Sensitivity Level (sensitivity) is specified with a float value in the range of 0.0 (least sensitive to noise) to 1.0 (highly sensitive to quiet input). It controls the sensitivity of the speech recognition process. Higher values will allow the speech recognition engine to recognize softer speech input but will also pick up more background noise. This parameter may need to be tuned downward if the voice application is used in noisy environments, or upward if it is used in very quiet environments. The default value is 0.5.
Input – Speech Timeout VoiceObjectsXML: ASRTimeout	The parameter Speech Timeout (timeout) specifies the maximum time the speech recognition engine waits for caller input. After the specified amount of time has lapsed, a No Input event is thrown by the media platform. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 3.1s or 2400ms). The default value is set to 3s at the VoiceObjects media platform driver level.
Input – Universal Commands VoiceObjectsXML: ASRUniversals	The parameter Universal Commands (universals) specifies which universal command grammars should be active within the voice dialog. The value is one of: all - make all universal grammars active; none - deactivate all universal grammars; a space-separated list of the universal grammar names (e.g. help exit cancel) - make the specified grammars active and all non-specified grammars inactive. Usually the following three universal commands are supported: help - the caller is asking for help; exit - the caller is asking to exit the application; cancel - the caller is asking to cancel the prompt that is being played. The default value is set to help at the VoiceObjects media platform driver level for all media platforms supporting universal commands. Some media platforms may optionally provide platform-specific universal command grammars. For example the Nuance Café media platform does support the command goback - the caller wants to retract the last response and go back to an earlier part of the dialog interaction.
Output – TTS Engine VoiceObjectsXML: TTSEngine	The parameter TTS Engine tells the media platform which TTS (text-to-speech) engine to use. It is valid to specify a particular engine (e.g. for a specific female or male voice) only if that engine is installed on the media platform being used to run this application. This parameter is media platform specific and is only supported by the following vendors: VoiceGenie, Voxpilot and Nuance Café. For further detail see the relevant media platform documentation.
Presentation – Bottom Logo URL VoiceObjectsXML: PRESBottomLogoURL	The parameter Bottom Logo URL only applies to the Web channel. Use it to specify a URL of an image file that will be added to the bottom of the page. By default, there is no Bottom Logo URL defined. Note that in a multi-tenant environment, the Resource Locator URL of the site settings is applied to the URL.
Presentation – Input VoiceObjectsXML: PRESInput	The parameter Input only applies to the text and Web channel. Use it to specify how the grammar of an Input object is to be presented. In the text channel, it can have the values text (grammar not displayed/available, free entry of text) or menu (grammar displayed as a menu of labeled items). In the Web channel, it can have the values text (text area for free input), password (text area for free input in password mode), menu (grammar displayed as a set of hyperlinks), radio (grammar displayed as radio-buttons), checkbox (grammar displayed as checkbox), or list (grammar displayed as a drop-down list). The default value depends on the number of entries in the grammar. In the text channel, password is interpreted as text, while radio and list are interpreted as menu.
Presentation – Input Maximum Length VoiceObjectsXML: PRESInputMaxLength	The parameter Maximum Length only applies to the Web channel. It specifies the maximum allowed length of input fields, i.e. the number of characters the caller is allowed to type in an input field. By default, no maximum is defined.
Presentation – Menu VoiceObjectsXML: PRESMenu	The parameter Menu only applies to the Web channel. Use it to specify how the items of a Menu object are to be displayed. It can have the values horizontal (all Menu items in one row), vertical (all items below each other), 2columns (two items per row), 3columns (three items per row). The default is vertical.
Presentation – Proceed Key VoiceObjectsXML: PRESProceedKey	The parameter Proceed Key only applies to the text channel. It defines the key that activates the “proceed” button in standalone outputs. No default key is defined, which means that the USSD gateway selects one.
Presentation – Proceed Label VoiceObjectsXML: PRESProceedLabel	The parameter Proceed Label only applies to the text and Web channel. It allows localizing the displayed label of the “proceed” button in standalone outputs. The default value is >>.
Presentation – Slot Label VoiceObjectsXML: PRESSlotLabel	The parameter Slot Label only applies to the Web channel. It specifies the labels to show in front of Input object slots (if any). Labels can contain text or markup and can be defined per slot, using the following syntax: label1(slot1),label2(slot2), ... By default, no slot labels are defined.
Presentation – Style Sheet URL VoiceObjectsXML: PRESCSSURL	The parameter Style Sheet URL only applies to the Web channel. Use it to specify a URL pointing to a CSS file that acts as a style sheet for the rendered XHTML page. By default, Platform\Resources\System\StyleSheet\default.css is used. Note that in a multi-tenant environment, the Resource Locator URL of the site settings is applied to the URL.
Presentation – Top Logo URL VoiceObjectsXML: PRESTopLogoURL	The parameter Top Logo URL only applies to the Web channel. Use it to specify a URL of an image file that will be added to the top of the page. By default, there is no Top Logo URL defined. Note that in a multi-tenant environment, the Resource Locator URL of the site settings is applied to the URL.
Resource Fetching – Audio Fetch Hint VoiceObjectsXML: RFAudioFetchHint	The parameter Audio Fetch Hint (audiofetchhint) tells the media platform whether or not audio files may be pre-fetched. The value is either: prefetch (default) - permit, but do not require, the media platform to prefetch audio files; or safe - fetch audio files only when they are needed, never before.
Resource Fetching – Audio Max Age VoiceObjectsXML: RFAudioMaxAge	The parameter Audio Max Age (audiomaxage) tells the media platform the maximum acceptable age of cached audio files. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 86400s). An unexpired cached file that does not exceed the maximum age will be used; a cached file that exceeds the maximum will be fetched again. The default value is media platform specific.
Resource Fetching – Audio Fetch Stale VoiceObjectsXML: RFAudioMaxStale	The parameter Audio Max Stale (audiomaxstale) tells the media platform the maximum acceptable time during which expired cached audio files can still be used. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 300s). A cached file that has been expired for more than the maximum stale time will be re-fetched; one that has been stale for less than or equal to the maximum stale time will be used. The default value is media platform specific.
Resource Fetching – Text Max Age VoiceObjectsXML: RFTextMaxAge	The parameter Text Max Age tells VoiceObjects Server the maximum acceptable age of cached text files. The value is a time designation expressed as an unsigned number in seconds (e.g. 86400). An unexpired cached file that does not exceed the maximum age will be used; a cached file that exceeds the maximum will be fetched again. The default value is 86400 seconds, corresponding to one day.
Resource Fetching – Document Fetch Hint VoiceObjectsXML: RFDocumentFetchHint	The parameter Document Fetch Hint (documentfetchhint) tells the media platform whether or not VXML files may be pre-fetched. The value is either: prefetch (default) - permit, but do not require, the media platform to pre-fetch VXML files; or safe - fetch VXML files only when they are needed, never before.
Resource Fetching – Document Max Age VoiceObjectsXML: RFDocumentMaxAge	The parameter Document Max Age (documentmaxage) tells the media platform the maximum acceptable age of cached VXML files. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 86400s). An unexpired cached file that does not exceed the maximum age will be used; a cached file that exceeds the maximum will be fetched again. The default value is media platform specific.
Resource Fetching – Document Max Stale VoiceObjectsXML: RFDocumentMaxStale	The parameter Document Max Stale (documentmaxstale) tells the media platform the maximum acceptable time during which expired cached VXML files can still be used. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 300s). A cached file that has been expired for more than the maximum stale time will be re-fetched; one that has been stale for less than or equal to the maximum stale time will be used. The default value is media platform specific.
Resource Fetching – Fetch Timeout VoiceObjectsXML: RFFetchTimeout	The parameter Fetch Timeout (fetchtimeout) tells the media platform the general timeout period for resource fetches. The media platform will wait this long for a requested resource to be returned before throwing an “error.badfetch" event. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 60s or 30000ms). The default value is media platform dependent.
Resource Fetching – Grammar Fetch Hint VoiceObjectsXML: RFGrammarFetchHint	The parameter Grammar Fetch Hint (grammarfetchhint) tells the media platform whether or not grammar files may be pre-fetched. The value is either: prefetch (default) - permit, but do not require, the media platform to pre-fetch grammar files; or safe - fetch grammar files only when they are needed, never before.
Resource Fetching – Grammar Fetch Options VoiceObjectsXML: RFGrammarFetchOptions	The parameter Grammar Fetch Options provides optional additional information to the media platform on how to fetch grammar files. Any number of options may be set separated by blanks in the format option=value (without quotes around the value). When working with Voxeo Prophecy it can e.g. be used to set voxeo:useuri=true in order to bypass grammar conversion.
Resource Fetching – Grammar Max Age VoiceObjectsXML: RFGrammarMaxAge	The parameter Grammar Max Age (grammarmaxage) tells the media platform the maximum acceptable age of cached grammar files. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 86400s). An unexpired cached file that does not exceed the maximum age will be used; a cached file that exceeds the maximum will be fetched again. The default value is media platform specific.
Resource Fetching – Grammar Max Stale VoiceObjectsXML: RFGrammarMaxStale	The parameter Grammar Max Stale (grammarmaxstale) tells the media platform the maximum acceptable time during which expired cached grammar files can still be used. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 300s). A cached file that has been expired for more than the maximum stale time will be re-fetched; one that has been stale for less than or equal to the maximum stale time will be used. The default value is media platform specific.
Resource Fetching – Object Fetch Hint VoiceObjectsXML: RFObjectFetchHint	The parameter Object Fetch Hint (objectfetchhint) tells the media platform whether or not files referenced in an <object> element may be pre-fetched. The value is either: prefetch (default) - permit, but do not require, the media platform to pre-fetch VXML files; or safe - fetch VXML files only when they are needed, never before.
Resource Fetching – Object Max Age VoiceObjectsXML: RFObjectMaxAge	The parameter Object Max Age (objectmaxage) tells the media platform the maximum acceptable age of cached files referenced in an <object> element. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 86400s). An unexpired cached file that does not exceed the maximum age will be used; a cached file that exceeds the maximum will be fetched again. The default value is media platform specific.
Resource Fetching – Object Max Stale VoiceObjectsXML: RFObjectMaxStale	The parameter Object Max Stale (objectmaxstale) tells the media platform the maximum acceptable time during which expired cached files referenced in an <object> element can still be used. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 300s). A cached file that has been expired for more than the maximum stale time will be re-fetched; one that has been stale for less than or equal to the maximum stale time will be used. The default value is media platform specific.
Resource Fetching – Script Fetch Hint VoiceObjectsXML: RFScriptFetchHint	The parameter Script Fetch Hint (scriptfetchhint) tells the media platform whether or not VXML files may be pre-fetched. The value is either: prefetch (default) - permit, but do not require, the media platform to pre-fetch VXML files; or safe - fetch VXML files only when they are needed, never before.
Resource Fetching – Script Max Age VoiceObjectsXML: RFScriptMaxAge	The parameter Script Max Age (scriptmaxage) tells the media platform the maximum acceptable age of cached script files. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 86400s). An unexpired cached file that does not exceed the maximum age will be used; a cached file that exceeds the maximum will be fetched again. The default value is media platform specific.
Resource Fetching – Script Max Stale VoiceObjectsXML: RFScriptMaxStale	The parameter Script Max Stale (scriptmaxstale) tells the media platform the maximum acceptable time during which expired cached script files can still be used. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 300s). A cached file that has been expired for more than the maximum stale time will be re-fetched; one that has been stale for less than or equal to the maximum stale time will be used. The default value is media platform specific.
Resource Fetching – Wait Audio Delay VoiceObjectsXML: RFFetchAudioDelay	The parameter Wait Audio Delay (fetchaudiodelay) is the amount of time to wait after a resource download is started by the media platform before the wait audio clip is played in the background. This parameter is useful to keep the period of silence short before the audio clip starts playing. If the resource download completes during the period of silence, the audio clip will not be played at all. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 2s or 2500ms). The default value is media platform dependent.
Resource Fetching – Wait Audio Minimum VoiceObjectsXML: RFFetchAudioMinimum	The parameter Wait Audio Minimum (fetchaudiominimum) specifies a time interval to play a wait audio clip (see Wait Audio URL), once started, even if the resource download completes in the meantime. The idea is that once the caller does begin to hear the wait audio clip, it should not be stopped too quickly. The value is a time designation expressed as an unsigned number followed by s for time in seconds; ms for time in milliseconds (e.g. 2s or 2500ms). The default value is media platform dependent.
Resource Fetching – Wait Audio URL VoiceObjectsXML: RFFetchAudio	The parameter Wait Audio URL (fetchaudio) specifies the URL of an audio clip to be played back while waiting for a resource to be fetched by the media platform. The default behavior of most of the media platforms is not to play any audio clip. The playing of the audio clip is governed by the parameters Wait Audio Delay, and Wait Audio Minimum in effect at the time of the fetch.