3.1 Introduction

3.1.1 Voice Encoding Formats

3.1.2 Buffer Sizes

3.2 Data Transfer Methods

3.2.1 Single Memory Transaction

3.2.2 Asynchronous Transfer

3.2.3 Callback Transfer

3.3 DTMF Tones

3.3.1 DTMFabort Mask

3.4 Voice Play Functions

3.4.1 Voice Play Parameters

3.4.2 Initiating Play

3.4.3 Terminating Play

3.4.4 Playing Voice Data in Callback Mode

3.4.5 Playing Voice Data in Asynchronous Mode

3.4.6 Controlling Gain During Play

3.4.7 Controlling Speed During Play

3.5 Voice Record Functions

3.5.1 Voice Record Parameters

3.5.2 Initiating Record

3.5.3 Terminating Record

3.5.4 Data Transfer Using Callback Mode

3.5.5 Data Transfer Using Asynchronous Mode

3.5.6 Recording with Automatic Gain Control

3.6 System Restrictions

3.6.1 Delays in Data Processing (AG Boards)

3.7 Simultaneous Play and Record

Configuration File Changes for agmon Users

Configuration File Changes for OAM Users

Considerations for Both agmon and OAM Users

3.1 Introduction

The ADI service provides device level playing and recording functions which are used by the Voice Message service. The most convenient way to program playing and recording applications is to use the Voice Message service functions since it provides disk management with the playing and recording functionality. To use the Voice Message service with the ADI service playing and recording functions, open both services on the same CTA context.

When using the Voice Message service, you do not call the ADI playing and recording functions directly. The Voice Message service will call the functions when needed.

For more information about the Voice Message service, refer to the Voice Message Service Developer's Reference Manual.

If you want to create an application using your own disk management functions, you may call the ADI functions directly.

When designing voice applications with the ADI service playing and recording functions, there are two primary decisions that must be made:

• Which encoding format to use, and

• Which data transfer method to use for exchanging data between the host and the board.

3.1.1 Voice Encoding Formats

When recording or playing speech files, you must select an encoding format. The primary issue to consider when selecting a format is the compression ratio vs. fidelity. More aggressive compression requires less disk space and reduces host-to-board loading.

AG and CG boards support the following encoding formats:

• NMS ADPCM

• G.726-compliant ADPCM

• OKI ADPCM (6 and 8 kHz)

• Mu-law and A-law PCM

• 8-bit and 16-bit linear PCM at 11 kHz

• 16-bit linear PCM at 8 kHz

• IMA ADPCM (6 and 8 kHz)

• Microsoft GSM (Full Rate)

QX boards support the following encoding formats:

• NMS ADPCM 16, 24, 32 Kbps and PCM Framed 64 kbps

• G.726 16, 24, 32, and 40 Kbps

• Mu-law and A-law PCM

• 8-bit and 16-bit linear PCM at 11 kHz

• 16-bit linear PCM at 8 kHz

• VOX ADPCM 32 Kbps

Each encoding format has a minimum data block size, called a frame. Frames vary in size and duration depending upon the encoding format. For Natural MicroSystems' AG boards, a frame corresponds to 10 or 20 milliseconds of speech, depending on the encoding format.

Note: Refer to the ADI Service Function Reference Manual for a list of DSP files that are required for each encoding format.

The encodings refer to the data going to and from the host, typically stored in a voice file. Except for ADI_ENCODE_NMS_64, this host encoding is independent of the line encoding, which is always either mu-law or A-law, depending on how the board is configured when it is initialized.

Note: The Voice Message service has equivalent encoding formats which begin with VCE_.

The encoding formats are:

