(Page 5 of 14 in this chapter)
5.4 Playing
There are 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.
There are no buffer-oriented play functions. Use the ADI function
adiPlayAsync
or
adiStartPlaying
if you need direct access to buffers. Refer to
Chapter 7
for more information on the ADI Service: Playing/Recording. Refer to the
ADI Service Function Reference
Manual
for more information on the ADI functions.
The
vceplay
demonstration program demonstrates copying messages from one voice file to another. Refer to
Section 13.2.8,
Voice File Play: vceplay
for more information.
5.4.1 Playing Functions
The following table lists when to use the play functions available in the CT Access Voice Message service.
If you want to...
Then use this function...
Start playing from the current position in the current message
vcePlay
Start playing from the beginning of the first message in a list of messages
vcePlayList
Play one message from a specified voice object
vcePlayMessage
Change the current play speed to a specified rate
vceSetPlaySpeed
Change the volume (loudness) of message playback by adjusting the amplification, or gain, applied to the message being played
vceSetPlayGain
5.4.2 Playing Completion Reasons
The following table lists the Voice Message service reason codes returned when play terminates. The reason is stated in the
value
field of the
VCEEVN_PLAY_DONE_EVENT
.
Note:
If play fails, the
value
field will contain an error code.
If...
Then play ends with...
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
Play is stopped because of a speech recognition event
CTA_REASON_RECOGNITION
You play an object that has an encoding that is not supported by the attached device service
CTAERR_FUNCTION_NOT_AVAIL
5.4.3 Speed and Gain Adjustment
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 CTA 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
.
The playing speed may also be adjusted 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 boards, replace
voice.dsp
in the
ag.cfg
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
AG Access Installation Manual
.
Use
vceGetContextInfo
to get the current gain and speed values.
5.4.4 Parameters
The play functions take an optional pointer to a parameter structure. If you pass
NULL
, the parameters take default values. Refer to
Section 3.5,
Managing Parameters
. Refer to Appendix D in the
CT Access Function Reference Manual
for more detailed information about the play parameters.
Field Name
Default Value
Description
DTMFabort
0xffff
Abort on DTMF (bit mask).
gain
0
Playing gain in dB, or VCE_CURRENT_VALUE to use the most recent gain setting. The valid range for AG boards is -54 to 24.
speed
100
Initial speed in percent, or VCE_CURRENT_VALUE to use the most recent speed setting. The valid range for AG boards is 50 - maxspeed.
maxspeed
100
Maximum play speed in percent. The valid range for AG boards is 100 - 200.
(Page 5 of 14 in this chapter)
Tech_Support@nmss.com
Copyright © 1996, Natural MicroSystems, Inc. All rights reserved.
(Page 5 of 14 in this chapter) (Page 5 of 14 in this chapter)