RecordVoiceToHost

Purpose

Use RecordVoiceToHost to enable voice data to be retrieved from a voice channel and passed to a custom server, to make the voice data available for speech recognition through a speech recognition application.

Description

This action is similar to the SendData action, with additional result states.

When the channel process begins to execute this action, it controls the initial parameter transfer to the custom server, just as for SendData. But in addition, a request is issued to the device driver to begin remote recording. The device driver 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.

If required, you can use ReceiveData to receive a response from the custom server after a RecordVoiceToHost. If, however, the user hangs up before the RecordVoiceToHost, the ReceiveData returns the Host Not Open result, because the internally-generated SendData action has been issued.

The action can terminate for any of the following reasons:

• The custom server closes the voice channel. Any remaining data in the buffers is discarded at this point.
• The caller stops the recording by pressing a DTMF key. You can specify that the caller can stop the recording by pressing Any DTMF key or Pause Key and Stop Key(s) (see Parameters for details):
• The custom server could not retrieve the voice data fast enough and the buffers overrun.
• The Maximum Record Time is reached.
• The caller hangs up.

RecordVoiceToHost causes an automatic fade out of any background music. You can override this by using the System: Music: Automatic fade before actions system variable (SV226).

If the recording of voice is interrupted by a DTMF user interrupt then all input is flushed as the action completes, and any queued DTMF, voice interrupt detection or fax tones are lost. If, however, the recording of voice is terminated by a timeout then all such input is retained.

Parameters

• Server Name. Identifies the custom server that receives the input parameters.
• Server Command. Identifies the custom server user function that contains the CA_Record_Voice_Stream() subroutine.
• Parameters. Specifies the variable to which each item of information requested by the custom server is assigned. The combined size of all the parameters must not exceed 3800 bytes.
• Interrupt with any DTMF key. Callers can use any DTMF key to indicate that they have finished (as with the GetKey action). This is suitable for discrete-word speech recognition applications. No pacing tone is played at the beginning, and no warning tone is played when maximum record time is reached.
• Pause Key and Stop Key(s). Callers can use only the pause and stop keys to indicate that they have finished (as with the RecordVoiceSegment action). Only the pause and stop keys are recognized; any other DTMF key is cut from the speech being recorded, but the application must still process this key. A pacing tone is played at the beginning and a warning tone is played when the maximum record time, set by the Record Voice Warning Time system parameter, is reached.

The stop key can be pressed to indicate that the user has finished speaking. The default stop key is the asterisk (*) on the telephone key pad, but can be reset to another key, using the Stop Key system parameter in the Application Server Interface parameters group. Alternatively, you can define more than one DTMF stop key by using SV183 (for more information see System: Play/Record: Alternate stop keys (RW) (SV183)).

The pause key can be pressed if the user needs to stop and then continue speaking. The default pause key is the number 8 on the telephone key pad, but can be reset to another key, using the Pause Key system parameter in the Application Server Interface parameters group. To start again after a pause, the user presses the pause key again.

If the caller does not press the pause key again to end a pause, recording starts again, provided the Maximum Record Time has not been reached and the custom server is still recording.

This mode of operation is primarily for recording voice messages to be sent to another Blueworx Voice Response system, or for continuous or dictation-mode speech recognition applications.

• Max Record Time. The total time allowed (in seconds) for recording.

  If you select Pause Key and Stop Key(s), a warning tone is played before the Max Record Time elapses. (The timing of the warning tone is specified by the Record Voice Warning Time system parameter, which specifies how long before the end of the Max Record Time the beep is to occur.)

• 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.) If this value is less than, or equal to, the Max Record Time, a warning message is logged, although the action proceeds with the values as set. If this value is 0, no response is expected from the custom server.

Possible results

Stopped by Host

The custom server stopped the action and no more voice data was required. This may occur, for example, because the custom server indicates the a speech recognition application has returned a result.

Stopped by DTMF

The caller pressed a DTMF key. Depending on parameter settings, this can be any DTMF or only the stop or pause keys. You must get and process the user interrupt. For example, the key pressed may represent the first digit of an account number that the caller is keying in, in which case, you should store it in a variable.

Timeout

Voice recording may stop for one of the following reasons, as identified by the value of the System: Action additional information system variable (SV180):

4

Too long a period of silence was detected.

5

The maximum record time was reached.

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 can occur for the following reasons, as identified by the value of the System: Action additional information system variable (SV180):

1

Too much parameter data sent to the custom server.

2

The custom server did not close the channel soon enough after recording was stopped. To avoid this, increase the value of the Remote Play / Record CA Time Out system parameter.

3

The custom server could not read the recorded data fast enough: the buffers were filled and so recording was stopped. To avoid this, increase the value of the Remote Play / Record Max 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 recording could not start.

Voice Channel Problem

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

Caller Hung Up

The caller hung up, so voice recording stopped.

ASCII syntax

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

1. Server Name
2. Host Response Time Limit
3. "STOP_RECORD_ON_DTMF" or "RECORD_COMPATIBLE" (these parameters correspond to Interrupt With Any DTMF Key and Pause Key and Stop Key(s), see Interrupt with any DTMF key..)
4. Maximum Record Time
5. Server Command
6. ... Parameters

For example:

label: "Check Edges"
        RecordVoiceToHost(CS_Request_Call, 20, "STOP_RECORD_ON_DTMF", 30,
                 read_rec, loc1_n)
          edge EDGE_RVTH_STOPPED_BY_DTMF:       stopped_by_dtmf
          edge EDGE_RVTH_STOPPED_BY_HOST:       stopped_by_host
          edge EDGE_RVTH_HOST_PROBLEM:   host_problem
          edge EDGE_RVTH_HOST_NOT_OPEN:         host_not_open
          edge EDGE_RVTH_LINE_PROBLEM:   line_problem
          edge EDGE_TIMEOUT:                       timeout
          edge EDGE_HUP:                                   hup
        ;
        RecordVoiceToHost(CS_Request_Call, 20, "RECORD_COMPATIBLE", in1_n,
                 read_rec, loc1_n);

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