(Page 3 of 14 in this chapter)

5.2 Characteristics

Before you start to create an application, you should first understand the following important characteristics about the CT Access Voice Message service. File Types Voice Encoding Formats Voice Handles Messages Lists Current Message and Current Position Prompt Builder Message Text

5.2.1 File Types

The CT Access Voice Message service supports the following file types: Natural MicroSystems VOX file format. This file format stores multiple messages in one file and enables messages to be deleted, added, edited, and annotated. Waveform Audio File Format (WAVE) files Flat files, which contain no header or format
Refer to Appendix B for more information about the VOX file format. The voxinfo utility displays information about a VOX file. Refer to Section 13.3.7, VOX File Information: voxinfo for more information.

5.2.2 Voice Encoding Formats

When recording or playing speech files, you must select an encoding format. The primary issue to consider when selecting a format is the compression ratio vs. fidelity. More aggressive compression requires less disk space and reduces host-to-board loading.
On heavily loaded systems, the throughput requirements between the host and the board may cause gaps in the speech record or playback. This is called an underrun condition. Greater compression may be necessary in this case to eliminate the problem.
The ADI service opened on the same CTA context determines what type of voice encoding is supported. For information on attaching the ADI service, refer to Section 3.3.5, Opening the ADI Service.
Alliance Generation boards support the following encoding formats: NMS ADPCM G.726 compliant ADPCM OKI ADPCM (6 and 8 kHz) Mu-law and A-law 8 and 16-bit PCM at 11 kHz 16-bit PCM at 8 kHz
Each encoding has a minimum data block size, called a frame. For Natural MicroSystems' boards, a frame corresponds to 10 or 20 milliseconds of speech, depending on the encoding. All messages in a voice file must have the same encoding.
The encodings refer to the data going to and from the host, typically stored in a voice file. Except for VCE_ENCODE_NMS_64, this host encoding is independent of the line encoding, which is always either mu-law or a-law, depending on how the board is configured when it is initialized. Note: The ADI service has equivalent encoding formats which begin with ADI_.
The encoding formats are listed in the following table: Encoding Format Description Sample Size (bits) Sample Rate (Hz) Frame Size (Bytes) Frame Time (ms) Data Rate (Bytes/sec) VCE_ENCODE_NMS_16 NMS ADPCM 16kbs 2 8000 42 20 2100 VCE_ENCODE_NMS_24 NMS ADPCM 24kbs 3 8000 62 20 3100 VCE_ENCODE_NMS_32 NMS ADPCM 32kbs 4 8000 82 20 4100 VCE_ENCODE_NMS_64 framed PCM 64kbs 8 8000 162 20 8100 VCE_ENCODE_MULAW mu-law 64kbs 8 8000 80 10 8000 VCE_ENCODE_ALAW A-law 64kbs 8 8000 80 10 8000 VCE_ENCODE_PCM8M16 PCM 8k mono 16 bit 16 8000 160 10 16000 VCE_ENCODE_OKI_24 OKI ADPCM 24kbs 4 6000 30 10 3000 VCE_ENCODE_OKI_32 OKI ADPCM 32kbs 4 8000 40 10 4000 VCE_ENCODE_PCM11M8 PCM 11kHz 8 bit mono (Wave format) 8 11000 110 10 11000 VCE_ENCODE_PCM11M16 PCM 11kHz 16 bit mono (Wave format) 16 11000 220 10 22000 VCE_ENCODE_G726 G.726 ADPCM 32kbs 4 8000 40 10 4000

Encoding Format	Description	Sample Size (bits)	Sample Rate (Hz)	Frame Size (Bytes)	Frame Time (ms)	Data Rate (Bytes/sec)
VCE_ENCODE_NMS_16	NMS ADPCM 16kbs	2	8000	42	20	2100
VCE_ENCODE_NMS_24	NMS ADPCM 24kbs	3	8000	62	20	3100
VCE_ENCODE_NMS_32	NMS ADPCM 32kbs	4	8000	82	20	4100
VCE_ENCODE_NMS_64	framed PCM 64kbs	8	8000	162	20	8100
VCE_ENCODE_MULAW	mu-law 64kbs	8	8000	80	10	8000
VCE_ENCODE_ALAW	A-law 64kbs	8	8000	80	10	8000
VCE_ENCODE_PCM8M16	PCM 8k mono 16 bit	16	8000	160	10	16000
VCE_ENCODE_OKI_24	OKI ADPCM 24kbs	4	6000	30	10	3000
VCE_ENCODE_OK`I`_32	OKI ADPCM 32kbs	4	8000	40	10	4000
VCE_ENCODE_PCM11M8	PCM 11kHz 8 bit mono (Wave format)	8	11000	110	10	11000
VCE_ENCODE_PCM11M16	PCM 11kHz 16 bit mono (Wave format)	16	11000	220	10	22000
VCE_ENCODE_G726	G.726 ADPCM 32kbs	4	8000	40	10	4000

