Adding parameters to session.xml

These parameters can appear in the session.xml. For more information, see Configuring sessions (session.xml).

These parameters appear in the <global> section of <sessionparameters>:

Parameter

Description

Value

application_name

Specifies the application name written to the call logs and used in the filepath to the logs.

String. Maximum length is 256 characters.

DEFAULT: MyApp
company_name

Specifies the company name written to the call logs and used in the filepath to the logs.

String. Maximum length is 256 characters.

DEFAULT: "Nuance"

These parameters appear in the <logging> section of <sessionparameters>:

Parameter

Description

Value

encryption_key

Specifies the public RSA encryption key in hexadecimal.

HEX string

DEFAULT: A sample key is defined in $NSSSVRSDK/config/example_session.xml for testing purposes only. For a deployed applications, the sample must be replaced.

encryption_key_tag

Specifies the label to identify a public encryption key.

String

DEFAULT: (none)

internal_encryption

Specifies the name of the mechanism to use for data encryption.

AES-192 or AES-256

DEFAULT: AES-192
wcr_enable

Enables whole-call recording (WCR) for this application session.

Boolean

DEFAULT: false (disabled)

Speech recognition

These parameters affect recognition. Set them in the <speechrecog> section of <speechserver> under <sessionparameters>:

Parameter

Description

Value

accept-charset

Specifies the acceptable character sets for entities returned in the response or events associated with this request.

Note: Ignored by Dragon Voice engines.

UTF-8, UTF-16, ISO-8859-1.

Values are case-sensitive. Use dashes when specifying in an MRCP header. Use underscores when specifying in session.xml. If this parameter is not specified, any character set is acceptable.

DEFAULT: (none)

cache-control.max-age

Use only cached data whose age is no greater than the specified time in seconds.

Integer: 0–INT_MAX (seconds), or -1 to disable (use normal caching).

DEFAULT: -1 (use no default)

cache-control.max-stale

Use only cached data that has exceeded its expiration time by up to the specified number of seconds.

Integer: 0–INT_MAX (seconds), or -1 to disable (use normal caching).

If no value is assigned to max-stale, the server may use stale data of any age.

DEFAULT: -1 (use no default)

cache-control.min-fresh

Use only cached data whose expiration time is no less than its current age plus the specified time in seconds.

Integer: 0–INT_MAX seconds

DEFAULT: 0 (seconds)

dtmf-buffer-time

Specifies the size of the type-ahead buffer.

Integer: 0–INT_MAX (milliseconds)

DEFAULT: 0

dtmf-interdigit-timeout

Specifies the maximum time allowed between each DTMF character entered by the user.

Integer: 0–INT_MAX (milliseconds)

DEFAULT: MRCP 5000

dtmf-term-char

Specifies the character that terminates DTMF input.

Nuance recommends that VoiceXML applications and Speech Server use the same default termination character. For example, since the VoiceXML default is # (the pound sign, also called the hash or number sign), you can change the Speech Server value to "#".

String. Any character on a telephone keypad.

DEFAULT:

VoiceXML: #

MRCP: NULL

dtmf-term-timeout

Specifies the time to wait for optional termination character (dtmf-term-char) after collecting the correct number of tones allowed by the grammar.

Integer: 0–INT_MAX

DEFAULT:

VoiceXML: 0 (seconds)

MRCP: 5000 (milliseconds)

fetch-timeout

Specifies the maximum time for the server to fetch content from the network.

Integer: 10–INT_MAX (milliseconds)

DEFAULT: MRCP 5000

grammar

Preload Recognizer speech grammar when the session starts.

Note: Ignored by Dragon Voice engines.

Filepath or URI.

DEFAULT: (none)

hotword-max-duration

Specifies the maximum length of an utterance that is considered for hotword recognition.

Note: Ignored by Dragon Voice engines.

Integer: 0–INT_MAX (milliseconds)

DEFAULT: 800

hotword-min-duration

Specifies the minimum length of an utterance that is considered for hotword recognition.

Note: Ignored by Dragon Voice engines.

Integer: 0–INT_MAX (milliseconds)

DEFAULT: 200

logging-tag

Specifies the text to write in the call log.

String

DEFAULT: (none)

media-type

Specifies the MIME content type in which to store audio captured with MRCP RECOGNIZE or RECORD.

Note: Ignored by Dragon Voice engines.

MIME content type

DEFAULT: audio/x-wav

new-audio-channel

Change to a new source for audio input captured with MRCP RECOGNIZE or RECORD.

Note: Ignored by Dragon Voice engines.

Boolean

DEFAULT: false

recognition-mode

Sets normal recognition or the special hotword mode.

