adiStartRecording

Starts a recording operation using a callback routine to deliver data. This function is not supported when Natural Access is running in client/server mode.

Supported board types

Prototype

DWORD adiStartRecording ( CTAHD ctahd, unsigned encoding, unsigned maxtime, ADIRECORD_ACCESS access, void *userarg, 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.
maxtime	Maximum recording time (in milliseconds). Use zero for no time limit. When voice activity detection is enabled, maxtime is the maximum duration of speech recording, excluding silences.
access	Pointer to a function to receive recorded data. See the prototype in the Details section.
userarg	An arbitrary pointer, the value of which is passed to the callback function (access) on every invocation.
parms	Pointer to record parameters according to the following structure (NULL uses default values): typedef struct { DWORD size; /* size of this structure / DWORD DTMFabort; / abort on DTMF / 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 (ms); / / use 0 to deactivate. / INT32 silenceampl; / qualif level for silence (dBm) / DWORD silencedeglitch; / deglitch while qualifying silence(ms) / /-[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) / DWORD AGCattacktime; / attack time (ms) / DWORD AGCdecaytime; / decay time (ms) */ } ADI_RECORD_PARMS; Refer to ADI_RECORD_PARMS for field descriptions.

Return values

Return value	Description
SUCCESS
ADIERR_INVALID_CALL_STATE	Function not valid in the current call state.
CTAERR_BAD_ARGUMENT	Invalid encoding selected or NULL buffer pointer passed.
CTAERR_BAD_SIZE	size is less than one frame.
CTAERR_FUNCTION_ACTIVE	Record is already active or the energy detector is active.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not valid in the current port state.
CTAERR_NOT_IMPLEMENTED	Function not implemented.
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_DONE

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 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 about 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 adiStartRecording to start a recording operation. adiStartRecording uses a callback routine (access) to deliver data. The ADI service allocates buffers and initiates recording. When a buffer fills with voice data, the ADI service invokes access, passing it the buffer address and size. The application must copy the buffer to a storage medium before returning from access.

access is invoked from ctaWaitEvent. The prototype for the access function is:

int NMSSTDCALL access ( void *userarg, void *buffer, unsigned size )

where:

Argument	Description
userarg	Pointer to value previously passed in adiStartRecording.
buffer	Pointer to memory allocated by the ADI service.
size	Size (bytes) of valid data in the buffer.

If the application's access returns a value other than SUCCESS, the ADI service terminates the record operation and generates ADIEVN_RECORD_DONE with a value field of ADIERR_PLAYREC_ACCESS.

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. Refer to ADI_RECORD_PARMS for field descriptions.

Example

The following code fragment records into the file test.vce using adiStartRecording:

int NMSSTDCALL writeAccess(
    void     *userarg,
    void     *buffer,
    unsigned size )
{
    FILE *fp = (FILE *)userarg;

    fwrite( buffer, 1, size, fp );
    if ( ferror( fp ) )
       return -1;
    return SUCCESS;
}

int myRecordFile( CTAHD ctahd, unsigned encoding)
{
    CTA_EVENT event;
    FILE *fp;

    /* note: binary open */
    if( (fp = fopen( "test.vce", "wb" )) == NULL )
       return MYFAILURE;

    if( adiStartRecording( ctahd, encoding, 0,
                           writeAccess, fp, NULL ) != SUCCESS )
        return MYFAILURE;

    do
    {
       myGetEvent( &event ); /* see ctaWaitEvent example */
    } while( event.id != ADIEVN_RECORD_DONE );

    fclose( fp );

    if( event.value == CTA_REASON_RELEASED )
        return MYDISCONNECT; /* call has been terminated */
    else if( CTA_IS_ERROR( event.value ) )
        return MYFAILURE;     /* API error                */
    else
        return SUCCESS;       /* stopped normally         */
}