paulscode.sound
Class SoundSystem

java.lang.Object
  paulscode.sound.SoundSystem

Direct Known Subclasses:

SoundSystemJPCT

public class SoundSystem
extends java.lang.Object

The SoundSystem class is the core class for the SoundSystem library. It is capable of interfacing with external sound library and codec library pluggins. This core class is stripped down to give it a smaller memory footprint and to make it more customizable. This library was created to provide a simple, common interface to a variety of 3rd-party sound and codec libraries, and to simplify switching between them on the fly. If no external pluggins are loaded, this core class by itself is only capable of playing MIDI files. Specific implementations (such as SoundSystemJPCT) will extend this core class. They will automatically link with popular external pluggins and provide extra methods for ease of use. There should be only one instance of this class in any program! The SoundSystem can be constructed by defining which sound library to use, or by allowing SoundSystem to perform its own library compatibility checking. See SoundSystemConfig for information about changing default settings and linking with external pluggins.

SoundSystem License:

You are free to use this library for any purpose, commercial or otherwise. You may modify this library or source code, and distribute it any way you like, provided the following conditions are met:
1) You may not falsely claim to be the author of this library or any unmodified portion of it.
2) You may not copyright this library or a modified version of it and then sue me for copyright infringement.
3) If you modify the source code, you must clearly document the changes made before redistributing the modified source code, so other users know it is not the original code.
4) You are not required to give me credit for this library in any derived work, but if you do, you must also mention my website: http://www.paulscode.com
5) I the author will not be responsible for any damages (physical, financial, or otherwise) caused by the use if this library or any part of it.
6) I the author do not guarantee, warrant, or make any representations, either expressed or implied, regarding the use of this library or any part of it.

Author: Paul Lamb
http://www.paulscode.com

Field Summary

protected java.lang.String	className Name of this class.
protected java.util.List<CommandObject>	commandQueue List of queued commands to perform.
protected CommandThread	commandThread Processes queued commands in the background.
protected SoundSystemLogger	logger Processes status messages, warnings, and error messages.
java.util.Random	randomNumberGenerator Generates random numbers.
protected Library	soundLibrary Handle to the active sound library.

Constructor Summary

SoundSystem()
Constructor: Create the sound system using the default library.

SoundSystem(java.lang.Class libraryClass)
Constructor: Create the sound system using the specified library.

Method Summary