This parameter applies to both Nuance Recognizer and the Krypton recognition engine; however, Krypton supports normal mode only.

Note: The Krypton recognition engine does not support hotword mode recognition.

normal, hotword

DEFAULT: normal

recognition-timeout

Maximum time for the recognizer to complete a recognition.

Integer: 0–INT_MAX milliseconds

DEFAULT: 10000 (10 sec MRCPv2) and 60000 (60 seconds MRCPv1)

save-waveform

Saves the current utterance and returns a URI pointer to the location.

Boolean

DEFAULT: 0 (don't save)

speech-language

Specifies the default language for built-in grammars.

Note: Ignored by Dragon Voice engines.

Language code for an installed language pack.

DEFAULT: en-US

start-input-timers

Start the recognizer’s input timers.

Boolean

DEFAULT: 1

Text to speech

These parameters affect text-to-speech. Set them in the <speechsynth> section of <speechserver> under <sessionparameters>:

Parameter

Description

Value

cache-control.max-age

Use only cached data whose age is no greater than the specified time in seconds.

Integer: 0–INT_MAX (seconds), or -1 to disable (use normal caching).

DEFAULT: -1 (use no default)

cache-control.max-stale

Use only cached data that has exceeded its expiration time by up to the specified number of seconds.

Integer: 0–INT_MAX (seconds), or -1 to disable (use normal caching).

If no value is assigned to max-stale, the server may use stale data of any age.

DEFAULT: -1 (use no default)

cache-control.min-fresh

Use only cached data whose expiration time is no less than its current age plus the specified time in seconds.

Integer: 0–INT_MAX seconds

DEFAULT: 0 (seconds)

fetch-timeout

Specifies the maximum time for the server to fetch content from the network.

Integer: 10–INT_MAX (milliseconds)

DEFAULT: MRCP 5000

lexicon-search-order

Specifies the list of active lexicon URIs and their search order.

String of absolute URIs, separated by spaces, in search order.

DEFAULT: (none)

logging-tag

Specifies the text to write in the call log.

String

DEFAULT: (none)

Call recorder

These parameters affect the call recorder. Set them in the <speechrecord> section of <speechserver> under <sessionparameters>:

Parameter

Description

Value

cache-control.max-age

Use only cached data whose age is no greater than the specified time in seconds.

Integer: 0–INT_MAX (seconds), or -1 to disable (use normal caching).

DEFAULT: -1 (use no default)

cache-control.max-stale

Use only cached data that has exceeded its expiration time by up to the specified number of seconds.

Integer: 0–INT_MAX (seconds), or -1 to disable (use normal caching).

If no value is assigned to max-stale, the server may use stale data of any age.

DEFAULT: -1 (use no default)

cache-control.min-fresh

Use only cached data whose expiration time is no less than its current age plus the specified time in seconds.

Integer: 0–INT_MAX seconds

DEFAULT: 0 (seconds)

capture-on-speech

Specifies whether to record immediately or wait until speech is detected.

Boolean.

DEFAULT: 0 (wait for speech)

fetch-timeout

Specifies the maximum time for the server to fetch content from the network.

Integer: 10–INT_MAX (milliseconds)

DEFAULT: MRCP 5000

logging-tag

Specifies the text to write in the call log.

String

DEFAULT: (none)

maxspeechtimeout

Specifies the maximum duration of an utterance collected from users.

Integer: -1, 1–INT_MAX (milliseconds)

DEFAULT: 22000 (22 seconds)

media-type

Specifies the MIME content type in which to store audio captured with MRCP RECOGNIZE or RECORD.

MIME content type

DEFAULT: audio/x-wav

new-audio-channel

Change to a new source for audio input captured with MRCP RECOGNIZE or RECORD.

Boolean

DEFAULT: false

trim-length

Specifies the length of audio trimmed from the end of the recording after the STOP.

Integer: 0–INT_MAX (milliseconds)

DEFAULT: 0

Set these Nuance Recognizer parameters in the <speechrecog> section of <sessionparameters>:

Parameter

Description

Value

swirec_acoustic_adapt_root

Specifies the storage location of self-learning files. Controls sharing of models across the server, tenants, or applications.

A directory path on the local machine

DEFAULT: (empty)

swirec_acoustic_adapt_suppress_adaptation

Temporarily stops self-learning activities for one or more languages.

Three boolean values, where each corresponds to a different CPU load (idle, normal, busy).The third value, for busy, is also used automatically for pegged. See swirec_load_adjusted_cpu_ranges for a discussion of these ranges.

Use 1 to suppress.

DEFAULT: (depends on language)

Some languages are 0, others are 1.

swirec_builtin_grammar_full_dtmf_mode

Includes "*#ABCD" in DTMF built-in grammars.

Boolean

DEFAULT: 0

swirec_diag_tags_enable

Controls the logged output by enabling tags in diagnostic log files.

Integers representing one or more tags in the TRC tagmap files.

DEFAULT: (none)

swirec_enable_robust_compile

Ignores missing pronunciations during grammar compilation.

Boolean

DEFAULT: 0 (disabled)

swirec_ignore_grammar_media_type

Ignores the media type that is returned by the server upon fetching a grammar. (It replaces the media type fetched from the server.)

Boolean

DEFAULT: 1 (ignore fetched type)

swirec_default_language

Sets a default language for built-in grammars.

A language code

DEFAULT: (the value of Recognizer’s DefaultLanguage parameter)

swirec_language_versions

Specifies the version of a Recognizer language to use.

Pairs of language codes and versions (installed Recognizer language packs).

DEFAULT: (most recent version of each language)

swirec_lmweight

Adds weight to match the dynamic ranges of language and acoustic models.

Float: 0.0 or greater.

DEFAULT: 1.0

swirec_load_adjusted_speedvsaccuracy

Overrides the automatic detection of CPU load, and forces specific values for parameters that balance speed and accuracy.

on, off, idle, normal, busy

DEFAULT: on

swirec_max_arcs

Specifies the maximum number of active FSM arcs.

Integer: 1–INT_MAX arcs. As many as three values are allowed.

DEFAULT: 10000, 5000, 3000

swirec_phoneme_lookahead_beam

Provides a secondary guide to the Viterbi beam search.

Float: -100–100. As many as three values are allowed. Typically set to the same value as swirec_silence_prune_offset.

DEFAULT: -30, -60, -60

swirec_secondpass_allophone_mapfile_name

Defines allophone maps for secondpass processing in Recognizer.

URI. One or more paths to acoustic model files.

DEFAULT: (default mapfiles used)

swirec_secondpass_global_fsm_name

Defines finite state machines for secondpass processing in Recognizer.

URI. One or more paths to acoustic model files.

DEFAULT: (default fsm files used)

swirec_secondpass_model_name

Specifies the acoustic models for secondpass processing in Recognizer.

URI. One or more paths to acoustic model files.

DEFAULT: (default models used)

swirec_retain_grammar_import_separator

Retains the semicolon as separator in the query string when importing a grammar.

Boolean

DEFAULT: 0

swirec_sensitive_query_keys

Suppresses logging of confidential values in grammar URI strings.

The name of a key in a grammar URI.

DEFAULT: (empty)

swirec_state_beam

Specifies the primary guide to control the number of paths considered. Primary guide for the Viterbi beam search.

Float: -100–100. As many as three values are allowed.

A typical range is between -60 and 0.

DEFAULT: 0, -15, -35

swirec_word_beam

For Nuance use only.

Threshold to control the number of paths considered. swirec_word_beam is analogous to swirec_state_beam, except that swirec_state_beam prunes paths that are within a word, whereas swirec_word_beam prunes only at word boundaries.

  

Set these Vocalizer parameters in the <speechsynth> section of <sessionparameters>:

Parameter

Description

Default

activeprompt_dbs

Specifies the ActivePrompt databases to load.

Path or URI to one or more ActivePrompt databases.

DEFAULT: (none)

audio_fetch_hint

Specifies the MRCP hint for how to access audio URIs.
  • prefetch: audio URIs can be downloaded when the request is received.
  • safe: audio URIs must not be downloaded until referenced.
  • stream: audio URIs can be streamed.

DEFAULT: prefetch

dictionaries

Loads user dictionaries for tuning speech output.

File path or URI to the dictionary. For multiple user dictionaries, specify multiple elements where each value specifies the URI for a single user dictionary.

DEFAULT: (none)

escape_sequence

Defines an alternative ESC character (ASCII 0x1B) for Vocalizer control sequences within the input text. (ESC continues to work even when this is set.) Alternative escape sequence for native markup.

A Perl 5 compatible regular expression. Special characters must be escaped with the backslash "\" character in the file, but not when used in VoiceXML.

DEFAULT: \\!

fetch_hint

Specifies when the Vocalizer may retrieve content from the server.
  • prefetch: may fetch all items that will be requested in a VoiceXML document when that document is opened.
  • safe: fetch an item only when requested.

DEFAULT: prefetch

language

Specifies the language for synthesis. IETF language code or Vocalizer language name for a language.

An IETF language code (for example, "en-US") or a Vocalizer language name (for example, "American English").

DEFAULT: (none)

language_identifier_languages

Permissible languages for automatic language identification in precedence order.

One or more ISO language codes. The default is all installed languages that support automatic language identifiication.

You can either 3-letter or hyphenated codes (usually 4-letters). For example, enu or en-US for American English. For a list of codes, see For more, see Vocalizer languages and voices. To see the 3-letter language codes for the currently installed voices, run " nvscmdline-V".

language_identifier_mode

Mode for automatic language identifiication during the session.

  • forced-choice: always switch to the language with the highest confidence.
  • rejection: don't switch languages if there is low confidence for the detected language.
  • memory-bias (default): adds weight to using the language of the previous sentence

language_identifier_scope

Enables automatic language identification and sets its scope.
  • user-defined (default): automatically identify the language when the application explicitly labels a block of text as unknown.
  • message: automatically identify the language on each input message (typically a sentence).
  • none: disable the feature

marker_mode

Specifies the types of markers, such as bookmarks, to deliver.

A bitmask of zero or more of the following:

  • TTS_MRK_SENTENCE (0x0001) for sentence markers
  • TTS_MRK_WORD (0x0002) for word markers
  • TTS_MRK_PHONEME (0x0004) for phoneme markers
  • TTS_MRK_BOOK (0x0008) for bookmarks, the only marker type supported in MRCP environments
  • TTS_MRK_PARAGRAPH (0x0200) for paragraph markers

DEFAULT: TTS_MRK_BOOK

rate

Specifies the speaking rate, where lower values are slower speaking rates.

Integer: 1–100.

Lower values request slower speaking rates.

DEFAULT: 50

rulesets

Specifies the rulesets to load.

One or more file paths or URIs to the ruleset.

DEFAULT: (none)

ssml_validation

Sets the mode to evaluate SSML markup in input text.

  • strict (default) validates the input against the SSML 1.0 Recommendation with Nuance extensions. If validation fails, Vocalizer logs error messages and aborts the synthesis operation with an error.
  • warn validates the input and logs errors, but does not abort the synthesis operation.
  • none skips validation.

DEFAULT: strict

voice

Specifies the Voice name for synthesis.

String. The name of any installed Vocalizer voice. For example, Samantha. Not case-sensitive.

Note: Specify the complete voice name (including any suffix).

DEFAULT: (none)

voice_age

Specifies the Voice model name, which indicates the type of TTS technology used for synthesis.
  • Adult: 18 years or older.
  • Child: Under 18 years.

DEFAULT: Adult

volume

Specifies the speaking volume based on the Vocalizer volume scale.

Integer: 0–100.

DEFAULT:

80 for Speech Server and Vocalizer

The <resourcehints> section of a session.xml file allows you to specify resources that are to be preloaded for the application. This is useful when your application uses resources that are so large that they could cause user perceived latency if loaded during a session itself. For example, <resourcehints> can be used to load Japanese models at the start in case the language switches during the call.

If your application does not use any large resources, it is recommended that you avoid including any <resourcehints> entries, as there is little advantage for minor resources.

At present, only Recognizer resources can be loaded in the <resourcehints> section of a session.xml file.

These parameters appear in the <speechrecog> section of <resourcehints>:

Parameter

Description

Default

swirec_model_name

Points to custom models for firstpass processing in Recognizer.

URI. Path to an acoustic model file.

DEFAULT: (default models are used for each language)

grammar

Preload Recognizer speech grammar when the session starts.

A grammar to be loaded. (When you load a language, that language’s built-in grammars are loaded automatically. There is therefore no need to load them in separate <resourcehints> entries.)

Filepath or URI.

DEFAULT: (none)

language

Specifies the language for synthesis. IETF language code or Vocalizer language name for a language.

An IETF language code (for example, "en-US") or a Vocalizer language name (for example, "American English").

DEFAULT: (none)

swirec_secondpass_allophone_mapfile_name

Defines allophone maps for secondpass processing in Recognizer.

In order to use this resource, a swirec_model_name must also be specified for the first pass.

URI. One or more paths to acoustic model files.

DEFAULT: (default mapfiles used)

swirec_secondpass_global_fsm_name

Defines finite state machines for secondpass processing in Recognizer.

In order to use this resource, a swirec_model_name must also be specified for the first pass.

URI. One or more paths to acoustic model files.

DEFAULT: (default fsm files used)

swirec_secondpass_model_name

Specifies the acoustic models for secondpass processing in Recognizer.

In order to use this resource, a swirec_model_name must also be specified for the first pass.

URI. One or more paths to acoustic model files.

DEFAULT: (default models used)

Note: The swirec_secondpass_* parameters must be used with a specific first pass model, as shown in the Sample session.xml file. The second pass resources are intended for advanced users only. Before you use them, it is recommended that you get advice from Nuance Network.