5.2.3 Voice Handles

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 access a voice object

Get a voice handle by calling vceOpenFile, vceCreateFile or
vceOpenMemory to open or create the file or to create a context for a memory block.

Note: You can also associate a voice handle with a file (or device) that is already open by calling vceAssignHandle.
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 CTA context. When you specify a voice handle, the CTA context is implied as illustrated in Figure 40.
Figure 40. A Voice Handle Associated With a CTA Context Note: If you have multiple threads, each with its own CTA context, and you want to load a prompt message into memory, each thread must obtain its own voice handle for the memory that contains the prompt.
vceClose releases a voice handle. It closes the associated file if the handle was obtained by vceOpenFile or vceCreateFile.

5.2.4 Messages

A voice object can contain 0, 1, or multiple messages depending on the file type. A message is a logical, contiguous block of speech identified by an unsigned number. Messages can be created in an open file or memory block by recording or copying to it. Unstructured formats (flat files, memory) contain only message zero (0) when first opened. Other messages can be defined by using vceDefineMessages.
The range of valid message numbers is dependent on the object type. Type Range of Valid Message Numbers VOX 0 to 32,767 Flat 0 to 65,535 Memory 0 to 65,535 WAVE 0 only
All unused (or deleted) message numbers in the valid range refer to zero-length messages and do not result in an error when referenced.
The special message number VCE_ALL_MESSAGES allows you to operate on all messages in an object as one message. Use this to copy all messages, play all messages, or erase all messages. You cannot record or write to this message number.

Type	Range of Valid Message Numbers
VOX	0 to 32,767
Flat	0 to 65,535
Memory	0 to 65,535
WAVE	0 only

5.2.5 Lists

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.

5.2.6 Current Message and Current Position

When you play a message or a list of messages, it becomes the current message for pausing and resuming, repositioning, etc. The current message is associated with the CTA context handle. The current message has a current position.
Figure 41. Current Message/Current Position
The following functions use and/or modify the current position:

vceErase

vcePlay

vceRead

vceRecord

vceSetPosition

vceWrite
The following functions define the current message:

vceConvertMessage

vceCopyMessage

vceEraseMessage

vcePlayList

vcePlayMessage

vceRecordMessage

vceSetCurrentList

vceSetCurrentMessage
If any voice object containing a message in the current message (list) is closed, there is no longer a current message. Any active play or record will be stopped. Note: The current message is not affected when a call hangs up.

5.2.7 Prompt Builder

Text strings can be converted to message lists. A text string containing data, such as "11/1/96", is passed to vceBuildPromptList which then builds a list of messages to be spoken from a standard message library. The output list of message numbers is passed to vcePlayList.
The interpretation of the text strings to lists of message numbers is controlled by the prompt rules table. The prompt rules table (american.tbl) contains the rules needed to interpret a text string.
The mkprompt utility demonstrates creating a prompt rules table. Refer to Section 13.3.4, Make Prompt: mkprompt for more information.
The testpmpt utility demonstrates testing a prompt rules table. Refer to Section 13.3.6, Test Prompt: testpmpt for more information.
The standard prompt rules table supplied with the Prompt Builder can say dates, times, numbers, and dollar amounts.
Figure 42. The Prompt Builder in the CT Access Voice Message Service
The compiled table and associated voice message file will be 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 C for information on adding or changing prompt rules.

5.2.8 Message Text

VOX files can have a text string (or other data) associated with each message. This is typically used to contain labels for prompts.
vceCopyMessageText, vceReadMessageText, and vceWriteMessageText allow you to edit message text. Refer to Section 5.12, Using Message Text.

(Page 3 of 14 in this chapter)

Tech_Support@nmss.com