Encoding Format	Description	Sample Size (bits)	Sample Rate (Hz)	Frame Size (Bytes)	Frame Time (ms)	Data Rate (Bytes /sec)
ADI_ENCODE_NMS_16	NMS ADPCM 16 kbit/s	2	8000	42	20	2100
ADI_ENCODE_NMS_24	NMS ADPCM 24 kbit/s	3	8000	62	20	3100
ADI_ENCODE_NMS_32	NMS ADPCM 32 kbit/s	4	8000	82	20	4100
ADI_ENCODE_NMS_64	Framed PCM 64 kbit/s	8	8000	162	20	8100
ADI_ENCODE_MULAW	mu-law 64 kbit/s	8	8000	80	10	8000
ADI_ENCODE_ALAW	A-law 64 kbit/s	8	8000	80	10	8000
ADI_ENCODE_PCM8M16	PCM 8k mono 16 bit (WAVE)	16	8000	160	10	16000
ADI_ENCODE_OKI_24	OKI ADPCM 24 kbit/s	4	6000	30	10	3000
ADI_ENCODE_OKI_32	OKI ADPCM 32 kbit/s	4	8000	40	10	4000
ADI_ENCODE_PCM11M8	PCM 11 kHz 8 bit mono (WAVE)	8	11000	110	10	11000
ADI_ENCODE_PCM11M16	PCM 11kHz 16 bit mono (WAVE)	16	11000	220	10	22000
ADI_ENCODE_G726	G.726 ADPCM 32 kbit/s	4	8000	40	10	4000
ADI_ENCODE_G726_16	G.726 ADPCM 16 kbit/s	2	8000	Variable	Variable	2000
ADI_ENCODE_G726_24	G.726 ADPCM 24 kbit/s	3	8000	Variable	Variable	3000
ADI_ENCODE_G726_32	G.726 ADPCM 32 kbit/s	4	8000	Variable	Variable	4000
ADI_ENCODE_G726_40	G.726 ADPCM 40 kbit/s	5	8000	Variable	Variable	5000
ADI_ENCODE_IMA_24	IMA ADPCM 24 kbit/s	4	6000	36	10	3600
ADI_ENCODE_IMA_32	IMA ADPCM 32 kbit/s	4	8000	46	10	4600
ADI_ENCODE_VOX_32	VOX ADPCM 32 kbit/s	4	8000	40	10	4000
ADI_ENCODE_GSM (CT Access 4.0 only)	MS-GSM 13 kbit/s	NA	8000	130	80	1625

3.1.2 Buffer Sizes

All buffers submitted to the ADI service play functions must be able to contain an integral number of frames for the selected encoding format. For example, if you select ADI_ENCODE_NMS_24, the buffer size must be a multiple of 62 bytes. Failure to submit a buffer meeting this size requirement causes the play function to terminate with CTAERR_BAD_SIZE. Other than the multiple frame size requirement, buffers submitted to the ADI service can be any size.

Each AG board has a physical buffer size which is both board and encoding dependent. If you submit a buffer larger than the physical size, the ADI service divides the buffer into physical segments and submits those segments to the AG board. To eliminate fractional buffers and to reduce the AG-to-host interactions, the optimum user buffer will be a multiple of the physical AG buffer size. This size is retrieved via adiGetEncodingInfo.

The ADI service employs a double-buffering scheme when recording and playing voice files. This means that when the AG board finishes processing a buffer, the subsequent buffer must already be allocated and submitted to the ADI service by the application.

On heavily loaded systems, the throughput requirements between the host and the AG board may cause gaps in the voice record or playback. This is called an underrun condition. Underruns are manifested as gaps in the voice data. Failure to maintain pace with the AG board can also cause underruns in the voice record or playback. Greater file compression may be necessary to eliminate the problem.

The ADI service counts the number of underruns that occur, but not their duration. Retrieve the underrun count by calling adiGetRecordStatus and adiGetPlayStatus.

Note: It is important not to submit small buffers (for example, buffers that hold less than one second of data), because small buffers can also cause underruns. The data throughput for a given encoding method can be derived from the values returned by adiGetEncodingInfo.

3.2 Data Transfer Methods

The ADI service provides three methods by which the application can transfer speech data to and from the AG board or QX board:

Method	Description
Single Memory Transaction	The application submits a single data buffer to the ADI service.
Asynchronous Transfer	The application serially submits multiple buffers by exchanging commands and events with the ADI service.
Callback Transfer	The ADI service manages the buffers and invokes an application callback function to retrieve or store data.

