PlayVoiceSegment

Purpose

Use PlayVoiceSegment to play the digitized voice data that speaks a voice segment.

A screen capture of the Action PlayVoiceSegment window

Description

PlayVoiceSegment can play back a voice segment either from disk, or from the temporary workspace in which the system holds it until it is saved.

Do not use PlayVoiceSegment for normal voice segments played from within an application; use PlayPrompt instead. Voice segments played with PlayVoiceSegment are retrieved from the database each time they are played. Voice segments played with PlayPrompt are cached within Blueworx Voice Response, which significantly increases performance. Do not save data at the same time it is being played. If you do so, the Play action will fail.

For the PlayVoiceSegment action to succeed, the voice channel must already be connectedthis is achieved through the successful completion of either an AnswerCall or a Makecall action. For an incoming call, the voice channel can also be connected prior to an AnswerCall action, if the system parameter Connect Voice Channel Before Answer is enabled (this parameter is only available if you are logged on as field).

If you use uncompressed voice segments with the PlayVoiceSegment action, this produces more network traffic when your Blueworx Voice Response system is part of a single system image.

The compression type of the voice segment must match the type in the system variable System: Voice Segment Compression Type (SV50). If a segment of that compression type does not exist, PlayVoiceSegment returns Voice Record Not Found.

While a voice segment is playing, the caller can press keys to fast-forward, pause, reverse, or stop. System parameters in the Application Server Interface parameter group set these keys as follows:

Activity	Default Key	System Parameter
Fast forward	9	Forward Key
Pause	8	Pause Key
Reverse	7	Reverse Key
Stop	*	Stop Key

In addition, system parameter SV183 can be used to specify other DTMF keys that can stop the action. See System: Play/Record: Alternate stop keys (RW) (SV183) for more information.

To resume after a pause, the caller must press the pause key again. If the caller does not resume after pressing the pause key (by pressing the pause key again), playing continues when the pause times out. The pause time out is configurable using the Play/Record Voice Maximum Pause (seconds) system parameter in the Blueworx Voice Response parameter group. The default value is 10 seconds.

When interrupt by voice detection is active, the caller can interrupt PlayVoiceSegment by speaking.

If a fax tone is detected, the action is terminated.

All user input and other events are flushed both before this action starts, and when it completes. As a result, any queued DTMF, voice interrupt detection, or fax tones are lost.

PlayVoiceSegment can be used with background music to produce a voice-over effect. If you don't want background music playing at the same time as the segment, precede this action with a ControlMusic action and set the fade time to 100.

You can only play a voice segment from Voice in Workspace if you created it with RecordVoiceSegment in your current session and have not saved it. The temporary workspace is cleared when you end the session.

Parameters

The parameters for PlayVoiceSegment identify the voice segment to play and where it is located. This action plays a voice segment either from workspace (Voice in Workspace) or from disk (Voice on Disk). If the voice data is in workspace, there are no parameters. If the segment is stored on disk, the parameters are:

Voice Dir Name (default) or Voice Dir ID. Identifies the voice directory to which the segment belongs. You can select a voice directory by name or by the ID assigned to it when it is created.
Note: We recommend that you use voice directory names, and not IDs, because voice directory IDs are not cross-referenced, so they are not included when doing an import or export. Also, if an imported voice directory has the same ID as a current directory, the ID of the imported directory is changed (after querying the user), and you will need to modify state tables to use the right voice directory.
Segment ID. Identifies the segment to be played.
Language. Identifies the language in which the segment was recorded.

Possible results

PlayVoiceSegment can have one of the following results:

Succeeded

The voice segment was found and successfully played to the caller, either partly or in full (a truncated voice segment that contains at least 128 bytes of the original data is still playedif more than 200 milliseconds of voice is lost a warning message is raised).

The system variable System: Action additional information (SV180) is set to one of the following values:

0: The action completed without interruption.
1: The caller pressed a DTMF key; play was interrupted.
2: Voice was detected; play was interrupted. Use WaitEvent to flush the voice event from the queue (see WaitEvent). Detection of voice interrupt is enabled by setting SV217 to 1 (see System: Voice interrupt detection: On/Off (RW) (SV217) ).
3: Fax tone was detected; play was interrupted. Detection of fax tone is enabled by setting SV227for possible values see System: Fax detection (SV227).
4: A custom server event occurred; play was interrupted. To retrieve the event, use the WaitEvent state table action (see WaitEvent). Detection of a custom server event is enabled by setting SV546 to 1 (see System: Host Interrupt Detection: On/Off (RW) (SV546) ).

Note: If you want to use the information in SV180, you must check it immediately after a state table action because it is reset by other actions.

Voice Channel Problem

The voice segment was not played, because there was a problem with the voice channel on which it was supposed to be played.

Voice Record Not Found

The voice segment does not exist, or has been truncated to less than 128 bytes of data..

Caller Hung Up

The caller has hung up.

ASCII syntax

When using an ASCII editor, code this action with these parameters in the following order:

"IN_WORKSPACE"

Or:

"ON_DISK"
"VDIR_ID"
Voice directory ID
Segment ID
Language

Or:

"ON_DISK"
"VDIR_NAME"
Voice directory name
Segment ID
Language

For example:

label: "Check Edges"
        PlayVoiceSegment("IN_WORKSPACE")
          edge EDGE_PLAYVCE_COMPLETED:   completed
          edge EDGE_PLAYVCE_LINE_PROBLEM:       line_problem
          edge EDGE_PLAYVCE_NOT_FOUND:  not_found
          edge EDGE_HUP:                                  hup
        ;
        PlayVoiceSegment("ON_DISK", "VDIR_NAME", System, loc1_n, SV142);
                   # SV142...App Profile Language

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.