(Page 1 of 1 in this chapter)

Chapter 7

Function Summary

7.1 Introduction
7.2 Getting a Voice Handle and Closing a Voice File
7.3 Playing
7.4 Recording
7.5 Stopping
7.6 Querying
7.7 Setting Current Message and Current Position
7.8 Editing Messages
7.9 Converting Text Strings to Message Lists
7.10 Creating and Editing Message Text
7.11 Performing Miscellaneous Voice Functions

7.1 Introduction

The CT Access Voice Message service:

The CT Access Voice Message service provides functions to:

Refer to Appendix A for definitions of CT Access terminology.

7.2 Getting a Voice Handle and Closing a Voice File

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

Function

 S/A*

 Description

vceOpenFile

 S

 Opens a voice file and returns a voice handle. The file can be opened for play only or both play and record.

vceCreateFile

 S

 Creates a new file of a specified type.

vceOpenMemory

 S

 Assigns a voice handle to a range of memory.

vceAssignHandle

 S

 Associates a voice handle with a file (or device) that is already opened.

vceClose

 S

 Closes a voice file or other voice object.

 *Synchronous or Asynchronous


Once you have obtained a voice handle, use the handle in combination with a message number to identify a segment of speech in the object for playing, recording, or editing. A message is a logical, contiguous block of speech identified by a message number.

Refer to Section 2.3, Getting a Voice Handle for more information.

7.3 Playing

The following functions allow you to start playing from different positions in a message, and to adjust the speed and volume during playback:

Function

 S/A*

 Description

vcePlay

 A

 Starts playing from the current position in the current message. This function can be used to resume playing after stopping a message in the middle.

vcePlayList

 A

 Starts playing from the beginning of the first message in a list of messages. It allows a message to be built from a library of words or phrases contained in a voice file. This function allows you to play a sequence of messages with no delay between messages.

vcePlayMessage

 A

 Plays one message from a specified voice object.

vceSetPlayGain

 S

 Changes the volume (loudness) of message playback by adjusting the amplification, or gain, applied to the message being played.

vceSetPlaySpeed

 S

 Changes the current play speed to a specified rate.

 *Synchronous or Asynchronous


Refer to Section 3.2, Playing for more information.

The vceplay demonstration program demonstrates copying messages from one voice file to another. Refer to Section 9.2.3, Voice File Play: vceplay for more information.

7.4 Recording

The following functions allow you to record messages:

Function

 S/A*

 Description

vceRecord

 A

 Starts recording at the current position in the current message.

vceRecordMessage

 A

 Records a message in an open voice object.

 *Synchronous or Asynchronous


Refer to Section 3.3, Recording for more information.

The vcerec demonstration program demonstrates copying messages from one voice file to another. Refer to Section 9.2.4, Voice File Record: vcerec for more information.

7.5 Stopping

vceStop stops the currently active play or record. This function is asynchronous.

7.6 Querying

The following functions allow you to obtain information about play and record messages, voice files, and sizes:

Function

 S/A*

 Description

vceGetCurrentList

 S

 Retrieves the list of messages comprising the current message.

vceGetCurrentSize

 S

 Retrieves the size, in milliseconds, of the current message.

vceGetEncodingInfo

 S

 Gets information about a voice encoding.

vceGetHighMessageNumber

 S

 Returns the highest message number in use in the voice object.

vceGetMessageSize

 S

 Returns the size in milliseconds of the specified message.

vceGetOpenInfo

 S

 Gets information about an open voice object.

vceGetContextInfo

 S

 Gets the current Voice Message service status of the specified CTA context.

vceGetUniqueMessageNumber

 S

 Gets the lowest available (empty) message in the file.

vceGetWaveInfo

 S

 Gets wave header information for a given encoding value.

 *Synchronous or Asynchronous


Refer to Chapter 4 for more information about these functions.

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

7.7 Setting Current Message and Current Position

When you play a message or a list of messages, the message or list 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.

The following functions allow you to set the current message or change the current position:

Function

 S/A*

 Description

vceSetCurrentList

 S

 Defines the current message to be a list of messages.

vceSetCurrentMessage

 S

 Defines the current message.

vceSetPosition

 S

 Sets the current position in the current message.

 *Synchronous or Asynchronous


You cannot set the current message or change the position if play or record is active.

Refer to Section 2.2.6, Current Message and Current Position for more information.

7.8 Editing Messages

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

Function

 S/A*

 Description

vceConvertMessage

 S

 Copies a message from one voice object to another. The encoding and/or amplitude of the message is translated.

vceCopyMessage

 S

 Creates or replaces a message in a destination object with a copy of a message in a source object. The source and destination objects must have the same encoding.

vceErase

 S

 Removes a specified number of milliseconds of data at the current position in the current message.

vceEraseMessage

 S

 Removes an entire message from a specified voice object.

vceRead

 S

 Reads data at the current position in the current message.

vceWrite

 S

 Writes data at the current position in the current message.

 *Synchronous or Asynchronous


Refer to Chapter 5 for more information.

7.9 Converting Text Strings to Message Lists

Text strings can be converted to message lists. A text string containing variable 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 Prompt Builder allows the application to announce dates, times, numbers, and monetary amounts.

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 compiled table and associated voice message file will be different for each spoken language supported.

The following functions allow you to build message numbers, and to load and to unload the prompt rules table:

Function

 S/A*

 Description

vceBuildPromptList

 S

 Builds a list of message numbers based on the specified prompt rule table entry point and variable text.

vceLoadPromptRules

 S

 Reads the specified prompt rules table into memory.

vceUnloadPromptRules

 S

 Releases resources associated with the specified prompt rules.

 *Synchronous or Asynchronous


Refer to Section 2.2.7, Prompt Builder for more information.

The CT Access Voice Message service is shipped with utilities for creating and testing prompt rules tables.

Use this utility...

 For a demonstration of...

mkprompt

 Creating a prompt rules table. Refer to Section 9.3.1.

testpmpt

 Testing a prompt rules table. Refer to Section 9.3.2.

7.10 Creating and Editing Message Text

Message text is a descriptive string which can be attached to a message in a NMS VOX file. The following functions allow you to write and copy message text:

Function

 S/A*

 Description

vceCopyMessageText

 S

 Copies message text from one voice message to another voice message.

vceReadMessageText

 S

 Reads the message text for a specified voice message in a VOX file.

vceWriteMessageText

 S

 Writes message text for a specified voice message in a NMS VOX file.

 *Synchronous or Asynchronous

7.11 Performing Miscellaneous Voice Functions

The following additional miscellaneous functions are available in the CT Access Voice Message service:

Function

 S/A*

 Description

vceDefineMessages

 S

 Defines message boundaries in a flat (unformatted) file or memory block.

vceSetWaveInfo

 S

 Loads a new entry in the WAVE encoding table.

 *Synchronous or Asynchronous


(Page 1 of 1 in this chapter)

tech_support@nmss.com
Copyright © 1999, Natural MicroSystems, Inc. All rights reserved.