Overview

This control provides supervisory recording or tap recording of a voice channel. It can record all or part of a call-flow. The TapRecord control features full duplex recording which means that the sum of both the interface and voice on any given voice channel is recorded.

The TapRecord control has two modes. The first occurs on an ordinary call, where the TapRecord records the interaction between a human (caller) and a machine (IVR). The second mode occurs if the call is bridged when the TapRecord control is executed. In this second mode, the interaction between two humans, the two callers who are bridged, is recorded.

Dialogic Hardware

With Dialogic ( [voicecard] type=Dialogic), the TapRecord control works in conjunction with the ResourceGroup control. To record a call, specify a free voice resource channel on which the recording will be done. On first entering the TapRecord control, a voice resource is allocated to the current channel using an available voice resource from a specified resource group. If no voice resource is available, the call will exit from the TapRecord Error node or return an error.

With DM3 cards, ( [voicecard] type=Intel or type=IntelHMP), the TapRecord control works in conjunction with the ResourcePool control. To record a call, specify a free voice resource channel on which the recording will be done. On first entering the TapRecord control, a voice resource is allocated to the current channel using an available voice resource from a specified resource pool. If no voice resource is available, the call will exit from the TapRecord Error node or return an error. For these types of cards the resource pool could be left blank (i.e. no resource pool specified in the property page); in this case the control tries to get a voice resource from the global pool.

Once a voice resource is allocated to the channel, tap recording begins. The recording is stopped by entering the second entry node, by calling a StopRecord, or by some other termination condition (user hang-up, system stop). It can be placed in any position in a call flow.

Please note that the TapRecord control is only supported on voice cards with an SC bus (D/4PCI is not supported). The TapRecord control will not work in test mode.

Record Filename

The filename used for each message can be a unique name created by the TapRecord control using the IFileName property and can also contain values from previous results in other controls. A wild char * can be used to indicate that a unique file name should be created. The TapRecord control does this by replacing the * with eight random characters when a call arrives at the control. For example, msg*.wav may be translated into msg12345678.wav. If a * is not specified, the same file is overwritten on every tap recording operation. If the AppendFile option is specified, the file is appended rather than overwritten.

To create a filename that is dependent on the channel, use the %#channel% variable. (See Special Control Names). This is replaced by the current channel number when the recording starts.

If a full path for the file is not specified, the VoiceDirectory is used, even if a language has been set by a language control. However you can override this by adding the VBVFrame.CurrentDirectory property into the file string, e.g. %VBVFrame.CurrentDirectory%msg*.wav. This records the file into the directory specified by the language control.

Terminating a Record

The recording is terminated by one of the following:

1. re-entering the TapRecord control second entry node

2. calling the StopRecord(channel) method, detecting silence using the MaxSil time property

3. detecting a hang-up

4. using a System Stop

The resource channel is then released.

Message Data

The TapRecord control can associate a data string with each message recorded. It does this by filling in the INFO section of the Wave file. The info section has a maximum size of 256 bytes. The default data string is set using the property page item File Data (FileData property). This data can be changed in the Enter event using the MsgData property.

File Handling

When recording a new file, the TapRecord control always records the file into a temporary file in the target directory as specified in the control setup. When the recording is saved, the temporary file is renamed to the required file name. If the record is not successful, the temporary file is deleted and the destination file is not created. If the record is using Append mode, the file is appended in-place.

Valid Recordings

A recording is considered valid if it is longer than IMinTime. Recordings shorter than this value are discarded.

Error Handling

When first entering the TapRecord control, if no voice resource is available, the call will exit from the TapRecord control Error node or return an error if using the StartRecord method. On forced shut-down and StopSystem, the recording, if valid, is saved. If the record is not successful, destination file is not created. If the record is using Append mode, the file is appended in-place. The resource channel is then released.

Special Disconnect Handling

If a disconnect occurs during a TapRecording, the recording, if valid, is saved. If the record is not successful, the destination file is not created. If the record is using Append mode, the file is appended in-place. The resource channel is then released.

TapRecord Control Example

Use of this control is shown in the example TapRecord and TapRecord_Bridge.

Initial Setup Properties

AppendFile

Boolean

If set to True, the recording is appended to the file, if it already exists. If it does not exist, a new file is created. If the recording is cancelled, the file is truncated to its original length.

CompressSilence

Boolean

(Not supported) Eliminates periods of silence during the recording, so that only the speech is recorded.

FileData

(String)

This property contains the default data for the Message Data associated with the record file. This data can contain control name references and can be changed at runtime using the MsgData property.

See Message Data.

IFileName

(String)

The default filename for the recorded file. See Record Filename.

IMaxSil

Integer

The maximum duration of silence in seconds before recording is terminated. See also MaxSil.

IMaxTime

Integer