The functions used to initiate play or record depends upon the data transfer method selected, as shown below:

	Single Memory	Asynchronous	Callback
Play	adiPlayFromMemory	adiPlayAsync	adiStartPlaying
Record	adiRecordToMemory	adiRecordAsync	adiStartRecording

adiStartPlaying and adiStartRecording are not supported while CT Access is running in Server mode. For more information about Server mode, refer to the CT Access Developer's Reference Manual.

The following three sections describe the general mechanics for the three transfer methods. These methods are described in greater detail in Section 3.4 and
Section 3.5.

3.2.1 Single Memory Transaction

If the application invokes adiPlayFromMemory or adiRecordToMemory, it supplies a single buffer that is retained by the ADI service for the duration of the function. The ADI service divides the application buffer into AG physical segments and performs all handshaking with the board.

Note: A buffer submitted for playing can be shared by multiple instances of the play function (within the same process) but the buffer submitted for recording must be unique for each active recording instance.

When the ADI service delivers the ADIEVN_PLAY_DONE or ADIEVN_RECORD_DONE event to the application, the buffer is then available for reuse or disposal.

In summary:

• The advantage to using single memory transaction is that it is relatively simple, and minimizes application interaction.

• The disadvantage to using single memory transaction is that it consumes a large virtual address space for large voice files. An application may experience latency reading or writing large files to and from storage.

3.2.2 Asynchronous Transfer

The asynchronous transfer method gives you maximum latitude with buffer address, size, and submission. An initial buffer is submitted when the play or record function is started by calling adiPlayAsync or adiRecordAsync. The ADI service generates events whenever more voice data is required (during a play function) or when another buffer is required (during a record function). The application is responsible for submitting buffers in a timely manner via adiSubmitPlayBuffer or adiSubmitRecordBuffer.

In summary:

• The advantage to using asynchronous transfer is that the programmer can control buffer addresses and sizes, and have asynchronous access to a storage medium.

• The disadvantage to using asynchronous transfer is that it is more complicated to program.

3.2.3 Callback Transfer

The callback transfer method strikes a balance between simplicity in programming and resource consumption. The ADI service allocates the buffers and invokes an application-specified callback function whenever a buffer needs to be filled (during a play function) or when a buffer needs to be emptied (during a record function). Within the callback routine, the application synchronously accesses the storage medium before returning.

In summary:

• The advantage to using callback transfer is that it minimizes virtual memory consumption and is simple to implement.

• The disadvantage to using callback transfer is that the application cannot control the buffer addresses or sizes, and it requires synchronous access to a storage medium.

3.3 DTMF Tones

When initiating a voice function, the application can program the AG board to terminate the function when a DTMF key is depressed by the remote party. By default, the AG board terminates play and record when any DTMF key is entered. The respective parameter structure, either ADI_PLAY_PARMS or ADI_RECORD_PARMS, includes a selective DTMF abort mask specifying which DTMF keys terminate the function.

3.3.1 DTMFabort Mask

The DTMF abort mask is a 16-bit entity in which each bit corresponds to a specific key on the telephone keypad. Setting a bit in the mask causes the voice function to terminate if that particular key is entered. The DTMFabort mask corresponds to the DTMF telephone keys as shown:

	Most Significant Bit											Least Significant Bit
Bit Position	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
DTMF Key	D	C	B	A	#	*	9	8	7	6	5	4	3	2	1	0

For example, if the abort mask is set to 0x03FF, the play or record functions will terminate if any digit from 0 through 9 is entered by the remote party. The adidef.h include file contains #defines (ADI_DTMF_xxx) for each digit and for certain digit groups.

Note: The DTMFabort mask has no effect on digit collection.

3.4 Voice Play Functions

This section provides a detailed description of the ADI service functions used in play initiation, termination and data transfer.

The general procedure for playing involves the following steps:

1. The application invokes a function to initiate playing.

2. The ADI service prompts the application for data.

3. The application provides data to the ADI service and can instruct the ADI service to automatically stop playing after the buffer has played (by setting the ADI_LASTBUFFER_SUBMITTED flag).

