2.1 Obtaining a Voice Handle

2.2 Defining Current Message and Current Position

2.3 Playing

2.3.1 Play Functions

2.3.2 Playing a Sequence of Messages

2.3.3 Play Completion Reasons

2.3.4 Adjusting Volume and Speed

2.3.5 Play Parameters

2.4 Recording

2.4.1 Record Functions

2.4.2 Record Completion Reasons

2.4.3 Resizing Messages

2.4.4 Record Parameters

2.5 Play and Record States

2.6 Stopping

2.6.1 Using DTMF to Terminate Play or Record

2.7 Retrieving Context Status

2.8 Retrieving Voice Object Information

2.9 Editing Voice Messages

2.9.1 Copying and Converting Messages

2.9.2 Erasing Messages

2.9.3 Reading and Writing Messages

2.10 Converting Text Strings to Message Lists

2.10.1 How the Prompt Builder Works

2.10.2 Prompt Rules Table

2.1 Obtaining a Voice Handle

Many functions take (or return) a voice handle. A voice handle identifies an open voice object, which is a file or a memory block. To use a voice object, you need a voice handle.

If you want to...	Then use this function...
Access an existing file for play or record	vceOpenFile
Create a new voice file of a specified type	vceCreateFile
Access a range of memory	vceOpenMemory vceCreateMemory
Access a file (or device) that is already opened	vceAssignHandle
Release a voice handle, close the associated file if the handle was obtained by vceOpenFile or vceCreateFile and free the memory allocated by vceCreateMemory.	vceClose

Use the handle in combination with a message number to identify a segment of speech in the object for playing, recording, or editing.

A voice handle is always associated with a context. When you specify a voice handle, the context is implied, as illustrated in Figure 1:

Figure 1. A Voice Handle Associated With a Context

Note: To access a voice object in multiple contexts (for example, to share a prompt file), open the voice object separately for each context.

2.2 Defining Current Message and Current Position

When you play a message or a list of messages, the message or message list becomes the current message for pausing and resuming, repositioning, etc. The current message is associated with the context handle. The current message has a current position.

Figure 2. Current Message/Current Position

Use the following functions to use and/or modify the current position:

• vceErase

• vcePlay

• vceRead

• vceRecord

• vceSetPosition

• vceWrite

Use the following functions to define the current message:

• vceConvertMessage

• vceCopyMessage

• vceEraseMessage

• vcePlayList

• vcePlayMessage

• vceRecordMessage

• vceSetCurrentList

• vceSetCurrentMessage

If a voice object containing a message in the current message (list) is closed, there is no longer a current message. Play or record is stopped, if it is active.

Note: The current message is not affected when a call hangs up.

2.3 Playing

The Voice Message service provides two types of playing functions:

• The message oriented functions, vcePlayMessage and vcePlayList, operate on a specific message or a list of messages. They take a voice handle and message number, or a list of message numbers. Playing starts from the beginning of the first message.

• The position-oriented function vcePlay operates on the current message in the specified context. Playing starts from the current position in the most recently accessed message or list.

Use the ADI service function adiPlayAsync or adiStartPlaying if you need direct access to buffers. Refer to the ADI Service Developer's Manual and to the ADI Service Function Reference Manual for more information on ADI functions.

The vceplay demonstration program demonstrates playing messages from one or more voice files. Refer to Section 5.4 for more information.

2.3.1 Play Functions

2.3.2 Playing a Sequence of Messages

A list is one or more messages. Use vcePlayList to play a sequence of messages with no delays between each message. This is the way to play a prompt string that has been converted to a sequence of message numbers by vceBuildPromptList. All messages in the list must have the same encoding. If the messages are in different files, use vceSetCurrentList followed by vcePlay.

2.3.3 Play Completion Reasons

The following table lists the Voice Message service reason codes returned when play terminates. The value field of the VCEEVN_PLAY_DONE_EVENT states the reason.

Note: If play fails, the value field contains an error code.

