Sampled Sound Playback

Representing Sound
The Audio Library supports playback of both uncompressed and ADPCM compressed, 16-bit audio. An audio waveform is represented with the Sound object via the ALSound structure. The ALSound structure contains entries for the Envelope, Pan, and Volume, along with a pointer to the ALWaveTable structure (which contains the audio).

Collections of sounds can be stored in an ALBankFile structure. The format of this structure is described in Section 19, “Audio File Formats”. The tools available to create Bank Files for inclusion in the ROM are described in Section 18, “Audio Tools."

Note: Currently, the only supported sample formats are single-channel, ADPCM compressed and 16-bit uncompressed.

Playing Sound
The Sound Player is the mechanism by which the Audio Library plays back individual sounds, such as isolated sound effects. It is responsible for allocating the resources needed to play a sound and for controlling the performance of the sound data for the application. There are certain steps you must take for your game to play a sound. At a minimum, you must:

1. Create and initialize the basic resources described in the section Generating Audio Output.

2. Instantiate the Sound Player with alSndpNew(). The Sound Player created also signs in as a client to the Synthesis Driver.

3. Copy the sound bank’s .ctl file into RAM, and initialize it with a call to alBnkfNew.

4. Allocate a sound with a call to alSndpAllocate().

5. Set the Sound Player’s target sound to reference your sound with alSndpSetSound().

6. Play the sound with alSndpPlay().

7. Stop the sound when you are finished with alSndpStop(). Note that if the sound is not looped, the sound player will take care of stopping the sound when it is finished playing. However, you can stop the sound at any time during playback with this call.

When the sound is no longer needed, the resources in the Sound Player can be freed with a call to alSndpDeallocate(). If the Sound Player itself is no longer required, it can be removed from the Synthesis Driver client list with alSndpDelete().

The Sound Player can play both looped and unlooped sounds. When playing a sound, the Sound Player steps through the Envelope states Attack, Decay, and Release. Envelope parameters are defined in the ALSound structure. The duration of the sound is determined by the sum of the Attack time, Decay time, and Release time, or the length of the wave table (whichever is shorter), scaled by the pitch.

For looped sounds, the duration is always determined by the Envelope parameters and the pitch. If the Envelope Decay time is set to -1, the sound will continue playing (that is, it will never enter the Release phase) until it is stopped by the application with a call to alSndpStop(). Envelope times are scaled by the playback pitch so that regardless of pitch, finite-length sounds play to completion. For example, by default, a sound played an octave lower plays for twice as long as it does at unity pitch. Loop points for sounds are embedded in the ALWaveTable structure. (Loop points will be automatically extracted from the .aiff file when using the file conversion tools provided.)

Various parameters that affect the playback of a sound can be set before and during playback. When a sound is allocated to a Sound Player, an ID is returned that uniquely identifies that sound. Parameters for a particular sound are set by first setting the target sound with a call to alSndpSetSound(), and then making a subsequent call to set a parameter for the target sound. Available calls are detailed in Table 1, below.

Note: Each sound allocated to a Sound Player has a unique ID and private parameter values and play state. To play the same sound simultaneously, possibly with different parameter settings, it must be allocated multiple times to the Sound Player.

A summary of Sound Player functions is given below. Details can be found in the reference (man) pages.

Table 1 Sound Player Functions

Function | Description
alSndpNew | Creates a new Sound Player.
alSndpDelete | Removes a Sound Player from the Synthesis Driver’s client list.
alSndpAllocate | Allocate a sound to a sound player.
alSndpDeallocate | Deallocate a sound from the sound player.
alSndpSetSound | Sets the Sound Player’s current sound.
alSndpGetSound | Returns the Sound Player’s current sound.
alSndpPlay | Plays the Sound Player’s current sound.
alSndpPlayAt | Plays a sound at some specified time in the future.
alSndpStop | Stops the current sound from playing.
alSndpGetStates | Gets the current state (stopped or playing) of the current sound.
alSndpSetPitch | Sets the pitch for the current sound.
alSndpSetVol | Sets the playback volume of the current sound.
alSndpSetPan | Sets the pan position of the current sound.
alSndpSetPriority | Sets the sounds priority value.
alSndpSetFXMix | Sets the wet/dry mix of the current sound.

Copyright © 1999 Nintendo of America Inc. All Rights Reserved Nintendo and N64 are registered trademarks of Nintendo Last Updated January, 1999