4. The ADI service terminates play upon delivering an ADIEVN_PLAY_DONE event. Refer to Section 3.4.3 for termination reasons that may be included as part of the event.
   Steps 2 and 3 above are typically performed multiple times.

Functions related to playing voice are listed in the following table:

If you want to...	Then use...
Initiate playing in callback transfer mode	adiStartPlaying
Initiate playing in single transfer mode	adiPlayFromMemory
Initiate playing in asynchronous transfer mode	adiPlayAsync
Submit play buffer (asynchronous)	adiSubmitPlayBuffer
Terminate playing	adiStopPlaying
Adjust the playing volume	adiModifyPlayGain
Adjust the playing speed	adiModifyPlaySpeed
Return information about playing	adiGetPlayStatus

adiStartPlaying is not supported while CT Access is running in Server mode.

Note: adiModifyPlaySpeed is not supported on a QX 2000 board. If this function is called on the QX 2000 board, CTAERR_FUNCTION_NOT_AVAIL is returned.

3.4.1 Voice Play Parameters

The ADI_PLAY_PARMS structure contains the following parameters, which modify the play function as noted:

Parameter	Description
DTMFabort	Controls which DTMF tones abort play.
gain	Applies specific gain to the encoded audio.
maxspeed	Dictates the maximum speed that will be used, which determines how much DSP processing power is allocated to the play function. This parameter is ignored for encoding types for which speed modification is not supported. For more information about speed control, refer to Section 3.4.7.
speed	The initial speedup factor applied to the encoded audio data. This parameter is ignored for encoding types for which speed modification is not supported.

3.4.2 Initiating Play

The ADI service provides three functions to initiate playing speech. The function used depends upon which data transfer method is selected:

This function is used...	When the...
adiPlayFromMemory	Application submits a single memory buffer to the ADI service.
adiStartPlaying	ADI service invokes application callback when data is needed.
adiPlayAsync	ADI service generates a buffer request event when more data is needed. The application asynchronously submits play buffers in response.

adiStartPlaying is not supported while CT Access is running in Server mode.

In all three cases, the ADI service returns SUCCESS if the "start playing" command is successfully sent to the AG board.

3.4.3 Terminating Play

The play function terminates when the ADI service delivers an ADIEVN_PLAY_DONE event, regardless of the transfer method selected. The event value field contains the termination reason, as follows:

If...	Then play ends with...
The application submitted a buffer with the ADI_LASTBUFFER_SUBMITTED flag and the buffer has finished playing	CTA_REASON_FINISHED
The call was released by either party	CTA_REASON_RELEASED
A DTMF digit specified in the abort mask was entered by the remote party	CTA_REASON_DIGIT
The application aborted play by calling adiStopPlaying	CTA_REASON_STOPPED
The play was aborted by the speech recognizer	CTA_REASON_RECOGNITION

3.4.4 Playing Voice Data in Callback Mode

In callback mode, the ADI service allocates a buffer and invokes an
application-specified function to play voice data into it. You specify the callback function when play is initiated with adiStartPlaying.

When the ADI service requires data, it invokes the callback function, passing it a buffer to fill and the buffer size. The application's callback routine reads data from a storage medium (for example, a disk) into the buffer. The callback returns to the ADI service the amount of data read and a flag indicating whether or not to terminate the playing session after the buffer is played.

Playing voice data using callback mode follows these steps:

1. The application invokes adiStartPlaying.
   Note: The ADI service invokes the callback function from within the adiStartPlaying context to retrieve the initial buffer (i.e., before adiStartPlaying returns).
2. The ADI service invokes the application's callback function when a play buffer needs to be filled with voice data.

3. The application's callback function fills the buffer before returning.
   At this point, if the application indicates that this is the last buffer (uses the ADI_LASTBUFFER_SUBMITTED flag) or if a termination condition has occurred, the play operation may terminate.

4. When playing completes, the ADI service generates an ADIEVN_PLAY_DONE event.
   Steps 2 and 3 are repeated until the ADIEVN_PLAY_DONE event is given to the application.
   The application is not allowed to invoke ADI service functions while the callback is executing.

3.4.5 Playing Voice Data in Asynchronous Mode

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