If...	The DONE event contains...
The end of the current message or list is reached	CTA_REASON_FINISHED
The time limit in vcePlay is reached	CTA_REASON_TIMEOUT
Play is stopped by calling vceStop	CTA_REASON_STOPPED
A touch tone digit is received and the corresponding bit in the DTMF abort parameter is set	CTA_REASON_DIGIT
The call is ended	CTA_REASON_RELEASED
You play an object that has an encoding that is not supported by the attached device service	CTAERR_FUNCTION_NOT_AVAIL

2.3.4 Adjusting Volume and Speed

You can set the volume (vceSetPlayGain) and speed (vceSetPlaySpeed) of play at any time. The new volume (gain or amplification) and the new speed are stored in the current context. If play is currently active, the change takes effect immediately. If you want a gain or speed change to carry over to the next play function, set the play gain or speed parameter on the next play to VCE_CURRENT_VALUE.

You can also adjust the playing speed for some encodings. Speed control is available for the NMS ADPCM encodings (VCE_ENCODE_NMS_xx) and the OKI ADPCM encodings (VCE_ENCODE_OKI_xx).

To enable speed up, increase the maxspeed play parameter from its default value of 100. When play is started with a higher value of maxspeed, the necessary DSP resources are allocated to support increased speed. You can start play with a fast speed (up to maxspeed) by changing the value of the speed parameter.

To use speed up with NMS ADPCM on AG Quad boards, replace voice.dsp in the configuration file with voxp.dsp and voxr.dsp.

Note: Starting play with maxspeed greater than 100 requires additional DSP resources beyond that required for playing at normal speed. To determine whether your AG board(s) and configuration can support speed up, refer to the NMS OAM System User's Manual, or the board-specific installation and developer's manual.

Use vceGetContextInfo to get the current gain and speed values.

2.3.5 Play Parameters

The play functions take an optional pointer to a parameter structure. If you pass NULL, the parameters take default values. Refer to VCE.PLAY in Appendix B for more information about the play parameters.

2.4 Recording

The Voice Message service provides two types of recording functions:

• The message oriented function, vceRecordMessage, operates on a specific message number. This function creates a new message, replacing the existing message, if any.

• The position-oriented function, vceRecord, operates on the current message in the specified context. Recording starts from the current position in the most recently accessed message.

Use the ADI functions adiRecordAsync or adiStartRecording if you need direct access to buffers. Refer to the ADI Service Developer's Manual for more information on playing and recording with the ADI service. Refer to the ADI Service Function Reference Manual for more information on the ADI service functions.

The vcerec demonstration program demonstrates copying messages from one voice file to another. Refer to Section 5.5 for more information.

Note: Playing and recording are mutually exclusive on a given context. Use the ADI Service to perform simultaneous play and record.

2.4.1 Record Functions

Recording optionally starts with a beep tone. The recording functions have a time limit. Silence detected during recording can optionally abort the recording.

If you want to...	Then use...
Start recording at the current position in the current message	vceRecord
Record a message into a specified voice object	vceRecordMessage

2.4.2 Record Completion Reasons

The following table lists the Voice Message service reason codes returned when record terminates. The value field of the VCEEVN_RECORD_DONE_EVENT states the reason.

Note: If record fails, the value field contains an error code.

If...	The DONE event contains...
The time limit in vceRecord is reached	CTA_REASON_TIMEOUT
No more space is available in the voice object, or recording in overwrite mode reached the end of the existing message	CTA_REASON_FINISHED
Silence is detected at the beginning of recording	CTA_REASON_NO_VOICE
Silence occurs after some energy is recorded	CTA_REASON_VOICE_END
Record is stopped at any time by calling vceStop	CTA_REASON_STOPPED
A touch tone digit is received and the corresponding bit in the DTMF abort parameter is set	CTA_REASON_DIGIT
The call is ended	CTA_REASON_RELEASED
You record to an object with an encoding that is not supported by the attached device service	CTAERR_FUNCTION_NOT_AVAIL

2.4.3 Resizing Messages

