(Page 1 of 1 in this chapter) Version

Chapter 3

Playing and Recording

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.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 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)
QX boards support the following encoding formats: NMS ADPCM 16, 24, 32 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

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

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 (e.g., 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.

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.

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

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.

	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

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: The application invokes a function to initiate playing. The ADI service prompts the application for data. 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). 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.

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

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.

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.

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.

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

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 (e.g., 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:

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).
The ADI service invokes the application's callback function when a play buffer needs to be filled with voice data.

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.

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:

The application invokes adiPlayAsync.

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

The application invokes adiSubmitPlayBuffer in response to the ADIEVN_PLAY_BUFFER_REQ event.

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:

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

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

If you want to modify the speed at which the voice data is played, call adiModifyPlaySpeed during a currently active play. The playing speed may also be adjusted for some encodings. 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

ADI_ENCODE_IMA_24

ADI_ENCODE_IMA_32
adiModifyPlaySpeed does not currently support the following boards:

AG 2000

AG 4000

QX 2000
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, replace voice.dsp in the ag.cfg file with voxp.dsp and voxr.dsp.
To enable speed up, 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. Slowdown is only supported to return a speedup message to normal speed. 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.

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.

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

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.

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.

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.

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.

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`

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 (e.g., a disk) and returns.

3.5.5 Data Transfer Using Asynchronous Mode

In asynchronous mode, the application transfers voice data from the AG or QX 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:

The application initiates recording in asynchronous mode by invoking adiRecordAsync.

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

The application submits the buffer by invoking adiSubmitRecordBuffer.

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.

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.

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
AG board or QX board. The AG board or QX board responds with an ADIEVN_RECORD_STARTED event at which time, the AG 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.

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 (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 will most likely be exhausted.
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 will most likely 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 and AG 4000 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 AG 2000 and AG 4000 boards occurs at a rate faster than 10 ms. Data processing delays on the AG 2000 and AG 4000 boards are less than or equal to the data processing delays on other AG boards.

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com