Figure 13. Voice Play Sequence

In general, transferring voice data asynchronously during play follows these steps:

1. The application invokes adiPlayAsync.

2. The ADI service sends an ADIEVN_PLAY_BUFFER_REQ event when a play buffer is required.

3. The application invokes adiSubmitPlayBuffer in response to the ADIEVN_PLAY_BUFFER_REQ event.

4. When play completes, the ADI service generates an ADIEVN_PLAY_DONE event.
   Steps 2 and 3 above are repeated until the ADIEVN_PLAY_ DONE event is given to the application.

Figure 14 is a state diagram depicting the complete life-cycle for play in asynchronous transfer mode:

Figure 14. Voice Play State

The three states for asynchronous play transfer illustrated in Figure 14 are described below.

• Idle: Play is not active.

• Active: When the application invokes adiPlayAsync, the ADI service sends the initial buffer to the AG board or QX board and transits to the Active state. The play state remains Active until one of the terminating conditions described in Section 3.4.3, occurs.

The ADI service sends events and the application submits buffers while in this state as described below:

1. The ADI service generates an ADIEVN_PLAY_BUFFER_REQ when more play data is needed.

2. In response to the ADI service, the application invokes adiSubmitPlayBuffer to continue playing. The application can terminate the play function by setting the ADI_LASTBUFFER_SUBMITTED flag. This causes the ADI service to generate an ADIEVN_PLAY_DONE event when the data already submitted has been played.

The application cannot invoke adiSubmitPlayBuffer unless the ADI service has given it an ADIEVN_PLAY_BUFFER_REQ event. The ADI service returns an ADIERR_TOO_MANY_BUFFERS error code when adiSubmitPlayBuffer is invoked without first receiving a buffer request event.

• Stopping: The application can abort play by invoking adiStopPlaying. The ADI service will not accept more play commands from the application while in the Stopping state. Any play functions invoked by the application result in the ADI service returning a CTAERR_INVALID_SEQUENCE error code. When the ADIEVN_PLAY_DONE event is delivered to the application, the play state returns to Idle.

3.4.6 Controlling Gain During Play

The play volume can be adjusted at play initiation by changing the default value of the play gain parameter stored in ADI_PLAY_PARMS. Volume can also be modified at any time while the play function is active by calling adiModifyPlayGain. The default value of the gain is 0 dB (i.e., no gain). The gain may be set to any value in the range of -54 dB to +24 dB.

3.4.7 Controlling Speed During Play

The playing speed can also be adjusted for some encodings.To modify the play speed, call adiModifyPlaySpeed during a currently active play. Speed control is available for:

• ADI_ENCODE_NMS_16

• ADI_ENCODE_NMS_24

• ADI_ENCODE_NMS_32

• ADI_ENCODE_NMS_64

• ADI_ENCODE_OKI_24

• ADI_ENCODE_OKI_32

adiModifyPlaySpeed does not currently support the QX 2000 board.

If you invoke adiModifyPlaySpeed for a play operation with data in any other encoding format, the play operation continues at its original speed.

To use speed-up with NMS ADPCM for AG boards (except for AG 2000 and AG 4000/C), replace voice.dsp in the configuration file with voxp.dsp and voxr.dsp.

To enable speed control, increase the maxspeed play parameter stored in ADI_PLAY_PARMS from its default value of 100.

When play is started with a higher value of maxspeed, the necessary DSP resources are allocated to support increased speed. You can start play with a fast speed (up to maxspeed) by changing the value of the speed parameter in the function call. For AG boards, slowdown is only supported to return a speedup message to normal speed. For AG 2000, AG 4000/C, and CG 6000C, slowdown up to 50% of normal speed is supported.

Note: Starting play with maxspeed greater than 100 requires additional DSP resources beyond that required for playing at normal speed. To determine whether your AG board(s) and configuration can support speed up, refer to the AG Runtime Configuration and Developer's Manual (CT Access 3.0 users) or the OAM System User's Manual (CT Access 4.0 users).

3.5 Voice Record Functions

This section provides a detailed description of the ADI service 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:

