# adiPlayAsync

Initiates a voice play operation with asynchronous
buffer submission.

#### Supported board types

- AG

- CG

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