4.5 Voice Play Functions

 (Page 6 of 8 in this chapter)
This section provides a detailed description of AG Access voice play functions used in play initiation, termination and data transfer. Functions related to playing voice are listed below:

Function

 Descriptions

adiStartPlaying

 Initiates playing in callback transfer mode.

adiPlayFromMemory

 Initiates playing in single transfer mode.

adiPlayAsync

 Initiates playing in asynchronous transfer mode.

adiSubmitPlayBuffer

 Submits play buffer (asynchronous).

adiStopPlaying

 Terminates playing.

adiModifyPlayGain

 Adjusts the playing volume.

adiModifyPlaySpeed

 Adjusts the playing speed.

adiGetPlayStatus

 Returns information about playing.

The general procedure for playing involves the following steps:

  1. The application invokes a function to initiate playing.

  2. AG Access prompts the application for data.

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

  4. AG Access terminates play upon delivering an ADIEVN_PLAY_DONE event (see Section 4.5.2, Play Termination, for termination reasons).

Steps 2 and 3 above are typically performed multiple times.

The ADIPLAY parameter structure modifies the play function.

4.5.1 Play Initiation

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

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

4.5.2 Play Termination

The play function on a port terminates when AG Access delivers an ADIEVN_PLAY_DONE event, regardless of the transfer method selected. This event is generated under the following conditions:

The event value field contains the termination reason.

4.5.3 Data Transfer Via Callback

In callback mode, AG Access allocates a speech buffer and invokes an application function to retrieve voice data into it. You specify the callback function when play is initiated via adiStartPlaying. The callback sequence of events is as follows:

  1. The application initiates playing in callback mode by invoking adiStartPlaying.

  2. AG Access invokes the application's callback routine when a play buffer needs to be filled with voice data.

  3. The application's callback fills the buffer before returning.

  4. When playing completes, AG Access generates an ADIEVN_PLAY_DONE event.

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

When AG Access requires data, it invokes the callback routine passing 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 AG Access the amount of data read and a flag indicating whether or not to terminate the playing session after the buffer is played.

Note: AG Access invokes the callback from within the adiStartPlaying context to retrieve the initial play buffer (i.e., before adiStartPlaying returns). The start- up sequence is as follows:

  1. The application invokes adiStartPlaying.

  2. adiStartPlaying invokes the callback to retrieve the initial data. The callback fills the buffer and returns.

  3. adiStartPlaying sends the play command to the AG board and returns.

The application is not allowed to invoke AG Access functions while the callback is executing.

The demonstration program playrec illustrates playing with callbacks.

4.5.4 Data Transfer Via Asynchronous Mode

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



: Audio Play Timing Diagram

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

  1. The application initiates playing in asynchronous mode by invoking adiPlayAsync.

  2. AG Access 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 playing completes, AG Access generates an ADIEVN_PLAY_DONE event.

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

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



: Audio Play State Diagram

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

Idle: The play function is not active.

Active: When the application invokes adiPlayAsync, AG Access sends the initial buffer to the AG board and transits to the Active state. The play state remains Active until one of the terminating conditions described in Section 4.5.2, Play Termination, occurs.

AG Access sends events and the application submits buffers while in this state as described below.

  1. AG Access generates an ADIEVN_PLAY_BUFFER_REQ when more play data is needed.

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

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

Stopping: The application can abort the play function by invoking adiStopPlaying. AG Access will not accept any more commands from the application while in the Stopping state. Any play functions invoked by the application result in AG Access returning an ADIERR_INVALID_SEQUENCE error code. When the ADIEVN_PLAY_DONE event is delivered to the application, the play state returns to Idle.

4.5.5 Gain and Speed Control

The playing volume can be adjusted at play start-up by changing the default value of the play gain parameter, and 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 -54db to +24db.

The playing speed may also be adjusted for some encodings. For AG Access Release 1.0, speed control is available for the NMS ADPCM encodings (ADI_ENCODE_NMS_xx) and the OKI ADPCM encodings (ADI_ENCODE_OKI_xx).

To enable speed up, increase the maxspeed play parameter 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. The playing speed may also be adjusted at any time while the play function is active by calling adiModifyPlaySpeed.

To use speed-up with NMS ADPCM, replace voice.dsp in the ag.cfg file with vox.dsp and voxr.dsp.

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, see Appendix B of your AG Access Installation Guide.

(Page 6 of 8 in this chapter)

Copyright 1996 Natural MicroSystems, Inc. All Rights Reserved.