Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package sdl.audio

Java bindings for SDL audio subsystem.

See:
          Description

Interface Summary
AudioCallBack Consumes handles to audio files and controls how they are mixed and played.
 

Class Summary
AudioData Wrapper around the native buffer containing the chuncks of audio data read from audio files.
AudioPlay Wrapper around the sound to be played.
SDLAudio SDLAudio is the primary binding for the SDL Audio subsystem.
SDLAudioCvt  
SDLAudioSpec Format of the SDL audio stream.
 

Package sdl.audio Description

Java bindings for SDL audio subsystem.

About the SDL Audio Subsystem

Excerpt from SDL intro, "What can it do", Audio section
Set audio playback of 8-bit and 16-bit audio, mono or stereo, with optional conversion if the format is not supported by the hardware. Audio runs independently in a separate thread, filled via a user callback mechanism. Designed for custom software audio mixers, but the example archive contains a complete audio/music output library.

JSDL core audio classes

There are three main classes that control the playback of audio over the audio device. The relationship between these three audio classes is as follows.

Using SDLAudio

In a typical application, the user instantiates a SDLAudio object and registers a callback with it. An SDLAudioCallback is an interruptable piece of code does the actual management of the individual audio samples. In JSDL, callbacks are implemented as AudioCallBack objects which contain this code in the method feedMe(). Users always need to have a callback method written which mixes their audio data and puts it in the audio stream

Step 1. Instantiation and CallBack registration 

 	SDLAudio audio = new SDLAudio();
 	audio.registerAudioCallBack(aCallback);

Step 2. Opening the audio device
Next the user will define the type of audio to be played on the audio device, and open the device. 

       SDLAudioSpec spec = new SDLAudioSpec(
       		44100,(short)SDLAudio.AUDIO_S16,
       		(byte)2,(byte)0,(short)4096,0);
       audio.setDesiredAudioSpec(spec);
       audio.openDevice();

Step 3. Optional initialization stuff
Now we will do some initialization stuff if we want. Here, the callback is loading and audio file. 

  	// code in AudioCallBack object's (aCallBack) initialization part 
       AudioPlay playable1 = audio.loadAndConvertSDLAudio("song1.wav");

Step 4. Start ("unpause") the audio playblack
Once the extra initialization stuff is finished, we allow the callback to play the audio stream by "un-pausing" the audio (ie. starting the audio). The audio won't actually start playing until the user calls pauseAudio(false), allowing him to perform other audio initialization as needed before his callback function is run. After the user is done using the sound output, he should close it with the closeAudio() method. 

       audio.pauseAudio(false); //start Sound

At this point the user may choose to sleep and allow the AudioCallBack thread to play the streams

Understanding SDL playback - an Analogy

To better clarify playback using the SDL audio subsystem, we will reuse the following analogy.

First of all, it is important to understand the difference between the audio stream going to the audio device and the data stream read from audio files.

SDL abstractions River Analogy
Playing an audio stream on an audio device. Controlling the stream of bytes pumped into the audio device is the job of SDLAudio. There is ONE stream per audio device. Audio Stream = A river of flowing water.
Audio Device = a cave that the river flows into. Playing the stream is letting the river flow into the cave.
Playing (Mixing) files into this stream. Playing audio files involves extracting chuncks of audio data and converting time to an appropriate format. These converted data chuncks then need to be mixed into the current audio stream. This job is supervised by the callback. Sound files = several individual boats placed on the flowing river (audio stream). The river will eventually carry them to the cave.
AudioPlayBack = a third party supervisor. The river traffic controller that stands by and make sure the boats sail or stop/dock as needed. Playing files is setting the boats afloat on the river current.

See Also:
AudioCallBack, AudioPlay, SDLAudio, sdl.test.TestAudio
Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES