# 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

- AG

- CG

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

#### See also

adiCommandRecord, adiGetRecordStatus, adiRecordAsync, adiRecordToMemory, adiSetNativeInfo, adiStopRecording

#### 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 */
}