The longest duration in seconds for a recording before recording is terminated. See MaxTime.

IMinTime

Integer

The minimum duration in seconds of a recording before it is accepted as a valid recording.

RecordFormat

Integer

One of the vbvFileFormatConstants. Remember that when playing back the recorded file, all phrases in a greeting must use the same format.

ResourceGroupName

(String)

Returns the resource group name being used in the GetResource control.

Runtime Properties

AppendFileMode

(Boolean)

This property overrides the append mode set by the AppendFile property on a per-call basis. It allows for an additional option: to prepend the new message data to the file, as well as overwriting or appending the new data. This property uses the vbvAppendModeConstants:

1. vbvFileOverWrite = 0

2. vbvFileAppend = 1

3. vbvFilePrepend = 2

Filename

(Channel as Integer) String

The filename created is available from the Filename property. Your VB code can override the filename by setting the property in the Enter event. Changing the filename at any other time has no effect. The filename can also be used as part of a greeting in order to replay the message. If the message is cancelled or not recorded, the filename property is empty.

EXAMPLES

To access the filename:

mystring = TapRecord1.Filename(channel)

To override the filename:

TapRecord1.Filename(channel) = myfile.tmp

FileSize

(Channel as Integer) Long

This property contains the size (in bytes) of the file recorded by the TapRecord control. If no file has been recorded, the value is 0.

GotoNode

(Integer)

This property will transfer a call to another control. See GotoNode.

MaxSil

(Channel as Integer) Integer

This is the duration (in seconds) of silence before VBVoice decides that the caller has stopped talking. This property is set by the control to the value Maximum Silence in the Setup property page. It can be changed in the Enter event to another value if required. The new value only affects the current call until it leaves this control.

MaxTime

(Channel as Integer) Integer

This is the maximum duration (in seconds) allowed for the recorded message. This property is set by the control to the value Max time for Record in the setup property page. It can be changed in the Enter event to another value if required. The new value only affects the current call until it leaves this control. The maximum time that can be set is 32767 seconds. To record files longer than this, either disable the maximum time by using a value of 0, or move to another record control with the AppendMode set to True to append more data to the same message.

EXAMPLE

To override the maximum time setting:

If CallerName = Fred Then

TapRecord1.MaxTime(channel) = 50 'stops after 50 seconds

Endif

MsgData

(String)

See Message Data.

Methods

StartRecord

Starts a TapRecord recording on the specified channel. The Channel parameter is the channel to tap. An additional voice resource must be available and will be grabbed from a specified resource group. If no voice resource is available, the method will fail. StartRecord returns 1 for success and 0 for failure.

Please note that the TapRecord has two modes for tap recording. The first will record the interaction between a human (caller) and a machine (IVR). The second mode, if the Channel is bridged, will record the interaction between two humans (the two callers that are bridged). To use the second mode, you must bridge the channels before calling the StartRecord method or else the first mode (human to machine) will be used.

Before using this method, the FileName [channel] property must be set to the desired filename.

StopRecord

Stops a TapRecord session and releases the resource channel. The Channel parameter is the channel to stop tapping on. When the recording is saved, the temporary file is renamed to the required file name. If the record is not successful, the temporary file is deleted and the destination file is not created. If the record is using Append mode, the file is appended in-place. StopRecord returns 1 for success and 0 for failure.

TakeCall

This method allows the programmer to override the graphical connections and transfer a call to any other control. See TakeCall.

Events

Enter

See Enter Event.

Exit

See Exit Event.

VoiceError

See VoiceError Event.

Setup Property Page

The TapRecord control allocates a voice resource for the current channel using an available voice resource from a specified resource group.

Record Setup Page

Dont record silence

(CompressSil property)

(Not supported) The voice card removes all silence periods greater than a predefined size. This is set to a default size of 200ms.

Append to file

(AppendFile property)

If set to True, the recording is appended to the file, if it already exists. If it does not exist, a new file is created.

File Data

(MsgData property)

Default message data to be associated with this file. This data is stored in the wave file in an INFO chunk and can be used in the PlayMsgs control to associate a message with a particular caller, or any other information you wish to store with the message. For instance, in a system with caller-id available, you could add %LineGroup1.CallerID% to this field. In a PlayMsgs control, add to the InfoGreeting a system phrase SayDigits %#this.MsgData% to vocalize the data to the caller.

Filename

(IFileName property)

Enter a file specification here. The Record control creates a file based on this specification to record the message. See Record Filename.

Maximum time for record

(IMaxTime property)

Sets the maximum time for a recording, in seconds.

Max silence

(IMaxSil property)

Sets the maximum period of silence before terminating a record operation.

Minimum Time for Valid Recording

(IMinTime property)

A recording shorter than this time is regarded as invalid. The file is deleted and treated as a silence timeout.