(Page 1 of 1 in this chapter)

Chapter 2

Overview of the Voice Message Service

2.1 About the CT Access Voice Message Service
2.2 Characteristics
2.2.1 Voice File Types
2.2.2 Voice Encoding Formats
2.2.3 Voice Handles
2.2.4 Messages
2.2.5 Lists
2.2.6 Current Message and Current Position
2.2.7 Prompt Builder
2.2.8 Message Text
2.3 Getting a Voice Handle
2.4 System Restrictions

2.1 About the CT Access Voice Message Service

The CT Access Voice Message service:

The following sections explain:

Refer to Chapter 9 for demonstration programs using the Voice Message service's play and record functions.

2.2 Characteristics

You need to understand the following characteristics of the Voice Message service as you prepare to create an application:

2.2.1 Voice File Types

The CT Access Voice Message service supports the following voice file types:

The voxinfo utility displays information about a VOX file. Refer to Section 9.3.3 for more information.

2.2.2 Voice Encoding Formats

When recording speech files, you must select an encoding format. The primary issue to consider when selecting a format is the compression ratio versus 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 the ADI Service Developer's Manual.

AG boards support the following encoding formats:

Each encoding format 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 CT Access 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
16 kbit/s

 2

 8000

 42

 20

 2100

VCE_ENCODE_NMS_24

 NMS ADPCM
24 kbit/s

 3

 8000

 62

 20

 3100

VCE_ENCODE_NMS_32

 NMS ADPCM
32 kbit/s

 4

 8000

 82

 20

 4100

VCE_ENCODE_NMS_64

 framed PCM
64 kbit/s

 8

 8000

 162

 20

 8100

VCE_ENCODE_MULAW

 mu-law 64 kbit/s

 8

 8000

 80

 10

 8000

VCE_ENCODE_ALAW

 A-law 64 kbit/s

 8

 8000

 80

 10

 8000

VCE_ENCODE_PCM8M16

 PCM 8k mono
16-bit (Wave)

 16

 8000

 160

 10

 16000

VCE_ENCODE_OKI_24

 OKI ADPCM
24 kbit/s

 4

 6000

 30

 10

 3000

VCE_ENCODE_OKI_32

 OKI ADPCM
32 kbit/s

 4

 8000

 40

 10

 4000

VCE_ENCODE_PCM11M8

 PCM 11kHz 8 bit mono (Wave)

 8

 11000

 110

 10

 11000

VCE_ENCODE_PCM11M16

 PCM 11 kHz
16- bit mono (Wave format)

 16

 11000

 220

 10

 22000

VCE_ENCODE_G726

 G.726 ADPCM
32 kbit/s

 4

 8000

 40

 10

 4000

VCE_ENCODE_IMA_24

 IMA ADPCM
24 kbits/s

 4

 6000

 36

 10

 3600

VCE_ENCODE_IMA_32

 IMA ADPCM
32 kbits/s

 4

 8000

 46

 10

 4600

2.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:

  1. 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.


  2. 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 2.





Figure 2.	 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.






2.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.






2.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.






2.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 3.	 Current Message/Current Position




The following functions use and/or modify the current position:




The following functions define the current message:





Refer to Chapter 8 for more information about these functions.



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.





2.2.7	 Prompt Builder





The Prompt Builder in the Voice Message service contains functions for converting text strings to message lists. The Prompt Builder allows an application to announce dates, times, numbers and monetary amounts. A text string containing the variable data, such as 10/21/96, is passed to the Prompt Builder which then uses a prompt rules table to build a list of messages to be spoken from a standard message library. The output list of message numbers can be passed directly to vcePlayList.



Specifically, 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 Chapter 6 for more information about using the Prompt Builder. Refer to Appendix E for a description of the runtime files and the commands that can be used to create custom rules.






2.2.8	 Message Text





The Voice Message service contains functions for copying, reading, and writing message text. Message text is a descriptive string which can be attached to a message in a NMS VOX file.



VOX files can have a text string (or other data) associated with each message. This is typically used to contain labels for prompts.



The following table lists when to use the message text functions available in the CT Access Voice Message service:


 





 If you want to...



 Then use this function...




 Copy the associated data from one voice message to another



 vceCopyMessageText




 Read the message text for a specified voice message in a VOX file



 vceReadMessageText




 Store associated message text for a specified voice message in a VOX file



 vceWriteMessageText















Refer to Chapter 8 for more information about these functions.






2.3	 Getting a Voice Handle





Now that you have an understanding of the important characteristics of the CT Access Voice Message service, you can create an application using the Voice Message service. 



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




 Access a file (or device) that is already opened



 vceAssignHandle















Refer to Chapter 8 for more information about these functions.



Once you have obtained a voice handle, you can use the handle in combination with a message number to identify a segment of speech in the object for playing, recording, or editing.






2.4	 System Restrictions





The following system restrictions should be noted regarding the CT Access Voice Message service:















 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1999, Natural MicroSystems, Inc.   All rights
reserved.