(Page 6 of 8 in this chapter)

6.5 Using the Voice Play Functions

This section provides a detailed description of AG Access voice play functions that initiate a play operation, terminate a play operation and transfer data.

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 the play operation upon delivering an ADIEVN_PLAY_DONE event (see Section 6.5.3, for termination reasons that may be included as part of the event).
    




Steps 2 and 3 above are typically performed multiple times.



Choose the appropriate function calls for your application:


  





 To ... 



 Use...




 Initiate a play operation in callback transfer mode



 adiStartPlaying




 Initiate a play operation in single transfer mode



 adiPlayFromMemory




 Initiate a play operation in asynchronous transfer mode



 adiPlayAsync




 Submit play buffer (asynchronous)



 adiSubmitPlayBuffer




 Terminate a play operation



 adiStopPlaying




 Adjust the playing volume



 adiModifyPlayGain




 Adjust the playing speed



 adiModifyPlaySpeed




 Return information about a play operation



 adiGetPlayStatus



















6.5.1	 Voice Play Parameters





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






6.5.2	 Initiating a Play Operation





AG Access provides three functions to initiate playing voice data. 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.






6.5.3	 Terminating a Play Operation





The play operation on a port terminates when AG Access delivers an ADIEVN_PLAY_DONE event, regardless of the transfer method selected. The event value field contains the termination reason, which is one of the following.






6.5.4	 Playing Voice Data in Callback Mode





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



When AG Access requires data, it invokes the callback function, passing it a buffer to fill and the buffer size. The application's callback function 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 play operation after the buffer is played.



In general, playing voice data using callback mode follows these steps:


    


  1. The application invokes adiStartPlaying.
    

    
Note:  AG Access invokes the callback function from within the adiStartPlaying context to retrieve the initial buffer (i.e., before adiStartPlaying returns). 


  2. AG Access invokes the application's callback function when a 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, AG Access 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 AG Access functions while the callback function is executing.



The demonstration program playrec illustrates a play operation using callback mode.






6.5.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 AG Access. These exchanges are depicted in the following diagram:


 



Figure 18.	 Voice Play Sequence




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


    


  1. The application invokes adiPlayAsync.
    

    

  2. AG Access sends an ADIEVN_PLAY_BUFFER_REQ event when a buffer is required.
    

    

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

    

  4. When the play operation completes, AG Access generates an ADIEVN_PLAY_DONE event.
    

    
Steps 2 and 3 are repeated until the ADIEVN_PLAY_DONE event is given to the application.



Figure 19 is a state diagram depicting the complete life-cycle for a play operation in asynchronous transfer mode.


 



Figure 19.	 Voice Play State




The three states for asynchronous play transfer illustrated in Figure 19 are:




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

    

    • 

    

    6.5.6	 Controlling Gain During a Play Operation
    

    


    The audio 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 operation 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.
    

    

    

    6.5.7	 Controlling Speed During a Play Operation
    

    


    To modify the speed at which the voice data is played, call adiModifyPlaySpeed during a currently active play operation. You can modify the playing speed for voice data that uses any of the following encodings: 
    

    

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


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


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


    When a play operation is started with a higher value of maxspeed, the necessary DSP resources are allocated to support increased speed. You can start a play operation with a fast speed (up to maxspeed) by changing the value of the speed parameter in the function call.
    

Note:  Starting a play operation with maxspeed greater than 100 requires additional DSP resources beyond those required for playing at normal speed. To determine whether your AG board(s) and configuration can support speed-up, see the AG Runtime Configuration and Developer's Manual.

    

    


    
 
    (Page 6 of 8 in this chapter)
    


    




    
tech_support@nmss.com

    

Copyright © 1997, Natural MicroSystems, Inc.   All rights
reserved.