If you want to...	Then use...
Initiate recording in callback transfer mode	adiStartRecording
Initiate recording into a single memory buffer	adiRecordToMemory
Initiate recording in asynchronous transfer mode	adiRecordAsync
Give an empty buffer to the ADI service for recording voice (asynchronous only)	adiSubmitRecordBuffer
Terminate recording	adiStopRecording
Return information about recording	adiGetRecordStatus

adiStartRecording is not supported while CT Access is running in Server mode.

3.5.1 Voice Record Parameters

The ADI_RECORD_PARMS structure contains the following parameters, which modify the record function as noted:

Parameter	Description
AGCattacktime	AGC attack time constant controls how quickly the gain is reduced for loud signals.
AGCdecaytime	AGC decay time constant controls how quickly the gain is increased for soft signals.
AGCenable	Flag that enables Automatic Gain Control (AGC). Set to 1 to enable AGC and 0 to disable it.
AGCsilenceampl	Noise threshold for AGC. Gain adjustment is suspended for signals below this level.
AGCtargetampl	Target amplitude for AGC.
beepampl	Amplitude of the record beep tone.
beepfreq	Frequency of the record beep tone (0 disables the beep).
beeptime	Duration of the record beep tone (0 disables the beep).
DTMFabort	Controls which DTMFs abort recording.
gain	Gain applied to the signal before it is encoded. If AGC is enabled, this is the initial gain when record is started.
novoicetime	Maximum length of silence at the beginning of a recording before record will be stopped with a reason of CTA_REASON_NO_VOICE. 0 disables this timer.
silenceampl	Maximum signal level that is considered to be silence.
silencedeglitch	Maximum non-silent interval that is ignored by the silence detector. Any sounds that last longer than this will reset the silence detector.
silencetime	Maximum length of silence after audio energy has been detected before recording is stopped with a reason of CTA_REASON_VOICE_END. 0 disables this timer.

3.5.2 Initiating Record

The ADI service provides three functions to initiate voice record. The function used depends upon which data transfer method is selected:

This function is used...	When...
adiRecordToMemory	The application submits a single buffer to the ADI service.
adiStartRecording	The ADI service invokes an application-specified callback function when a buffer is full. The application must store the data before returning.
adiRecordAsync	The ADI service generates a buffer full event when each buffer is full. The application asynchronously stores the data and submits empty buffers in response.

adiStartRecording is not supported while CT Access is running in Server mode.

In all three cases, the ADI service returns SUCCESS if the recording function successfully initiated.

3.5.3 Terminating Record

The record function terminates when the ADI service delivers an ADIEVN_RECORD_DONE event, regardless of which transfer method has been used. The event value field contains one of the following termination reasons:

If...	Then play ends with...
The call was released by either party	CTA_REASON_RELEASED
A DTMF digit specified in the abort mask was entered by the remote party	CTA_REASON_DIGIT
The application aborted recording via adiStopRecording	CTA_REASON_STOPPED
The remote party never spoke (see Figure 15)	CTA_REASON_NO_VOICE
The remote party stopped speaking for the "voice end" time period (see Figure 16)	CTA_REASON_VOICE_END
The remote party spoke longer than the maximum duration (see Figure 17)	CTA_REASON_TIMEOUT

Figure 15. Record Termination - No Voice

Figure 16. Record Termination - Voice End

Figure 17. Record Termination - Timeout

There are three timer parameters that terminate the record function:

Parameter	Description
novoicetime	Specifies the time, in milliseconds, that the remote party has after the beep-sync prompt in which to start speaking. novoicetime is stored in the ADI_RECORD_PARMS structure.
silencetime	Specifies the maximum silence duration, in milliseconds, after the remote caller has stopped speaking. silencetime is stored in the ADI_RECORD_PARMS structure.
maxtime	Specifies the record function time limit, in milliseconds. The remote caller has maxtime milliseconds after the beep in which to completely record a message. maxtime is a function argument specified when initiating the record function.

3.5.4 Data Transfer Using Callback Mode

In record callback mode, the ADI service allocates two record buffers when the record function initiates. The ADI service invokes the application-specified callback routine whenever a record buffer is filled. You specify the callback function when record is initiated via adiStartRecording.