When a message is replaced by vceRecordMessage, the new message might be larger or smaller than the previous one. The ability to resize a message depends on the object and the position of the message in the object. A message in a VOX file or a message that is located at the end of a flat (unformatted) file can grow without limit (until the disk is full). A file can physically shrink if the message at the end of the file is replaced with a smaller one (the shrinkage occurs when the file is closed). A message in a memory block is limited to the size of the memory specified with vceOpenMemory or vceCreateMemory.

There is usually only one message in a flat file or a memory block. If there is more than one message in a flat file or memory block and a message in the middle is replaced, the new message cannot be larger than the existing message. vceRecordMessage ends with CTA_REASON_FINISHED when the limit is reached.

2.4.4 Record Parameters

The record functions take an optional pointer to a parameter structure for controlling beep tone, silence detection, record gain (including optional automatic gain control), and DTMF abort. If you pass NULL, the parameters take default values. Refer to VCE.RECORD in Appendix B for more information about the record parameters.

Note: Automatic gain control is an algorithm applied to incoming speech (recording) before compression and storage that is designed to keep the amplitude of the stored speech at a target level.

The following figures illustrate the three time windows that terminate the record function:

Figure 3. Record Termination - No Voice

Figure 4. Record Termination - Voice End

Figure 5. Record Termination - Timeout

2.5 Play and Record States

The following diagram illustrates the play and record states:

Figure 6. Play and Record States

The following table describes the play and record states:

State	Description
Idle	The play and record functions are not active.
Playing	When the application initiates playing by invoking a play function (vcePlay, vcePlayList, or vcePlayMessage), the Voice Message service is in the playing state.
Recording	When the application initiates recording by invoking a record function (vceRecord or vceRecordMessage), the Voice Message service is in the recording state.
Play Stopping	The application initiates stopping the play by invoking vceStop. The Voice Message service generates a VCEEVN_PLAY_DONE event and returns to the idle state.
Record Stopping	The application initiates stopping the record by invoking vceStop. The Voice Message service generates a VCEEVN_RECORD_DONE event and returns to the idle state.

The play or record state remains active until either

• A VCEEVN_PLAY_DONE event or a VCEEVN_RECORD_DONE event is received.

• vceStop is called.

2.6 Stopping

Call vceStop to stop play or record. Stopping play or record results in a DONE event. The value field of the DONE event contains CTA_REASON_STOPPED.

Note: CTA_REASON_STOPPED is also returned if play or record is stopped when the voice object being played or recorded is closed with vceClose. If you are playing a list, play is stopped if an object containing any message in the list is closed.

2.6.1 Using DTMF to Terminate Play or Record

By default, play or record terminates when any DTMF digit is detected. The play parameter structure and the record parameter structure provide a selective DTMF abort mask specifying which DTMF digits terminate the function.

The DTMF abort mask is a 16-bit entity where each bit corresponds to a specific key on the telephone keypad. Setting a bit in the mask causes the voice function to terminate if that particular key is entered. The DTMF abort mask corresponds to the DTMF telephone keys as shown:

	Most Significant Bit											Least Significant Bit
Bit Position	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
DTMF Key	D	C	B	A	#	*	9	8	7	6	5	4	3	2	1	0

For example, if the abort mask is set to 0x03FF, the playing/recording functions will terminate if any digit from 0 through 9 is entered by the remote party. The vcedef.h include file contains #defines (VCE_DTMF_xxx) for each digit and for certain digit groups.

2.7 Retrieving Context Status

vceGetContextInfo returns the current Voice Message service status of the specified context, including information about the current, or most recent, play or record operation.

The status block includes the following information:

• Current position in milliseconds relative to the beginning of the current message.

• Reason last play/record ended (0 initially and while function is active).

• Current or last function (play/record/none-yet).

• Underruns (cumulative for the lifetime of the context).

• Auxiliary error code (for example, an OS error from file access).

• Current value of play gain. This value is used for the next playing function if the play gain parameter is set to VCE_CURRENT_VALUE. Otherwise, this value is set to the value of the play gain parameter when playing starts. It can be changed by vceSetPlayGain.

