Reco Input

This Reco tool sends a request to the input recognition subsystem to accept user input either by speech or DTMF. The recognition will be performed using the grammars specified by their GrammarIDs. The list may include voice and or DTMF grammars and the recognition will use the corresponding input methods. Thus, if no DTMF grammar is specified, only voice input is possible and vice-versa. All grammars whose IDs are specified in the Grammars argument must have been registered previously through the Reco Register Grammar, Reco Register Grammar String, or Reco Register Inline Grammar tools.

In addition to GrammarIDs of explicitly registered grammars, grammars can also be referenced through "inline" references. Inline references have the following format:

$< GrammarURI > [~< GrammarType >][^<GrammarID>]

Thus, a URI grammar maybe referenced without having to previously register it. This is probably most useful for built-in grammars.

Note 1: It is not necessary to call Reco Initialize before invoking this tool, as an ASR engine will automatically be chosen if none is already active (see Reco Initialize for details on how an engine is chosen if no other parameters are specified).

Note 2: If Input Modes other than the default are specified and one of the input modes is not supported by the current session, it is simply ignored. Thus, if Input Modes is "3" (Voice & DTMF), yet the session does not support ASR, only DTMF input is solicited. If none of the grammar IDs represents a DTMF grammar, the tool would fails with a Grammar Error. If the Input Modes parameter is "2" (Voice) and only DTMF is supported, the tool fails with a Failure error and the Error Code output parameter contains "error.com.inin.mode". It is thus recommended to use the default for Input Modes, unless it is used for a fallback to DTMF or to explicitly request a certain input mode.

Inputs

Interaction

Identifier of the interaction.

Input Modes

Optional. Space separated list of input modes to use for this request. Default: Input modes specified when the session was created.

Grammars

Space separated list of Grammar IDs of the grammars that are to be used to use to accept speech and DTMF input during this recognition step. In addition to GrammarIDs of previously registered grammars, explicit references may be specified too.

DTMF Termination Keys

DTMF termination key(s). Default: "#"

DTMF Escape Keys

DTMF escape key(s). Default: ""

Confidence Level

Minimum confidence the highest scoring hypothesis of the recognition result must have for a successful recognition. If no hypothesis above this threshold, the tool returns through the Nomatch exit. This parameter corresponds to the "confidencelevel" property of VoiceXML.
Range: 0.0 … 1.0. Default: 0.5.

Top N Answers

Maximum number of distinct answers to include in the recognition result. Default: 2.

NOTE: This does not mean that there will be at most N hypotheses in the recognition result. Each answer may have multiple hypotheses with the same (or very similar) confidence. For example: Assume a dial-by-name grammar where the first names are optional (e.g. "[Adam] Smith | [John] Smith | [John] Smythe"). If the caller says "Smith," there are two possible hypotheses with the same confidence (the same confidence level), one for "Adam Smith" and one for "John Smith." Thus, these two hypotheses would count as one answer. The ASR engine may also provide a second answer with a lower confidence for "John Smythe." Increasing the value of the Top N Answers parameter will cause the engine to search for more answers and will thus increase the computation required by the ASR engine.

Timeout

Value

Maximum time to wait (in seconds) for speech or DTMF input (i.e. if no key is pressed or speech is detected within this time, the recognition aborts). Default: 5s

Mode

Specifies the semantics of the Timeout value.

Relative (0): Default. Timer starts when the plays complete (silence timeout).

Absolute (1): Timer starts immediately, irrespective of how long the plays play.

FinalPlay (2): The timer starts when the last of the queued plays starts to play. Starts immediately no plays are playing.

Interdigit Timeout

Maximum inter-digit delay for DTMF (in seconds). Default: 2.5s

Termination Timeout

Termination timeout (in seconds) for DTMF input when DTMF grammar must terminate. Default: 0s

Incomplete Timeout

Maximum time to wait (in seconds) after caller stops talking and grammar is not yet in an accepting state before timing out and returning through No Match. Default: 1.5s.

Complete Timeout

Maximum time to wait (in seconds) after a valid speech input has been provided before the input is accepted after the caller stops talking. Default: 0.5s

Max Speech Timeout

Maximum allowed duration of user speech before aborting. This prevents excessive background noise from blocking the tool indefinitely. Default: 20s

Tone Detector

Tone Detector 1 Frequency

First tone detection frequency in Hz. Set to 0 to disable tone detection. Default: 1100

Tone 1 Max Deviation

Maximum frequency deviation of tone 1 in Hz. Default: 50

Tone Detector 2 Frequency

Second tone detection frequency in Hz. Set to 0 to disable tone detection. Default: 0

Tone 2 Max Deviation

Maximum frequency deviation of tone 2 in Hz. Default: 50

ON Duration(s)

Time (in seconds) during which tone must be on. Default: 0.2

ON Deviation(s)

Maximum deviation of tone duration. Default: -0.2

OFF Duration(s)

Time (in seconds) during which tone must be off. Default: 0.0

OFF Deviation

Maximum deviation of tone off duration.
Default: -0.0

Interval Count

Number of tone on/off intervals required for match. Default: 0

Properties

Inline recognition properties. Properties specified here are active for the duration of the recognition. These properties can be used for advanced control of the recognition or to enable engine specific custom extensions.

Outputs

XML Document

<result> element node of the recognition result data.

If an error occurred, an empty <result> node will be returned with error information attached. Use XML Get Error to obtain extended error information.

Hypothesis Count

Number of recognition hypotheses in the recognition result.

Code (event)

This output parameter contains the error code if the tool failed in the form of a VoiceXML style event.

Text (message)

Text accompanying the error code.

Exit: 

Success

A valid input matching one or more of the specified grammars was recognized. May be DTMF or voice.

Escape

The DTMF "Escape" key was pressed.

Tone

A tone matching the specified rules was detected during the recognition.

No Input

No input was recognized during the specified timeout time. This corresponds to the "noinput" VoiceXML event.

No Match

Input was provided, but it did not match any of the active grammars. This corresponds to the "nomatch" VoiceXML event. Even if the tool returns through this exit, there may still be a recognition result.

Max Speech 

The "Max speech timeout" was exceeded during speech input. This probably means that the background noise is too high and the handler should probably fall back to DTMF-only input. This exit corresponds to the "maxspeechtimeout" VoiceXML event.

Failure 

Some other error occurred. Use XML Get Error on the returned recognition result node to obtain additional information.