When the ADI service fills a record buffer, it invokes the record callback function, and passes it the buffer pointer and the buffer size. The callback routine writes the data to a storage medium (for example, a disk) and returns.

3.5.5 Data Transfer Using Asynchronous Mode

In asynchronous mode, the application transfers voice data from the board to the host by cooperatively exchanging commands and events with the ADI service. These exchanges are depicted in Figure 18:

Figure 18. Voice Record Sequence

In general, transferring voice data during record follows these steps:

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

2. The ADI service generates an ADIEVN_RECORD_STARTED event to inform the application to submit the second buffer.

3. The application submits the buffer by invoking adiSubmitRecordBuffer.

4. The ADI service sends an ADIEVN_RECORD_BUFFER_FULL event to the application when a record buffer has been filled. The buffer address and size are provided.

5. If the value field in the ADIEVN_RECORD_BUFFER_FULL event has the ADI_RECORD_BUFFER_REQ bit set, the ADI service needs another record buffer. In response, the application invokes adiSubmitRecordBuffer.

6. When recording completes, the ADI service generates an ADIEVN_RECORD_DONE event.

Steps 2, 3, and 4 are repeated until the ADIEVN_RECORD_DONE event is delivered to the application.

Figure 19 is a state diagram depicting the complete life-cycle for record using asynchronous data transfer:

Figure 19. Record States

The four states for asynchronous record transfer illustrated in Figure 19 are:

• Idle: The function is not active.

• Wait Record Started: The record function enters this state when the application invokes adiRecordAsync. The ADI service sends the initial buffer to the board. The board responds with an ADIEVN_RECORD_STARTED event at which time, the board is actively recording. 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 3.5.3, occurs. The ADI service and the application exchange "buffer full" events and submit buffer commands while in this state as described below:

• The ADI service 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. adiSubmitRecordBuffer 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. The ADI service will not execute any more record functions from the application while in the Stopping state. Any record functions invoked by the application result in the ADI service returning CTAERR_INVALID_SEQUENCE error code. When the ADIEVN_RECORD_DONE event is delivered to the application, the record state returns to Idle.

3.5.6 Recording with Automatic Gain Control

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

Figure 20. Automatic Gain Control (AGC) Record Parameters

The remaining four record AGC parameters, AGCtargetampl, AGCsilenceampl, AGCattacktime, and AGCdecaytime, control the behavior of the AGC. The default values for these should be correct for most applications. Refer to the ADI Service Function Reference Manual for a description of each of the record parameters.

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

AG boards support record AGC except for the following encoding types:

• mu-law (10)

• A-law (11)

• PCM8M16 (13)
  Note: AG 2000, AG 4000/C, and CG 6000C boards support AGC for record on all encoding types.

3.6 System Restrictions

The following system restrictions should be noted regarding voice record and playback:

• Only one function can drive the output to the telephone line (an MVIP inband output stream); therefore, the following functions are mutually exclusive:

• Voice recording with beep enabled (since the record beep prompt drives the output)

• Voice play

• Tone generation

• FSK sending

If the DTMF detector is disabled, voice functions cannot terminate when digits are entered.

The following functions are typically configured to share the same group of task processors:

Call progress

Voice record

Voice play

Tone generation

MF detection

For the typical configuration, DSP capacity is allotted under the assumption that every CTA context is running no more than one of these functions at any given time. There is nothing preventing the application from concurrently executing some combinations of these functions on some CTA contexts. If, however, multiple CTA contexts concurrently execute a combination of these functions, the DSP capacity may be exhausted.

3.6.1 Delays in Data Processing (AG Boards)

Delays between initiating a command and its execution are influenced by the following factors:

• 10 ms batching - There are two (three on an AG-8 board) 10 ms delays between the line and the application that result from DSP data being batched in 10 ms blocks.
  For example, if a command is sent to the board to change the play volume, there will be a 20 ms delay (30 ms on AG-8 board) before the change appears on the line.

