adiPlayAsync

Initiates a voice play operation with asynchronous buffer submission.

Supported board types

Prototype

DWORD adiPlayAsync ( CTAHD ctahd, unsigned encoding, void *buffer, unsigned bufsize, unsigned flags, ADI_PLAY_PARMS *parms)

Argument

Description

ctahd

Context handle returned by ctaCreateContext or ctaAttachContext.

encoding

Data encoding format. See Voice encoding formats for a complete list.

buffer

Pointer to initial voice data buffer.

bufsize

Number of bytes stored at the address in buffer.

flags

Indicates 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;

Refer to ADI_PLAY_PARMS for field descriptions and valid values.

Return values

Return value

Description

SUCCESS

 

ADIERR_INVALID_CALL_STATE

Function not valid in the current 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

Function already started.

CTAERR_INVALID_CTAHD

Context handle is invalid.

CTAERR_INVALID_STATE

Function not valid in the current port state.

CTAERR_OUTPUT_ACTIVE

Play failed because there is another active output function.

CTAERR_SVR_COMM

Server communication error.

Events

Event

Description

ADIEVN_PLAY_BUFFER_REQ

Generated when the ADI service needs a buffer containing voice data. The application responds 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

Buffer submitted with the ADI_PLAY_LAST_BUFFER flag set completed playing.

CTA_REASON_RECOGNITION

Aborted because of speech recognition. You receive this reason only if the application is using a speech recognition library.

CTA_REASON_RELEASED

Call terminated.

CTA_REASON_STOPPED

Stopped by application request.

Details

Use adiPlayAsync to initiate 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 must be the largest frame multiple that fits in one 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 reuse 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 reuse the buffer.

After play initiates, the ADI service sends ADIEVN_PLAY_BUFFER_REQ to the application whenever more data is needed. The application responds to this event by submitting a filled voice buffer with adiSubmitPlayBuffer. The application must submit buffers only in response to ADIEVN_PLAY_BUFFER_REQ.

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 ADIEVN_PLAY_DONE with the value set to CTA_REASON_FINISHED.

Refer to Recording and playing for information about play operations in asynchronous mode.

Encoding formats and DSP files

When recording or playing speech files on AG boards, a specific DSP file must be loaded for each encoding type. For more information, refer to Voice encoding formats.

When recording or playing speech files on CG boards, a specific DSP file must be loaded for each encoding type except when using the native play and record feature. The native play and record feature combines an ADI port with an MSPP endpoint and plays or records speech data directly to or from an IP endpoint with no transcoding. For information on the native play and record feature, refer to Performing NMS native play and record.

The following table lists the DSP files that must be loaded on the AG and CG boards:

Encoding type

AG DSP file

CG DSP file

ADI_ENCODE_ALAW

rvoice.m54 or

rvoice_vad.m54

rvoice.f54 or

rvoice_vad.f54

ADI_ENCODE_G723_5

 

g723.f54

ADI_ENCODE_G723_6

 

g723.f54

ADI_ENCODE_G726

g726.m54

g726.f54

ADI_ENCODE_G726_16

 

 

ADI_ENCODE_G726_24

 

 

ADI_ENCODE_G726_32

 

 

ADI_ENCODE_G726_40

 

 

ADI_ENCODE_G729A

 

g729.f54

ADI_ENCODE_GSM

gsm_ms.m54

gsm_ms.f54

ADI_ENCODE_IMA_24

ima.m54

ima.f54

ADI_ENCODE_IMA_32

ima.m54

ima.f54

ADI_ENCODE_NMS_16

voice.m54

voice.f54

ADI_ENCODE_NMS_24

voice.m54

voice.f54

ADI_ENCODE_NMS_32

voice.m54

voice.f54

ADI_ENCODE_NMS_64

voice.m54

voice.f54

ADI_ENCODE_MULAW

rvoice.m54 or

rvoice_vad.m54

rvoice.f54 or

rvoice_vad.f54

ADI_ENCODE_OKI_24

oki.m54

oki.f54

ADI_ENCODE_OKI_32

oki.m54

oki.f54

ADI_ENCODE_PCM8M16

rvoice.m54 or

rvoice_vad.m54

rvoice.f54 or

rvoice_vad.f54

ADI_ENCODE_PCM11M8

wave.m54

wave.f54

ADI_ENCODE_PCM11M16

wave.m54

wave.f54

ADI_ENCODE_VOX_32

 

 

Refer to DSP file summary for DSP file descriptions. Refer to the board installation and developer's manual for MIPS usage.

See also

adiModifyPlayGain, adiModifyPlaySpeed, adiPlayFromMemory, adiSetNativeInfo, adiStartPlaying, adiStopPlaying,

Example

Refer to the playrec demonstration program.