PlayVoiceFromHost

Purpose

Use PlayVoiceFromHost to enable voice data to be sent to a voice channel by a custom server, so that it can be played down the telephone line.

A screen capture of the Action PlayVoiceFromHost window

Description

The voice data could, for example, have been retrieved from another Blueworx Voice Response or generated by a speech synthesis application. The action is similar to the SendData action, with additional parameters and result states.

When the channel process begins to execute this action, it controls the initial parameter transfer to the custom server, just as with the SendData action. But in addition, a request is sent to the device driver to begin remote playing. The latter returns a handle to the channel process. The handle is attached to the data packet that the channel process sends to the custom server. As with the SendData action, the time on the data packet is set from the Host Response Time Limit parameter on the action.

For the PlayVoiceFromHost 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 required, you can use ReceiveData to receive a response from the custom server after a PlayVoiceFromHost action. But if the user hangs up before the PlayVoiceFromHost, or if no voice data was played, the ReceiveData returns the Host Not Open result because the internally-generated SendData action has not been issued.

The action terminates when one of the following events occurs:

The custom server closes the voice channel and the all voice data has been played.
The caller stops the playing by pressing a DTMF key or speaking (to enable Voice detection, set SV217 to 1). For DTMF, you can specify that the caller can stop the playing by pressing:
- Any DTMF Key (as with the PlayPrompt action when ForcePlay is not set), or by speaking when voice interrupt detection is active. To define specific DTMF keys that can be used to stop the action, use SV183 (see System: Play/Record: Alternate stop keys (RW) (SV183) for more information).
- Only the Pause Key and Stop Key(s) (as with the PlayVoiceSegment action), or by speaking when voice interrupt detection is active. Only the pause and stop keys are recognized; any other DTMF key is ignored and cut from the voice being played. 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. The forward and reverse keys are notsupported for this action.
(You can specify the ForcePlay option (as on the PlayPrompt action), to prevent the caller from interrupting the play action. All the voice data is transmitted down the line, until the custom server signals that there is no more data to play.)
The custom server did not pass voice data quickly enough, and the voice channel remains idle for longer than the time specified by the Idle Time parameter.
The caller hangs up.
A fax tone is detected and ForcePlay is not set.

PlayVoiceFromHost 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 voice data, precede this action with a ControlMusic action and set the fade time to 100.

Unless you set Interrupt with Any DTMF key, all input is flushed both before this action starts, and when it completes. As a result, any queued DTMF, voice interrupt detection or fax tones are lost.

Parameters

Server Name. Identifies the custom server that receives the input parameters.
Server Command. Identifies the custom server user function that contains the CA_Play_Voice_Elements() or CA_Play_Voice_Stream() subroutine.
Parameters. Specifies the variable to which each item of information is assigned.
Force Play. Specifies that the caller cannot stop the play action by pressing a DTMF key.
Interrupt with any DTMF key. Specifies that the caller can stop the play action by pressing any DTMF key or by speaking if voice interrupt detection is active. Set this parameter to preserve any queued DTMF, voice interrupt detection, or fax tones that would otherwise be flushed when the PlayVoiceFromHost action starts.
Pause Key and Stop Key(s). Specifies that the caller can stop the play action by pressing either the pause or the stop key or by speaking if voice interrupt detection is active.
Idle Time. The maximum period for which the voice channel may be idle without voice data to play. This ensures that the custom server is sending data.
Host Response Time Limit. Specifies the maximum number of seconds allowed for a response from the custom server. (This is the response that will be picked up by a subsequent ReceiveData action.)

Possible results

Stopped by Host

The custom server stopped the action. This may occur, for example, because the custom server has completed: all the voice data has been played. At the state table level, this implies the action completed successfully. Specific detail of the reasons for termination should be trapped and reported within the custom server.

Stopped by DTMF

The caller pressed a DTMF key or spoke.

The system variable System: Action additional information(SV180) will be set with one of the following values:

0: The action completed without interruption.
1: The caller pressed a DTMF key; play was interrupted. The key pressed is written to the System: Play/Record: Actual stop key system variable (SV184).
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.

Host Problem

This may occur for a number of reasons. The cause is reported in the System: Action additional information system variable (SV180). Possible values are:

1: Too much parameter data sent to the custom server
2: The custom server did not close the channel soon enough after playing was stopped. To avoid this, increase the value of the Remote Play/Record CA Time Out system parameter.
3: The custom server did not provide voice data soon enough at the start of the action or after a restart (which may occur because of an underrun condition). To avoid this, either increase the value of the Idle Time parameter or decrease the value of the Remote Play/Record Min Data system parameter.

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.

Host Not Open

The requested custom server has not been activated (using the OpenHostServerLink action) so voice playing could not start.

Voice Channel Problem

A problem occurred on the voice channel, so voice playing could not continue.

Caller Hung Up

The caller hung up, so voice playing stopped.

ASCII syntax

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

Server Name
Host Response Time Limit
"FORCE_PLAY"
- or "STOP_PLAY_ON_DTMF"
- or "PAUSE_AND_STOP_KEYS"
Idle Time
Server Command
... Parameters

For example:

"Check Edges"
        PlayVoiceFromHost(CS_Request_Call, 10, "FORCE_PLAY", IO
                 read_rec, in1_n)
                   edge EDGE_PVFH_STOPPED_BY_HOST:       stopped_by_host
                   edge EDGE_PVFH_STOPPED_BY_DTMF:       stopped_by_dtmf
                   edge EDGE_PVFH_HOST_PROBLEM:   host_problem
                   edge EDGE_PVFH_HOST_NOT_OPEN:         host_not_open
                   edge EDGE_PVFH_LINE_PROBLEM:   line_problem
                   edge EDGE_HUP:                                       hup
        ;
        PlayVoiceFromHost(CS_Request_Call, 10, "STOP_PLAY_ON_DTMF", IO
                 read_rec, in1_n);
        PlayVoiceFromHost(CS_Request_Call, 10, "PAUSE_AND_STOP_KEYS", IO
                 read_rec, in1_n);

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