• Function start and stop - There is a 10-20 ms delay starting a DSP input function (record, for example) and a 20-30 ms delay to start an output function (play, for example). This is in addition to the batching delay explained above.
  For example, when play is started on an AG-8 board, 50-60 ms elapse before the data appears on the line (20-30 ms start-up delay, plus 30 ms batching delay).

• Load-related queueing delay - A heavily loaded AG board or host will not be able to process data as soon as the data is available. The AG board is designed to normally complete processing commands, events and data for all channels in each 10 ms time period. Occasionally, some processing may be delayed by 10 or 20 ms when a board is heavily loaded.

• Voice buffering - Although the DSPs process data in 10 ms blocks, it is not practical for the host to deliver the data in such small batches. Typically, play and record buffers hold 2-5 seconds of data. It is possible to use buffers as small as 100 ms with a fast and/or lightly loaded host.

• Codec and switch delays - These add up to less than .5 millisecond.
  Note: The AG 2000, AG 4000/C and CG 6000C boards are not limited to 10 ms blocks of data. These boards support DSP functions using a variety of data block sizes (a data block size can be as small as 2 ms). As a consequence, the delays in data processing depend on the data block size of the specific DSP function. In addition, command and event processing to and from the DSPs on these boards occurs at a rate faster than 10 ms. Data processing delays on these boards are less than or equal to the data processing delays on other AG boards.

3.7 Simultaneous Play and Record

This section describes how to modify the configuration file to simultaneously play and record on a port.

Configuration File Changes for agmon Users

If you are running agmon on an AG board, add the following lines of code to the relevant Board section in the ag.cfg file:

buffers=n

buffersize=5000

where n = 4 times the number of ports on your AG board. For example, an AG-2000 board contains 8 ports, so n would be 32.

Configuration File Changes for OAM Users

If you are running OAM on an AG board or a CG board, add the following lines of code to the relevant Board section in the configuration file:

Buffers[0].Num=n

Buffers[0].Size=5000

where n = 4 times the number of ports on your AG or CG board. For example, an AG 2000 board contains 8 ports, so n would be 32.

Considerations for Both agmon and OAM Users

You will also need to disable the beep when recording. If you do not, the record function will try to seize the output, causing a CTAERR_OUTPUT_ACTIVE error. To do this, set the record parameter beepfreq or beeptime to 0.

For AG Quad T/Dual T and AG Quad E/Dual E boards, running play and record on many ports is resource-intensive in terms of both MIPS and memory. It may be necessary to remove some DSP overlays from your configuration file to allow it to function correctly.

Testing has been performed on three different boards with each of two encodings for recording, three encodings for playing, and two levels of echo cancellation.

Boards:
AG-8, AG-8/80, AG-T1 (168 MIPS)

Record encodings:
ADI_ENCODE_MULAW, ADI_ENCODE_NMS_64

Play encodings:
ADI_ENCODE_MULAW, ADI_ENCODE_NMS_64, ADI_ENCODE_NMS_24

Echo cancellation:
Default echo cancellation
(adi.start.echocancel.mode = 1)
Maximum echo cancellation
(adi.start.echocancel.filterlength = 20,
adi.start.echocancel.adapttime = 100)

The results are summarized in the following table. The port counts listed are for the default/maximum echo cancellation, and the encoding schemes are abbreviated as follows:

64: ADI_ENCODE_NMS_64
24: ADI_ENCODE_NMS_24
Mu: ADI_ENCODE_MULAW

Board	Record	Play	Ports	Limiting Resource
AG-8	64	64	7/6	CMEM
		24	8/6	task processors
		Mu	7/6	CMEM
	Mu	64	7/6	CMEM
		24	8/6	task processors
		Mu	8/6	CMEM
AG-8/80	64	64	8/8	ports
		24	8/8	ports
		Mu	8/8	ports
	Mu	64	8/8	ports
		24	8/8	ports
		Mu	8/8	ports
AG-T1	64	64	26/20	task processors
		24	26/20	task processors
		Mu	26/20	task processors
	Mu	64	26/20	task processors
		24	26/20	task processors
		Mu	26/20	task processors

Note: These results were obtained with all extraneous overlays removed, and represent a best-case scenario.