• Current value of play speed. This value is used for the next playing function if the play speed parameter is set to VCE_CURRENT_VALUE. Otherwise, this value is set to the value of the play speed parameter when playing starts. It can be changed by vceSetPlaySpeed.

• Number of messages in the current message. Use vceGetCurrentList to retrieve the actual message list.

• Encoding of the current message.

• Frame size of the encoding.

• Frame duration of the encoding.

The millisecond and position values are updated as each buffer is submitted internally for play or completed for record.

Note: When play ends, the values may be adjusted downward if not all of the data submitted to the device was actually played.

2.8 Retrieving Voice Object Information

Use the following functions to retrieve voice object information:

To get the...	Use...
File type, open mode, or associated context of an open voice object	vceGetOpenInfo
Size of a specified message in milliseconds	vceGetMessageSize
Highest message number currently in use in the voice object	vceGetHighMessageNumber
Lowest unused message number for the voice object	vceGetUniqueMessageNumber

Refer to Section 5.3, Voice File Information: vceinfo for details about the demonstration program that displays information about a voice file.

2.9 Editing Voice Messages

The editing functions allow you to access and modify data in a voice object without actually playing or recording. You can open a file and edit it without needing a voice board.

The Voice Message service provides functions for the following editing tasks:

• Copying

• Converting encoding or amplitude

• Erasing

• Reading/Writing

2.9.1 Copying and Converting Messages

Use the following functions to copy and convert messages:

To...	Use...
Create or replace a message in a destination object with a copy of a message in a source object when the encoding is the same	vceCopyMessage
Create or replace a message in a destination object with a copy of a message in a source object when the encoding is different or you want to change the amplitude	vceConvertMessage

The vcecopy demonstration program demonstrates copying messages from one voice file to another. Refer to Section 5.2, Voice File Copy/Convert Program: vcecopy for more information.

2.9.2 Erasing Messages

Use the following functions to erase messages:

To...	Use...
Remove an entire message from a specified voice object by changing the message size to zero (0)	vceEraseMessage
Remove a specified number of milliseconds of data at the current position in the current message	vceErase

2.9.3 Reading and Writing Messages

Use the following functions to read and write messages:

To...	Use...
Read data at the current position in the current message	vceRead
Write data at the current position in the current message	vceWrite

2.10 Converting Text Strings to Message Lists

The Prompt Builder contains functions for converting text strings to message lists. The Prompt Builder allows an application to announce dates, times, numbers, and monetary amounts.

Use the following functions to convert text strings to message lists:

To...	Use...
Build a list of message numbers from specified text	vceBuildPromptList
Load a prompt rules table into memory	vceLoadPromptRules
Release resources associated with a prompt rules table	vceUnloadPromptRules

2.10.1 How the Prompt Builder Works

The Prompt Builder takes a set of compiled rules that state how text strings are to be translated into voice messages. An associated voice file contains the messages corresponding to these rules. For example, the text string 10 is translated to the voice message ten.

Refer to Appendix D for a description of the runtime files and the commands that can be used to create custom rules.

An application can convert text strings to message lists. A text string containing data, such as 11/1/01, is passed to vceBuildPromptList which then builds a list of messages to be played from a standard message library. The output list of message numbers is passed to vcePlayList.

2.10.2 Prompt Rules Table

A prompt rules table contains the rules needed to interpret a text string.

Use this utility...	To...
mkprompt	Create a prompt rules table. Refer to Section 5.6.
testpmpt	Test a prompt rules table. Refer to Section 5.7.

The standard prompt rules table (american.tbl) supplied with the Prompt Builder can play dates, times, numbers, and dollar amounts.

Figure 7. Prompt Builder in the Voice Message Service

The compiled table and associated voice message file is different for each spoken language supported. Additional phrase types can be supported by adding to the rules provided, or by developing a new set of rules for different spoken languages. Refer to Appendix D for information on adding or changing prompt rules.