void	activate(java.lang.String sourcename) Activates the specified source after it was culled, so it can be played again.
void	backgroundMusic(java.lang.String sourcename, java.lang.String filename, boolean toLoop) Creates a new permanant, streaming, priority source with zero attenuation.
void	backgroundMusic(java.lang.String sourcename, java.net.URL url, java.lang.String identifier, boolean toLoop) Creates a new permanant, streaming, priority source with zero attenuation.
void	changeDopplerFactor(float dopplerFactor) Changes the Doppler factor, for determining Doppler effect scale.
void	changeDopplerVelocity(float dopplerVelocity) Changes the Doppler velocity, for use in Doppler effect.
void	checkFadeVolumes() Makes sure the current volume levels of streaming sources and MIDI are correct.
void	cleanup() Ends the command thread, shuts down the sound system, and removes references to all instantiated objects.
boolean	CommandQueue(CommandObject newCommand) Queues a command.
void	cull(java.lang.String sourcename) Culls the specified source.
static java.lang.Class	currentLibrary() Returns the currently loaded library, or -1 if none.
void	dequeueSound(java.lang.String sourcename, java.lang.String filename) Removes the first occurrence of the specified filename/identifier from the specified source's list of sounds to play when previous playback ends.
protected boolean	errorCheck(boolean error, java.lang.String message, int indent) Prints the specified message if error is true.
protected void	errorMessage(java.lang.String message, int indent) Prints an error message.
void	fadeOut(java.lang.String sourcename, java.lang.String filename, long milis) Fades out the volume of whatever the specified source is currently playing, then begins playing the specified file at the source's previously assigned volume level.
void	fadeOut(java.lang.String sourcename, java.net.URL url, java.lang.String identifier, long milis) Fades out the volume of whatever the specified source is currently playing, then begins playing the specified file at the source's previously assigned volume level.
void	fadeOutIn(java.lang.String sourcename, java.lang.String filename, long milisOut, long milisIn) Fades out the volume of whatever the specified source is currently playing, then fades the volume back in playing the specified filename.
void	fadeOutIn(java.lang.String sourcename, java.net.URL url, java.lang.String identifier, long milisOut, long milisIn) Fades out the volume of whatever the specified source is currently playing, then fades the volume back in playing the specified file.
void	feedRawAudioData(java.lang.String sourcename, byte[] buffer) Feeds raw data through the specified source.
void	flush(java.lang.String sourcename) Flushes all previously queued audio data from a streaming source.
static SoundSystemException	getLastException() Returns the last SoundSystemException thrown, or null if none.
ListenerData	getListenerData() Method for obtaining information about the listener's position and orientation.
float	getMasterVolume() Returns the overall volume, affecting all sources.
float	getPitch(java.lang.String sourcename) Returns the pitch of the specified source.
float	getVolume(java.lang.String sourcename) Returns the current volume of the specified source, or zero if the specified source was not found.
protected void	importantMessage(java.lang.String message, int indent) Prints an important message.
protected void	init(java.lang.Class libraryClass) Loads the message logger, initializes the specified sound library, and starts the command thread.
static boolean	initialized() Returns false if a sound library is busy initializing.
void	interruptCommandThread() Wakes up the Command Thread to process commands.
static boolean	libraryCompatible(java.lang.Class libraryClass) Checks if the specified library type is compatible.
protected void	linkDefaultLibrariesAndCodecs() Links with any default libraries or codecs should be made in this method.
void	loadSound(byte[] data, javax.sound.sampled.AudioFormat format, java.lang.String identifier) Saves raw PCM audio data in the specified audio format, under the specified identifier.
void	loadSound(java.lang.String filename) Pre-loads a sound into memory.
void	loadSound(java.net.URL url, java.lang.String identifier) Pre-loads a sound specified by the given URL into memory.
protected void	ManageSources() This method can be overridden by extended classes to be used for source management (culling and activating sources based on established rules).
protected void	message(java.lang.String message, int indent) Prints a message.
float	millisecondsPlayed(java.lang.String sourcename) Returns the number of miliseconds since the specified source began playing.
void	moveListener(float x, float y, float z) Moves the listener relative to the current location.
boolean	newLibrary(java.lang.Class libraryClass) Switches to the specified library, loosing all sources.
void	newSource(boolean priority, java.lang.String sourcename, java.lang.String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a new non-streaming source.
void	newSource(boolean priority, java.lang.String sourcename, java.net.URL url, java.lang.String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a new non-streaming source.
void	newStreamingSource(boolean priority, java.lang.String sourcename, java.lang.String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a new streaming source.
void	newStreamingSource(boolean priority, java.lang.String sourcename, java.net.URL url, java.lang.String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a new streaming source.
void	pause(java.lang.String sourcename) Pauses the specified source.
void	play(java.lang.String sourcename) Plays the specified source.
boolean	playing() Returns true if anything is currently playing.
boolean	playing(java.lang.String sourcename) Returns true if the specified source is playing.
void	queueSound(java.lang.String sourcename, java.lang.String filename) If the specified source is a streaming source or MIDI source, this method queues up the next sound to play when the previous playback ends.
void	queueSound(java.lang.String sourcename, java.net.URL url, java.lang.String identifier) If the specified source is a streaming source or MIDI source, this method queues up the next sound to play when the previous playback ends.
java.lang.String	quickPlay(boolean priority, java.lang.String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a temporary source and plays it.
java.lang.String	quickPlay(boolean priority, java.net.URL url, java.lang.String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a temporary source and plays it.
java.lang.String	quickStream(boolean priority, java.lang.String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a temporary source and streams it.
java.lang.String	quickStream(boolean priority, java.net.URL url, java.lang.String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll) Creates a temporary source and streams it.
void	rawDataStream(javax.sound.sampled.AudioFormat audioFormat, boolean priority, java.lang.String sourcename, float x, float y, float z, int attModel, float distOrRoll) Opens a direct line for streaming audio data.
void	removeSource(java.lang.String sourcename) Removes the specified source and clears up any memory it used.
void	removeTemporarySources() Searches for and removes any temporary sources that have finished playing.
void	rewind(java.lang.String sourcename) Rewinds the specified source.
void	setAttenuation(java.lang.String sourcename, int model) Changes a source's attenuation model.
void	setDistOrRoll(java.lang.String sourcename, float dr) Changes a source's fade distance or rolloff factor.
static void	setException(SoundSystemException e) Stores a SoundSystemException which can be retreived later with the 'getLastException' method.
void	setListenerAngle(float angle) Sets the listener's angle in radians around the y-axis.
void	setListenerOrientation(float lookX, float lookY, float lookZ, float upX, float upY, float upZ) Sets the listener's orientation.
void	setListenerPosition(float x, float y, float z) Moves the listener to the specified location.
void	setListenerVelocity(float x, float y, float z) Sets the listener's velocity, for use in Doppler effect.
void	setLooping(java.lang.String sourcename, boolean lp) Changes a source to looping or non-looping.
void	setMasterVolume(float value) Sets the overall volume, affecting all sources.
void	setPitch(java.lang.String sourcename, float value) Manually sets the specified source's pitch.
void	setPosition(java.lang.String sourcename, float x, float y, float z) Move a source to the specified location.
void	setPriority(java.lang.String sourcename, boolean pri) Set a source's priority factor.
void	setTemporary(java.lang.String sourcename, boolean temporary) Sets a flag for a source indicating whether it should be used or if it should be removed after it finishes playing.
void	setVelocity(java.lang.String sourcename, float x, float y, float z) Sets the specified source's velocity, for use in Doppler effect.
void	setVolume(java.lang.String sourcename, float value) Manually sets the specified source's volume.
protected static void	snooze(long milliseconds) Sleeps for the specified number of milliseconds.
void	stop(java.lang.String sourcename) Stops the specified source.
boolean	switchLibrary(java.lang.Class libraryClass) Switches to the specified library, and preserves all sources.
void	turnListener(float angle) Turns the listener counterclockwise by "angle" radians around the y-axis, relative to the current angle.
void	unloadSound(java.lang.String filename) Removes a pre-loaded sound from memory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

protected SoundSystemLogger logger

Processes status messages, warnings, and error messages.

soundLibrary

protected Library soundLibrary

Handle to the active sound library.

commandQueue

protected java.util.List<CommandObject> commandQueue

List of queued commands to perform.

commandThread

protected CommandThread commandThread

Processes queued commands in the background.

randomNumberGenerator

public java.util.Random randomNumberGenerator

Generates random numbers.

className

protected java.lang.String className

Name of this class.

Constructor Detail

SoundSystem

public SoundSystem()

Constructor: Create the sound system using the default library. If the default library is not compatible, another library type will be loaded instead, in the order of library preference. See SoundSystemConfig for information about sound library types.

SoundSystem

public SoundSystem(java.lang.Class libraryClass)
            throws SoundSystemException

Constructor: Create the sound system using the specified library.

Parameters:

libraryClass - Library to use. See SoundSystemConfig for information about chosing a sound library.

Throws:

SoundSystemException

Method Detail

linkDefaultLibrariesAndCodecs

protected void linkDefaultLibrariesAndCodecs()

Links with any default libraries or codecs should be made in this method. This method is empty in the core SoundSystem class, and should be overriden by classes which extend SoundSystem. See SoundSystemConfig for information about linking with sound libraries and codecs.

init

protected void init(java.lang.Class libraryClass)
             throws SoundSystemException

Loads the message logger, initializes the specified sound library, and starts the command thread. Also instantiates the random number generator and the command queue.

Parameters:

libraryClass - Library to initialize. See SoundSystemConfig for information about chosing a sound library.

Throws:

SoundSystemException

cleanup

public void cleanup()

Ends the command thread, shuts down the sound system, and removes references to all instantiated objects.

interruptCommandThread

public void interruptCommandThread()

Wakes up the Command Thread to process commands. This method should be used if there is a need to call methods 'ManageSources' and 'CommandQueue' externally. In most cases, this method will not be needed, since SoundSystem automatically wakes the Command Thread every time commands are placed into either the ManageSources queue or CommandQueue to be processed.

loadSound

public void loadSound(java.lang.String filename)

Pre-loads a sound into memory. The file may either be located within the JAR or at an online location. If the file is online, filename must begin with "http://", since that is how SoundSystem recognizes URL's. If the file is located within the compiled JAR, the package in which sound files are located may be set by calling SoundSystemConfig.setSoundFilesPackage().

Parameters:

filename - Filename of the sound file to load.

loadSound

public void loadSound(java.net.URL url,
                      java.lang.String identifier)

Pre-loads a sound specified by the given URL into memory. The second parameter 'identifier' should look like a filename, and it must have the correct extension so SoundSystem knows what codec to use for the file referenced by the URL instance.

Parameters:

url - URL handle to the sound file to load.

identifier - Filename/identifier of the file referenced by the URL.

loadSound

public void loadSound(byte[] data,
                      javax.sound.sampled.AudioFormat format,
                      java.lang.String identifier)

Saves raw PCM audio data in the specified audio format, under the specified identifier. This identifier can be later used in place of 'filename' parameters to reference the sample data.

Parameters:

data - The sample data

format - Format the sample data is stored in

identifier - What to call the sample.

unloadSound

public void unloadSound(java.lang.String filename)

Removes a pre-loaded sound from memory. This is a good method to use for freeing up memory after a large sound file is no longer needed. NOTE: the source will remain in memory after calling this method as long as the sound is attached to an existing source. When calling this method, calls should also be made to method removeSource( String ) for all sources which this sound is bound to.

Parameters:

filename - Filename/identifier of the sound file to unload.

queueSound

public void queueSound(java.lang.String sourcename,
                       java.lang.String filename)

If the specified source is a streaming source or MIDI source, this method queues up the next sound to play when the previous playback ends. The file may either be located within the JAR or at an online location. If the file is online, filename must begin with "http://", since that is how SoundSystem recognizes URL paths. If the file is located within the compiled JAR, the package in which sound files are located may be set by calling SoundSystemConfig.setSoundFilesPackage(). This method has no effect on non-streaming sources.

Parameters:

sourcename - Source identifier.

filename - Name of the sound file to play next.

queueSound

public void queueSound(java.lang.String sourcename,
                       java.net.URL url,
                       java.lang.String identifier)

If the specified source is a streaming source or MIDI source, this method queues up the next sound to play when the previous playback ends. The third parameter 'identifier' should look like a filename, and it must have the correct extension so SoundSystem knows what codec to use for the file referenced by the URL instance. This method has no effect on non-streaming sources.

Parameters:

sourcename - Source identifier.

url - URL handle to the sound file to load.

identifier - Filename/identifier of the file referenced by the URL.

dequeueSound

public void dequeueSound(java.lang.String sourcename,
                         java.lang.String filename)

Removes the first occurrence of the specified filename/identifier from the specified source's list of sounds to play when previous playback ends. This method has no effect on non-streaming sources.

Parameters:

sourcename - Source identifier.

filename - Filename/identifier of the sound file to play next.

fadeOut

public void fadeOut(java.lang.String sourcename,
                    java.lang.String filename,
                    long milis)

Fades out the volume of whatever the specified source is currently playing, then begins playing the specified file at the source's previously assigned volume level. The file may either be located within the JAR or at an online location. If the file is online, filename must begin with "http://", since that is how SoundSystem recognizes URL paths. If the file is located within the compiled JAR, the package in which sound files are located may be set by calling SoundSystemConfig.setSoundFilesPackage(). If the filename parameter is null or empty, the specified source will simply fade out and stop. The miliseconds parameter must be non-negative or zero. This method will remove anything that is currently in the specified source's list of queued sounds that would have played next when the current sound finished playing. This method may only be used for streaming and MIDI sources.

Parameters:

sourcename - Name of the source to fade out.

filename - Name of a sound file to play next, or null for none.

milis - Number of miliseconds the fadeout should take.

fadeOut

public void fadeOut(java.lang.String sourcename,
                    java.net.URL url,
                    java.lang.String identifier,
                    long milis)

Fades out the volume of whatever the specified source is currently playing, then begins playing the specified file at the source's previously assigned volume level. If the url parameter is null or empty, the specified source will simply fade out and stop. The third parameter 'identifier' should look like a filename, and it must have the correct extension so SoundSystem knows what codec to use for the file referenced by the URL instance. The miliseconds parameter must be non-negative or zero. This method will remove anything that is currently in the specified source's list of queued sounds that would have played next when the current sound finished playing. This method may only be used for streaming and MIDI sources.

Parameters:

sourcename - Name of the source to fade out.

url - URL handle to the sound file to play next, or null for none.

identifier - Filename/identifier of the file referenced by the URL.

milis - Number of miliseconds the fadeout should take.

fadeOutIn

public void fadeOutIn(java.lang.String sourcename,
                      java.lang.String filename,
                      long milisOut,
                      long milisIn)

Fades out the volume of whatever the specified source is currently playing, then fades the volume back in playing the specified filename. Final volume after fade-in completes will be equal to the source's previously assigned volume level. The filename parameter may not be null or empty. The file may either be located within the JAR or at an online location. If the file is online, filename must begin with "http://", since that is how SoundSystem recognizes URL paths. If the file is located within the compiled JAR, the package in which sound files are located may be set by calling SoundSystemConfig.setSoundFilesPackage(). The miliseconds parameters must be non-negative or zero. This method will remove anything that is currently in the specified source's list of queued sounds that would have played next when the current sound finished playing. This method may only be used for streaming and MIDI sources.

Parameters:

sourcename - Name of the source to fade out/in.

filename - Name of a sound file to play next, or null for none.

milisOut - Number of miliseconds the fadeout should take.

milisIn - Number of miliseconds the fadein should take.

fadeOutIn

public void fadeOutIn(java.lang.String sourcename,
                      java.net.URL url,
                      java.lang.String identifier,
                      long milisOut,
                      long milisIn)

Fades out the volume of whatever the specified source is currently playing, then fades the volume back in playing the specified file. Final volume after fade-in completes will be equal to the source's previously assigned volume level. The url parameter may not be null or empty. The third parameter 'identifier' should look like a filename, and it must have the correct extension so SoundSystem knows what codec to use for the file referenced by the URL instance. The miliseconds parameters must be non-negative or zero. This method will remove anything that is currently in the specified source's list of queued sounds that would have played next when the current sound finished playing. This method may only be used for streaming and MIDI sources.

Parameters:

sourcename - Name of the source to fade out/in.

url - URL handle to the sound file to play next.

identifier - Filename/identifier of the file referenced by the URL.

milisOut - Number of miliseconds the fadeout should take.

milisIn - Number of miliseconds the fadein should take.

checkFadeVolumes

public void checkFadeVolumes()

Makes sure the current volume levels of streaming sources and MIDI are correct. This method is designed to help reduce the "jerky" fading behavior that happens when using some library and codec pluggins (such as LibraryJavaSound and CodecJOrbis). This method has no effect on normal "non-streaming" sources. It would normally be called somewhere in the main "game loop". IMPORTANT: To optimize frame-rates, do not call this method for every frame. It is better to just call this method at some acceptable "granularity" (play around with different granularities to find what sounds acceptable for a particular situation).

backgroundMusic

public void backgroundMusic(java.lang.String sourcename,
                            java.lang.String filename,
                            boolean toLoop)

Creates a new permanant, streaming, priority source with zero attenuation. The file may either be located within the JAR or at an online location. If the file is online, filename must begin with "http://", since that is how SoundSystem recognizes URL paths. If the file is located within the compiled JAR, the package in which sound files are located may be set by calling SoundSystemConfig.setSoundFilesPackage().

Parameters:

sourcename - A unique identifier for this source. Two sources may not use the same sourcename.

filename - Filename of the sound file to stream at this source.

toLoop - Should this source loop, or play only once.

backgroundMusic

public void backgroundMusic(java.lang.String sourcename,
                            java.net.URL url,
                            java.lang.String identifier,
                            boolean toLoop)

Creates a new permanant, streaming, priority source with zero attenuation. The third parameter 'identifier' should look like a filename, and it must have the correct extension so SoundSystem knows what codec to use for the file referenced by the URL instance.

Parameters:

sourcename - A unique identifier for this source. Two sources may not use the same sourcename.

url - URL handle to the sound file to stream at this source.

identifier - Filename/identifier of the file referenced by the URL.

toLoop - Should this source loop, or play only once.

newSource

public void newSource(boolean priority,
                      java.lang.String sourcename,
                      java.lang.String filename,
                      boolean toLoop,
                      float x,
                      float y,
                      float z,
                      int attmodel,
                      float distOrRoll)

Creates a new non-streaming source. See SoundSystemConfig for more information about Attenuation, fade distance, and rolloff factor.

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

sourcename - A unique identifier for this source. Two sources may not use the same sourcename.

filename - Filename/identifier of the sound file to play at this source.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

newSource

public void newSource(boolean priority,
                      java.lang.String sourcename,
                      java.net.URL url,
                      java.lang.String identifier,
                      boolean toLoop,
                      float x,
                      float y,
                      float z,
                      int attmodel,
                      float distOrRoll)

Creates a new non-streaming source. See SoundSystemConfig for more information about Attenuation, fade distance, and rolloff factor.

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

sourcename - A unique identifier for this source. Two sources may not use the same sourcename.

url - URL handle to the sound file to stream at this source.

identifier - Filename/identifier of the file referenced by the URL.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

newStreamingSource

public void newStreamingSource(boolean priority,
                               java.lang.String sourcename,
                               java.lang.String filename,
                               boolean toLoop,
                               float x,
                               float y,
                               float z,
                               int attmodel,
                               float distOrRoll)

Creates a new streaming source. The file may either be located within the JAR or at an online location. If the file is online, filename must begin with "http://", since that is how SoundSystem recognizes URL paths. If the file is located within the compiled JAR, the package in which sound files are located may be set by calling SoundSystemConfig.setSoundFilesPackage().

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

sourcename - A unique identifier for this source. Two sources may not use the same sourcename.

filename - The filename of the sound file to play at this source.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

newStreamingSource

public void newStreamingSource(boolean priority,
                               java.lang.String sourcename,
                               java.net.URL url,
                               java.lang.String identifier,
                               boolean toLoop,
                               float x,
                               float y,
                               float z,
                               int attmodel,
                               float distOrRoll)

Creates a new streaming source. The fourth parameter 'identifier' should look like a filename, and it must have the correct extension so SoundSystem knows what codec to use for the file referenced by the URL instance.

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

sourcename - A unique identifier for this source. Two sources may not use the same sourcename.

url - URL handle to the sound file to stream at this source.

identifier - Filename/identifier of the file referenced by the URL.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

rawDataStream

public void rawDataStream(javax.sound.sampled.AudioFormat audioFormat,
                          boolean priority,
                          java.lang.String sourcename,
                          float x,
                          float y,
                          float z,
                          int attModel,
                          float distOrRoll)

Opens a direct line for streaming audio data. This method creates a new streaming source to play the data at. The resulting streaming source can be manipulated the same as any other streaming source. Raw data can be sent to the new streaming source using the feedRawAudioData() method.

Parameters:

audioFormat - Format that the data will be in.

priority - Setting this to true will prevent other sounds from overriding this one.

sourcename - A unique identifier for this source. Two sources may not use the same sourcename.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attModel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

quickPlay

public java.lang.String quickPlay(boolean priority,
                                  java.lang.String filename,
                                  boolean toLoop,
                                  float x,
                                  float y,
                                  float z,
                                  int attmodel,
                                  float distOrRoll)

Creates a temporary source and plays it. After the source finishes playing, it is removed. Returns a randomly generated name for the new source. NOTE: to make a source created by this method permanant, call the setActive() method using the return value for sourcename.

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

filename - Filename/identifier of the sound file to play at this source.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

Returns:

The new sorce's name.

quickPlay

public java.lang.String quickPlay(boolean priority,
                                  java.net.URL url,
                                  java.lang.String identifier,
                                  boolean toLoop,
                                  float x,
                                  float y,
                                  float z,
                                  int attmodel,
                                  float distOrRoll)

Creates a temporary source and plays it. After the source finishes playing, it is removed. Returns a randomly generated name for the new source. NOTE: to make a source created by this method permanant, call the setActive() method using the return value for sourcename.

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

url - URL handle to the sound file to stream at this source.

identifier - Filename/identifier of the file referenced by the URL.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

Returns:

The new sorce's name.

quickStream

public java.lang.String quickStream(boolean priority,
                                    java.lang.String filename,
                                    boolean toLoop,
                                    float x,
                                    float y,
                                    float z,
                                    int attmodel,
                                    float distOrRoll)

Creates a temporary source and streams it. After the source finishes playing, it is removed. The file may either be located within the JAR or at an online location. If the file is online, filename must begin with "http://", since that is how SoundSystem recognizes URL paths. If the file is located within the compiled JAR, the package in which sound files are located may be set by calling SoundSystemConfig.setSoundFilesPackage(). Returns a randomly generated name for the new source. NOTE: to make a source created by this method permanant, call the setActive() method using the return value for sourcename.

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

filename - Filename of the sound file to stream at this source.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

Returns:

The new sorce's name.

quickStream

public java.lang.String quickStream(boolean priority,
                                    java.net.URL url,
                                    java.lang.String identifier,
                                    boolean toLoop,
                                    float x,
                                    float y,
                                    float z,
                                    int attmodel,
                                    float distOrRoll)

Creates a temporary source and streams it. After the source finishes playing, it is removed. The third parameter 'identifier' should look like a filename, and it must have the correct extension so SoundSystem knows what codec to use for the file referenced by the URL instance. Returns a randomly generated name for the new source. NOTE: to make a source created by this method permanant, call the setActive() method using the return value for sourcename.

Parameters:

priority - Setting this to true will prevent other sounds from overriding this one.

url - URL handle to the sound file to stream at this source.

identifier - Filename/identifier of the file referenced by the URL.

toLoop - Should this source loop, or play only once.

x - X position for this source.

y - Y position for this source.

z - Z position for this source.

attmodel - Attenuation model to use.

distOrRoll - Either the fading distance or rolloff factor, depending on the value of "attmodel".

Returns:

The new sorce's name.

setPosition

public void setPosition(java.lang.String sourcename,
                        float x,
                        float y,
                        float z)

Move a source to the specified location.

Parameters:

sourcename - Identifier for the source.

x - destination X coordinate.

y - destination Y coordinate.

z - destination Z coordinate.

setVolume

public void setVolume(java.lang.String sourcename,
                      float value)

Manually sets the specified source's volume.

Parameters:

sourcename - Source to move.

value - New volume, float value ( 0.0f - 1.0f ).

getVolume

public float getVolume(java.lang.String sourcename)

Returns the current volume of the specified source, or zero if the specified source was not found.

Parameters:

sourcename - Source to read volume from.

Returns:

Float value representing the source volume (0.0f - 1.0f).

setPitch

public void setPitch(java.lang.String sourcename,
                     float value)

Manually sets the specified source's pitch.

Parameters:

sourcename - The source's name.

value - A float value ( 0.5f - 2.0f ).

getPitch

public float getPitch(java.lang.String sourcename)

Returns the pitch of the specified source.

Parameters:

sourcename - The source's name.

Returns:

Float value representing the source pitch (0.5f - 2.0f).

setPriority

public void setPriority(java.lang.String sourcename,
                        boolean pri)

Set a source's priority factor. A priority source will not be overriden when too many sources are playing at once.

Parameters:

sourcename - Identifier for the source.

pri - Setting this to true makes this source a priority source.

setLooping

public void setLooping(java.lang.String sourcename,
                       boolean lp)

Changes a source to looping or non-looping.

Parameters:

sourcename - Identifier for the source.

lp - This source should loop.

setAttenuation

public void setAttenuation(java.lang.String sourcename,
                           int model)

Changes a source's attenuation model. See SoundSystemConfig for more information about Attenuation.

Parameters:

sourcename - Identifier for the source.

model - Attenuation model to use.

setDistOrRoll

public void setDistOrRoll(java.lang.String sourcename,
                          float dr)

Changes a source's fade distance or rolloff factor. See SoundSystemConfig for more information about fade distance and rolloff.

Parameters:

sourcename - Identifier for the source.

dr - Either the fading distance or rolloff factor, depending on the attenuation model used.

changeDopplerFactor

public void changeDopplerFactor(float dopplerFactor)

Changes the Doppler factor, for determining Doppler effect scale. See SoundSystemConfig for more information about Doppler effect.

Parameters:

dopplerFactor - New value for Doppler factor.

changeDopplerVelocity

public void changeDopplerVelocity(float dopplerVelocity)

Changes the Doppler velocity, for use in Doppler effect. See SoundSystemConfig for more information about Doppler effect.

Parameters:

dopplerVelocity - New value for Doppler velocity.

setVelocity

public void setVelocity(java.lang.String sourcename,
                        float x,
                        float y,
                        float z)

Sets the specified source's velocity, for use in Doppler effect. See SoundSystemConfig for more information about Doppler effect.

Parameters:

sourcename - The source's name.

x - Velocity along world x-axis.

y - Velocity along world y-axis.

z - Velocity along world z-axis.

setListenerVelocity

public void setListenerVelocity(float x,
                                float y,
                                float z)

Sets the listener's velocity, for use in Doppler effect. See SoundSystemConfig for more information about Doppler effect.

Parameters:

x - Velocity along world x-axis.

y - Velocity along world y-axis.

z - Velocity along world z-axis.

millisecondsPlayed

public float millisecondsPlayed(java.lang.String sourcename)

Returns the number of miliseconds since the specified source began playing.

Returns:

miliseconds, or -1 if not playing or unable to calculate

feedRawAudioData

public void feedRawAudioData(java.lang.String sourcename,
                             byte[] buffer)

Feeds raw data through the specified source. The source must be a streaming source and it can not be already associated with a file or URL to stream from. Only use this for streaming sources created with the rawDataStream() method. NOTE: Be carefull how much data you send to a source to stream. The data will be processed at playback speed, so if you queue up 1 hour worth of data, it will take 1 hour to play (not to mention hogging a ton of memory). To clear out all queued data from the source, use the flush() method. Also note: if there is a break in the data stream, you will hear clicks and studders, so ensure that the data flow is steady.

Parameters:

sourcename - Name of the streaming source to play from.

buffer - Byte buffer containing raw audio data to stream.

play

public void play(java.lang.String sourcename)

Plays the specified source.

Parameters:

sourcename - Identifier for the source.

pause

public void pause(java.lang.String sourcename)

Pauses the specified source.

Parameters:

sourcename - Identifier for the source.

stop

public void stop(java.lang.String sourcename)

Stops the specified source.

Parameters:

sourcename - Identifier for the source.

rewind

public void rewind(java.lang.String sourcename)

Rewinds the specified source.

Parameters:

sourcename - Identifier for the source.

flush

public void flush(java.lang.String sourcename)

Flushes all previously queued audio data from a streaming source.

Parameters:

sourcename - Identifier for the source.

cull

public void cull(java.lang.String sourcename)

Culls the specified source. A culled source can not be played until it has been activated again.

Parameters:

sourcename - Identifier for the source.

activate

public void activate(java.lang.String sourcename)

Activates the specified source after it was culled, so it can be played again.

Parameters:

sourcename - Identifier for the source.

setTemporary

public void setTemporary(java.lang.String sourcename,
                         boolean temporary)

Sets a flag for a source indicating whether it should be used or if it should be removed after it finishes playing. One possible use for this method is to make temporary sources that were created with quickPlay() permanant. Another use could be to have a source automatically removed after it finishes playing. NOTE: Setting a source to temporary does not stop it, and setting a source to permanant does not play it. It is also important to note that a looping temporary source will not be removed as long as it keeps playing.

Parameters:

sourcename - Identifier for the source.

temporary - True = temporary, False = permanant.

removeSource

public void removeSource(java.lang.String sourcename)

Removes the specified source and clears up any memory it used.

Parameters:

sourcename - Identifier for the source.

moveListener

public void moveListener(float x,
                         float y,
                         float z)

Moves the listener relative to the current location.

Parameters:

x - X offset.

y - Y offset.

z - Z offset.

setListenerPosition

public void setListenerPosition(float x,
                                float y,
                                float z)

Moves the listener to the specified location.

Parameters:

x - Destination X coordinate.

y - Destination Y coordinate.

z - Destination Z coordinate.

turnListener

public void turnListener(float angle)

Turns the listener counterclockwise by "angle" radians around the y-axis, relative to the current angle.

Parameters:

angle - radian offset.

setListenerAngle

public void setListenerAngle(float angle)

Sets the listener's angle in radians around the y-axis.

Parameters:

angle - radians.

setListenerOrientation

public void setListenerOrientation(float lookX,
                                   float lookY,
                                   float lookZ,
                                   float upX,
                                   float upY,
                                   float upZ)

Sets the listener's orientation.

Parameters:

lookX - X coordinate of the (normalized) look-at vector.

lookY - Y coordinate of the (normalized) look-at vector.

lookZ - Z coordinate of the (normalized) look-at vector.

upX - X coordinate of the (normalized) up-direction vector.

upY - Y coordinate of the (normalized) up-direction vector.

upZ - Z coordinate of the (normalized) up-direction vector.

setMasterVolume

public void setMasterVolume(float value)

Sets the overall volume, affecting all sources.

Parameters:

value - New volume, float value ( 0.0f - 1.0f ).

getMasterVolume

public float getMasterVolume()

Returns the overall volume, affecting all sources.

Returns:

Float value representing the master volume (0.0f - 1.0f).

getListenerData

public ListenerData getListenerData()

Method for obtaining information about the listener's position and orientation.

Returns:

a ListenerData object.

switchLibrary

public boolean switchLibrary(java.lang.Class libraryClass)
                      throws SoundSystemException

Switches to the specified library, and preserves all sources.

Parameters:

libraryClass - Library to use.

Returns:

True if switch was successful. See SoundSystemConfig for information about chosing a sound library.

Throws:

SoundSystemException

newLibrary

public boolean newLibrary(java.lang.Class libraryClass)
                   throws SoundSystemException

Switches to the specified library, loosing all sources.

Parameters:

libraryClass - Library to use. See SoundSystemConfig for information about chosing a sound library.

Throws:

SoundSystemException

ManageSources

protected void ManageSources()

This method can be overridden by extended classes to be used for source management (culling and activating sources based on established rules). One possible use for this method is sorting sources by distance, culling the furthest, and activating the closest. This method is automatically called on the CommandThread before processing queued commands, so you do not need to call it anywhere else. Note: use methods cull() and activate() here, NOT CommandCull() and CommandActivate() (thread safety issue). IMPORTANT: Always use synchronized( SoundSystemConfig.THREAD_SYNC ) when manually manipulating sources from outside the Command Thread!

CommandQueue

public boolean CommandQueue(CommandObject newCommand)

Queues a command. If newCommand is null, all commands are dequeued and executed. This is automatically used by the sound system, so it is not likely that a user would ever need to use this method. See CommandObject for more information about commands.

Parameters:

newCommand - Command to queue, or null to execute commands.

Returns:

True if more commands exist, false if queue is empty.

removeTemporarySources

public void removeTemporarySources()

Searches for and removes any temporary sources that have finished playing. This method is used internally by SoundSystem, and it is unlikely that the user will ever need to use it.

playing

public boolean playing(java.lang.String sourcename)

Returns true if the specified source is playing.

Parameters:

sourcename - Unique identifier of the source to check.

Returns:

True or false.

playing

public boolean playing()

Returns true if anything is currently playing.

Returns:

True or false.

libraryCompatible

public static boolean libraryCompatible(java.lang.Class libraryClass)

Checks if the specified library type is compatible.

Parameters:

libraryClass - Libary type to check.

Returns:

True or false.

currentLibrary

public static java.lang.Class currentLibrary()

Returns the currently loaded library, or -1 if none.

Returns:

Global library identifier

initialized

public static boolean initialized()

Returns false if a sound library is busy initializing.

Returns:

True or false.

getLastException

public static SoundSystemException getLastException()

Returns the last SoundSystemException thrown, or null if none.

Returns:

The last exception.

setException

public static void setException(SoundSystemException e)

Stores a SoundSystemException which can be retreived later with the 'getLastException' method.

Parameters:

e - Exception to store.

snooze

protected static void snooze(long milliseconds)

Sleeps for the specified number of milliseconds.

message

protected void message(java.lang.String message,
                       int indent)

Prints a message.

Parameters:

message - Message to print.

indent - Number of tabs to indent the message.

importantMessage

protected void importantMessage(java.lang.String message,
                                int indent)

Prints an important message.

Parameters:

message - Message to print.

indent - Number of tabs to indent the message.

errorCheck

protected boolean errorCheck(boolean error,
                             java.lang.String message,
                             int indent)

Prints the specified message if error is true.

Parameters:

error - True or False.

message - Message to print if error is true.

indent - Number of tabs to indent the message.

Returns:

True if error is true.

errorMessage

protected void errorMessage(java.lang.String message,
                            int indent)

Prints an error message.

Parameters:

message - Message to print.

indent - Number of tabs to indent the message.