(Page 25 of 69 in this chapter)
Version
adiPlayAsync
Description
Initiates a voice play operation with asynchronous buffer submission.
Prototype
DWORD
adiPlayAsync
(
CTAHD
ctahd
,
unsigned
encoding
,
void
*buffer
,
unsigned
bufsize
,
unsigned
flags
,
ADI_PLAY_PARMS
*parms
)
ctahd
CTA context handle returned by
ctaCreateContext
.
encoding
Data encoding format (a complete list of
ADI_ENCODING_xxx
values is in
adidef.h
).
buffer
Pointer to initial voice data buffer.
bufsize
Number of bytes stored at the address in
buffer
.
flags
Signifies if the specified buffer is the only buffer to be played (can be set to
ADI_PLAY_LAST_BUFFER
or
0
).
parms
Pointer to play parameters according to the following structure (
NULL
value uses the default play parameters):
typedef struct
{
DWORD size; /* size of this structure */
DWORD DTMFabort; /* abort on DTMF */
INT32 gain; /* playing gain in dB */
DWORD speed; /* initial speed in percent (AG boards only) */
DWORD maxspeed; /* max play speed in percent (AG boards only) */
} ADI_PLAY_PARMS;
Return Values
SUCCESS
ADIERR_INVALID_CALL_STATE
CTAERR_BAD_ARGUMENT
Either invalid
encoding
or
NULL
buffer
.
CTAERR_BAD_SIZE
bufsize
is not a multiple of framesize for selected
encoding
.
CTAERR_FUNCTION_ACTIVE
CTAERR_INVALID_CTAHD
CTAERR_INVALID_STATE
CTAERR_OUTPUT_ACTIVE
Events
ADIEVN_PLAY_BUFFER_REQ
Generated whenever the ADI service needs a buffer containing voice data. The application should respond by either submitting a full buffer (
adiSubmitPlayBuffer
) or a full or partial buffer (
adiSubmitPlayBuffer
with flag indicating
ADI_PLAY_LAST_BUFFER
). If the
ADI_PLAY_UNDERRUN
bit is set, an underrun occurred, meaning that playing was temporarily suspended because there was no buffer to play.
ADIEVN_PLAY_DONE
Generated by the ADI service when the play operation terminates. The event
size
field contains the total number of bytes played during the function's instance. The event
value
field contains one of the following termination conditions, or an error code:
CTA_REASON_DIGIT
Aborted due to DTMF.
CTA_REASON_FINISHED
The buffer submitted with the
ADI_PLAY_LAST_BUFFER
flag set has completed playing.
CTA_REASON_RECOGNITION
Aborted because of speech recognition. You will only receive this reason if your application is using a speech recognition library.
CTA_REASON_RELEASED
The call was terminated.
CTA_REASON_STOPPED
Stopped by application request.
DSP File
For AG and CG hardware, each encoding rate of this function requires a specific DSP file to be loaded. For QX hardware, all of the following encoding rates are supported in the standard DSP file. The files and encoding rates are shown in the following table:
AG DSP File
AG 2000/
AG 4000/C DSP File
CG 6000C File
QX
Support
Encoding Type
voice.dsp/
voxp.dsp
voice.m54
voice.f54
Y
ADI_ENCODE_NMS_16
voice.dsp/
voxp.dsp
voice.m54
voice.f54
Y
ADI_ENCODE_NMS_24
voice.dsp/
voxp.dsp
voice.m54
voice.f54
Y
ADI_ENCODE_NMS_32
voice.dsp/
voxp.dsp
voice.m54
voice.f54
Y
ADI_ENCODE_NMS_64
rvoice.dsp
rvoice.m54
rvoice.f54
Y
ADI_ENCODE_MULAW*
rvoice.dsp
rvoice.m54
rvoice.f54
Y
ADI_ENCODE_ALAW*
rvoice.dsp
rvoice.m54
rvoice.f54
Y
ADI_ENCODE_PCM8M16*
okiply.dsp/
okirec.dsp
oki.m54
oki.f54
N
ADI_ENCODE_OKI_24
okiply.dsp/
okirec.dsp
oki.m54
oki.f54
N
ADI_ENCODE_OKI_32
waveply.dsp
wave.m54
wave.f54
Y
ADI_ENCODE_PCM11M8
waveply.dsp
wave.m54
wave.f54
Y
ADI_ENCODE_PCM11M16
g726ply.dsp/
g726rec.dsp
g726.m54
g726.f54
Y
ADI_ENCODE_G726
QX only
ADI_ENCODE_G726_16
QX only
ADI_ENCODE_G726_24
QX only
ADI_ENCODE_G726_32
QX only
ADI_ENCODE_G726_40
imaply.dsp/
imarec.dsp
ima.m54
ima.f54
N
ADI_ENCODE_IMA_24
imaply.dsp/
imarec.dsp
ima.m54
ima.f54
NA
ADI_ENCODE_IMA_32
QX only
ADI_ENCODE_VOX_32
gsm_ms.m54
gsm_ms.f54
NA
ADI_ENCODE_GSM
(CT Access 4.0 only)
*These encodings do not support Automatic Gain Control on AG-8, AG 24/30/48/60, AG T1/E1, AG Quad, and AG Quad Dual boards.
Note:
Refer to the
QX 2000 Installation and Developer's Manual
for DSP file information specific to the QX board family. Refer to the
AG 2000 Installation and Developer's Manual,
the
AG 4000 Installation and Developer's Manual
and the
AG 4000C Installation and Developer's Manual
for the DSP files for the AG 2000 and AG 4000/C boards. Refer to the
CG 6000C Installation and Developer's Manual
for the DSP files for the CG 6000C board.
Details
This function initiates a voice playback operation. The voice data is supplied in a sequence of buffers. The application has complete latitude and responsibility for allocating, filling, and submitting buffers to the ADI service.
The
bufsize
can be arbitrarily large but must be an integral multiple of
framesize
bytes for the selected
encoding
. For optimum performance, the
bufsize
should be the largest frame multiple that will fit in one AG board buffer. You can obtain this size by calling
adiGetEncodingInfo
(refer to the
maxbufsize
argument). If
bufsize
is less than or equal to the board buffer size, you can re-use the buffer as soon as this function returns. Otherwise, to avoid overwriting data, you must wait for the second
ADIEVN_PLAY_BUFFER_REQ
before you can re-use the buffer.
After play initiates, the ADI service sends
ADIEVN_PLAY_BUFFER_REQ
events to the application whenever more data is needed. The application responds to this event by submitting a filled voice buffer via
adiSubmitPlayBuffer
. The application should only submit buffers in response to
ADIEVN_PLAY_BUFFER_REQ
events.
For proper operation, each buffer must be submitted while the previous buffer is being played. If a buffer is submitted too late, an underrun occurs and silence is played. You can monitor for underruns by checking the
ADI_PLAY_UNDERRUN
bit in the
value
field of the
ADIEVN_PLAY_BUFFER_REQ
event. Use
adiGetPlayStatus
to retrieve a count of underruns that occurred since play started.
The application terminates play by submitting a buffer with the
flags
argument set to
ADI_PLAY_LAST_BUFFER
. After the ADI service has played the buffer that was submitted with the flag set, it generates an
ADIEVN_PLAY_DONE
event with the value set to
CTA_REASON_FINISHED
.
Refer to the
ADI Service Developer's Manual
for more details about play operations in asynchronous mode.
See Also
adiSubmitPlayBuffer
,
adiPlayFromMemory
,
adiStartPlaying
,
adiStopPlaying
,
adiGetEncodingInfo
,
adiModifyPlayGain
,
adiModifyPlaySpeed
Example
Refer to the
playrec
demonstration program.
(Page 25 of 69 in this chapter)
Version
Want to send us feedback on our documentation? Email:
Tech_Pubs@nmss.com
Copyright © 2000, Natural MicroSystems, Inc. All rights reserved.
(Page 25 of 69 in this chapter) Version