4.6 Voice Record Functions

This section provides a detailed description of AG Access voice recording functions used in record initiation, termination and data transfer. The callback and asynchronous transfer methods are also explored in detail.

Functions related to recording voice are listed below:

Function	Description
adiStartRecording	Initiates recording in callback transfer mode.
adiRecordToMemory	Initiates recording into a single memory buffer.
adiRecordAsync	Initiates recording in asynchronous transfer mode.
adiSubmitRecordBuffer	Gives an empty buffer to AG Access for recording voice (asynchronous only).
adiStopRecording	Terminates recording.
adiGetRecordStatus	Returns information about recording.

The ADIRECORD parameter structure modifies the record function.

AG Access provides three functions to initiate voice recording. The function used depends upon which data transfer method is selected, as listed below.

• adiRecordToMemory: A single memory buffer.

• adiStartRecording: AG Access invokes application callback when a data buffer is full. The application must store the data before returning.

• adiRecordAsync: AG Access generates a buffer full event when a user buffer is full. The application asynchronously stores the data and submits empty buffers in response.

In all three cases, AG Access returns SUCCESS if the recording function successfully initiated.

The port's record function terminates when AG Access delivers an ADIEVN_RECORD_DONE event, regardless of which transfer method is selected. This event is generated whenever one of the following conditions occur (the event value field contains the termination reason):

• ADI_REASON_RELEASED - The call was released by either party.

• ADI_REASON_DIGIT - A DTMF digit specified in the abort mask was entered by the remote party.

• ADI_REASON_STOPPED - The application aborted recording via adiStopRecording.

• ADI_REASON_NO_VOICE - The remote party never spoke (see Figure 16).

• ADI_REASON_VOICE_END - The remote party stopped speaking for the "voice end" time period (see Figure 17).

• ADI_REASON_TIMEOUT - The remote party spoke longer than the maximum duration (see Figure 18).

  
  
  

: Record Termination - Voice End

: Record Termination - Timeout

There are three time windows that terminate the record function:

• novoicetime - The remote party has this many milliseconds after the beep- sync prompt in which to start speaking. The novoicetime is in the ADIRECORD parameter structure.

• silencetime - This timer specifies the maximum silence duration after the remote caller has stopped speaking. The silencetime is in the ADIRECORD parameter structure.

• maxtime - This is the record function time limit (milliseconds). The remote caller has maxtime milliseconds after the beep in which to completely record a message. The maxtime is a function argument specified when initiating the record function.

In record callback mode, AG Access allocates two record buffers when the record function initiates. AG Access invokes the application callback routine whenever a record buffer has filled. You specify the callback function when play is initiated via adiStartRecording.

When AG Access fills a record buffer, it invokes the record callback routine passing the buffer pointer and the buffer size. The callback writes the data to a storage medium (e.g., a disk) and returns.

The AG Access development kit contains the playrec demo which illustrates recording with callbacks.

In asynchronous mode, the application transfers voice data from the AG board to the host by cooperatively exchanging commands and events with AG Access. These exchanges are depicted in Figure 19.

In general, transferring voice data during record involves the following steps:

1. The application initiates recording in asynchronous mode by invoking adiRecordAsync.

2. AG Access generates an ADIEVN_RECORD_STARTED event as a stimulus for the application to submit the second buffer. The application submits the buffer by invoking adiSubmitRecordBuffer.

3. AG Access sends an ADIEVN_RECORD_BUFFER_FULL event to the application when a record buffer has filled. The buffer address and size are provided.

4. If the value field in the ADIEVN_RECORD_BUFFER_FULL event has the ADI_RECORD_BUFFER_REQ bit set, AG Access needs another record buffer. In response, the application invokes adiSubmitRecordBuffer.

5. When recording completes, AG Access generates an ADIEVN_RECORD_DONE event.

Steps 2, 3, and 4 above are repeated until the record done event is given to the application.

Figure 20 is a state diagram depicting the complete life-cycle for asynchronous record transfer.

The four states for asynchronous record transfer illustrated in Figure 20 are described below.

Idle: The function is not active.

Wait Record Started: The record function enters this state when the application invokes adiRecordAsync. AG Access sends the initial buffer to the AG board. The AG board responds with an ADIEVN_RECORD_STARTED event at which time, the AG board is actively playing. The application must submit the second required record buffer if the event's value field has the ADI_RECORD_BUFFER_REQ bit set.

Active: The record function enters the ACTIVE state after receiving the ADIEVN_RECORD_STARTED event. The record function remains ACTIVE until one of the terminating conditions described in Section 4.6.2, Record Termination, occurs. AG Access and the application exchange "buffer full" events and submit buffer commands while in this state as described below.

• AG Access generates an ADIEVN_RECORD_BUFFER_FULL event when a record buffer is full.

• In response, the application invokes adiSubmitRecordBuffer to continue recording.

A maximum of two user record buffers can be actively submitted at any given time. The adiSubmitRecordBuffer routine returns the error ADIERR_TOO_MANY_BUFFERS if a third buffer is submitted.

Stopping: The application can immediately abort the record function by invoking adiStopRecording. AG Access will not execute any more record functions from the application while in the Stopping state. Any record functions invoked by the application result in AG Access returning an ADIERR_INVALID_SEQUENCE error code. When the ADIEVN_RECORD_DONE event is delivered to the application, the record state returns to Idle.

Five record parameters allow control of Automatic Gain Control (AGC), as illustrated in Figure 21. By default, AGC is disabled and the record gain is determined only by the gain parameter. To enable AGC, set the parameter AGCenable to 1.

The remaining four record AGC parameters -- target level, silence level, and attack and decay times -- control the behavior of the AGC. The default values for these should be correct for most applications. See Appendix D of the AG Access Function Reference Manual for a description of each of the record parameters.

Note: when AGC is enabled, the gain parameter determines the gain applied when record begins.

Copyright 1996 Natural MicroSystems, Inc. All Rights Reserved.