adiRecordAsync

Initiates recording in asynchronous buffer mode.

Supported board types

Prototype

DWORD adiRecordAsync ( CTAHD ctahd, unsigned encoding, unsigned maxmsec, void *buffer, unsigned bufsize, ADI_RECORD_PARMS *parms)

Argument	Description
ctahd	Context handle returned by ctaCreateContext or ctaAttachContext.
encoding	Encoding type. See Voice encoding formats for a complete list.
maxmsec	Maximum duration for recording (milliseconds). When voice activity detection is enabled, maxmsec is the maximum duration of speech recording, excluding silences.
buffer	Pointer to buffer to receive recorded data.
bufsize	Number of bytes available at buffer (bufsize must be set to an exact multiple of the framesize for the selected encoding).
parms	Pointer to record parameters according to the following structure (NULL uses default values): typedef struct { WORD size; /* size of this structure / DWORD DTMFabort; / mask that specifies DTMF tones to abort; / INT32 gain; / recording gain in dB SLC parms (used if silence det);/ DWORD novoicetime; / length of initial silence to stop recording (ms);/ / use 0 to deactivate initial silence detection. / DWORD silencetime; / length of silence to stop recording after / / voice has been detected; use 0 to deactivate. / INT32 silenceampl; / qualif level for silence (dBm) / DWORD silencedeglitch; / deglitch while qualifying silence / /-[Beep for record]------------------------------/ DWORD beepfreq; / beep frequency (Hz) / INT32 beepampl; / beep amplitude (dBm) / DWORD beeptime; / beep time (ms) 0=no beep / /--[AGC parms]-----------------------------------/ DWORD AGCenable; / enable AGC; use 1 to activate / INT32 AGCtargetampl; / target AGC level (dBm) / INT32 AGCsilenceampl; / silence level (dBm) / WORD AGCattacktime; / attack time (ms) / DWORD AGCdecaytime; / decay time (ms) */ } ADI_RECORD_PARMS; Refer to ADI_RECORD_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 selected or NULL buffer pointer passed.
CTAERR_BAD_SIZE	size is less than one frame.
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	Record failed because there is another active output function.
CTAERR_RESOURCE_CONFLICT	Silence detector is in use by adiStartEnergyDetector.
CTAERR_SVR_COMM	Server communication error.

Events

Event	Description
ADIEVN_RECORD_STARTED	Generated by the ADI service after the function is started on the board. If the ADI_RECORD_BUFFER_REQ bit in the event value field is set, more buffers are needed and the application must submit another empty buffer.
ADIEVN_RECORD_BUFFER_FULL	Generated by the ADI service when a buffer is filled with recorded voice data. The event contains the following fields: buffer: Pointer to a previously submitted user buffer. size: Number of bytes recorded into buffer. value: Flags; If the ADI_RECORD_BUFFER_REQ bit is set, more buffers are needed and the application must submit another empty buffer. If the ADI_RECORD_UNDERRUN bit is set, an underrun occurred. There was no new buffer to record information when this one was completed.
ADIEVN_RECORD_DONE	Generated when the record operation completes. The event size field contains the total number of bytes recorded during the record instance lifetime. The value field contains one of the following termination reasons or error codes: CTA_REASON_DIGIT Aborted due to DTMF. CTA_REASON_NO_VOICE No voice detected. CTA_REASON_RELEASED Call terminated. CTA_REASON_STOPPED Stopped by application request. CTA_REASON_TIMEOUT Record time limit (maxmsec) reached. CTA_REASON_VOICE_END User stopped speaking. CTAERR_FUNCTION_NOT_AVAIL Required DSP file not loaded on the board. CTAERR_xxx or ADIERR_xxx Record failed.

Details

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.

For more information, see Encoding formats and DSP files. The table lists the DSP files that must be loaded on the AG and CG boards. Refer to the board installation and developer's manual for MIPS usage.

Use adiRecordAsync to initiate a voice record operation. The data is supplied to the application in a sequence of buffers. The application submits empty buffers using adiSubmitRecordBuffer for the duration of the operation. These buffers are then filled with recorded voice data and ADIEVN_RECORD_BUFFER_FULL events are returned. The application has complete latitude and responsibility for allocating, flushing, and submitting the buffers.

When the ADI service needs another buffer, it sets the ADI_RECORD_BUFFER_REQ bit in the event value field for ADIEVN_RECORD_STARTED and ADIEVN_RECORD_BUFFER_FULL. The application responds by submitting another empty buffer using adiSubmitRecordBuffer. The application submits buffers only when requested by the ADI service. The ADI service owns the buffer until either ADIEVN_RECORD_BUFFER_FULL or ADIEVEN_RECORD_DONE is delivered to the application.

The last buffer before the DONE event can be a partial buffer. The DONE event itself does not include a buffer of data. The record operation terminates when the application receives ADIEVN_RECORD_DONE.

Note: The final buffer submitted is not always returned to the application. If the application dynamically allocates buffers, it must keep track of submitted buffers to free any outstanding buffers when record is done.

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

For proper operation, each buffer must be submitted while the previous buffer is being filled. If a buffer is submitted too late, an underrun occurs and the input data is lost. You can monitor for underruns by checking the ADI_RECORD_UNDERRUN bit in the value field of ADIEVN_RECORD_BUFFER_FULL. Use adiGetRecordStatus to retrieve a count of underruns that occurred since record started.

Note: You cannot initiate a record operation while playing voice or generating tones unless you disable the record beep by setting either ADI_RECORD.beeptime or ADI_RECORD.beepfreq to 0 (zero). You cannot start a record operation if the energy detector is active unless both ADI_RECORD.novoicetime and ADI_RECORD.silencetime are 0 (zero).

For more information, refer to Recording.

Example

Refer to the playrec demonstration program.