This topic includes details
of the parameters required to synthesize and play a text string and
return codes.
Purpose
Use this call to synthesize and
play a text string.
Parameters
Input
- session_id (Number)
- The session identifier allocated on the successful call to MRCP_TTS_Assign.
- text_type (string)
- This indicates the format of the text to be played, the possible
values being:
- ascii-string
- The text is contained in the 'text' input parameter
and will automatically be enclosed in MRCP <speak> tags by Blueworx Voice Response.
- ascii-file
- The text is contained in a file, the name (path)
of which is specified in the 'text' input parameter. A file can only
be loaded from a local storage device, and not an HTTP server.
- xml-string
- The string in 'text' is assumed to be formatted 'speak' XML which
is sent to the TTS engine without any retagging
- xml-file
- The string in 'text' is assumed to be the name (path) of a file
containing pre-formatted 'speak' XML
- text (String)
- See the description of 'text_type' above.
Note that the text
string has a limit of 2000 characters. To play longer text strings,
your application needs to break them up into smaller chunks or use
one of the file modes of operation.
- parameters (Tagged String)
- The MRCP configuration to be used for this speak action only.
These header fields will augment and update any session values set
using MRCP_TTS_CONFIG or the configuration in file $CUR_DIR/ca/MST_dir/mst.xml for
this action only. To build the string, use the PutTag operator of
the AssignData state table action. See 4.i for details of how
to use PutTag. The header fields that can be specified in this field
are defined in the MRCP specification and are passed unchanged to
the MRCP TTS server on the MRCP SPEAK call. Examples are as follows:
- Speech-Language en-us
- Voice-gender female
- Prosody-volume 25
- stop_keys (String)
- This attribute controls how the playing of synthesized text can
be interrupted by the pressing of DTMF keys. The possible values are:
- NONE
- This is the default value and indicates that the playing cannot
be interrupted. It is equivalent to FORCE_PLAY for the PlayVoiceFromHost
action.
- ALL
- Any DTMF key can interrupt the play. It is equivalent to STOP_PLAY_ON_DTMF
for the PlayVoiceFromHost action.
Output
- return_code (Number)
- Contains the result of the action. See below for details.
- stop_reason (String)
- If the return_code is 0, this indicates what if anything
caused the TTS play to stop. If it completed without interruption
then this string is empty, otherwise it is one of the following:
- DTMF:
- DTMF was detected.
- HUP:
- Caller has hung up.
Return codes
- 0 - Succeeded
- The TTS synthesized and played all or some of the prompt without
any problems. Check the stop_reason to see what if anything caused
the prompt to be stopped prematurely.
- 7 - Protocol error
- The text-to-speech server
has reported a protocol error. More details about the exact error
will be logged to the Blueworx Voice Response error log.
- 8 - Invalid session
- The session ID specified was not valid.
- 9 - Parameter error
- A parameter is in error (for example, a text string exceeds 2000
characters in length). More details about the exact error will be
logged to the Blueworx Voice Response error log.
- 10 - Failed
- An unexpected problem occurred.
- 4nn
- Protocol error returned by the MRCP server if a parameter passed in the correct format, but the
MRCP V1.0server cannot process it, for example, when an unsupported language is specified. For
details of these codes and their meaning, refer to the MRCP V1.0 specification available
at:
http://tools.ietf.org/html/draft-shanmugham-mrcp-04