paulscode.sound
Class SoundSystemConfig

java.lang.Object
  extended by paulscode.sound.SoundSystemConfig

public class SoundSystemConfig
extends java.lang.Object

The SoundSystemConfig class is used to access global sound system settings, and to link with external pluggins. All members of this class are static. SoundSystemConfig is sort of a "catch all" configuration class, so if you are not sure where to find something in the SoundSystem library, this is probably a good place to start.

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
static int ATTENUATION_LINEAR
          Global identifier for linear attenuation.
static int ATTENUATION_NONE
          Global identifier for no attenuation.
static int ATTENUATION_ROLLOFF
          Global identifier for rolloff attenuation.
static java.lang.String EXTENSION_MIDI
          A Regular expression for determining if a file's extension is MIDI.
static java.lang.String PREFIX_URL
          A Regular expression for determining if a path is an online URL.
static java.lang.Object THREAD_SYNC
          Lock object used to synchronize the three threads used by SoundSystem.
static int TYPE_NORMAL
          A normal (non-streaming) source.
static int TYPE_STREAMING
          A streaming source.
 
Constructor Summary
SoundSystemConfig()
           
 
Method Summary
static void addLibrary(java.lang.Class libraryClass)
          Adds an entry to the list of library types.
static void addStreamListener(IStreamListener streamListener)
          Adds an entry to the list of stream listeners.
static ICodec getCodec(java.lang.String filename)
          Returns the codec that can be used to read audio data from the specified file.
static int getDefaultAttenuation()
          Returns the default attenuation model used when one is not specified.
static float getDefaultFadeDistance()
          Returns the default fade distance used when one is not specified.
static float getDefaultRolloff()
          Returns the default rolloff factor used when one is not specified.
static float getDopplerFactor()
          Returns the doppler factor, for determining Doppler Effect scale.
static float getDopplerVelocity()
          Returns the Doppler Velocity, for use in Doppler Effect.
static int getFileChunkSize()
          Returns the size of each chunk to read at a time for loading (non-streaming) files.
static java.util.LinkedList<java.lang.Class> getLibraries()
          Returns the list of library types.
static java.lang.String getLibraryDescription(java.lang.Class libraryClass)
          Return the longer description of the specified library, or null if error.
static java.lang.String getLibraryTitle(java.lang.Class libraryClass)
          Return the short title of the specified library, or null if error.
static SoundSystemLogger getLogger()
          Returns a handle to the message logger.
static float getMasterGain()
          Returns the value for the overall volume.
static int getMaxFileSize()
          Returns the maximum number of bytes to read in for (non-streaming) files.
static int getNumberNormalChannels()
          Returns the maximum number of normal (non-streaming) channels that can be created.
static int getNumberStreamingBuffers()
          Returns the number of buffers used for each streaming sorce.
static int getNumberStreamingChannels()
          Returns the maximum number of streaming channels that can be created.
static java.lang.String getOverrideMIDISynthesizer()
          Returns the name of the MIDI synthesizer to use instead of the default, or empty string if none was specified.
static java.lang.String getSoundFilesPackage()
          Returns the package where sound files are located.
static int getStreamingBufferSize()
          Returns the number of bytes to load at a time when streaming.
static boolean getStreamQueueFormatsMatch()
          Returns whether or not all sounds in each streaming source's queue will be handled as if they have exactly the same format once decoded (including channels, sample rate, and sample size).
static boolean libraryCompatible(java.lang.Class libraryClass)
          Checks if the specified library class is compatible on the user's machine.
static boolean midiCodec()
          Indicates whether or not there is a codec for reading from MIDI files.
static void notifyEOS(java.lang.String sourcename, int queueSize)
          Notifies all stream listeners that an End Of Stream was reached.
static void removeLibrary(java.lang.Class libraryClass)
          Removes the specified library from the list of library types.
static void removeStreamListener(IStreamListener streamListener)
          Removes an entry from the list of stream listeners.
static boolean reverseByteOrder(java.lang.Class libraryClass)
          Return whether or not requires reversal of audio data byte-order.
static void setCodec(java.lang.String extension, java.lang.Class iCodecClass)
          Uses the specified file extension to associate a particular file format with the codec used to read audio data from it.
static void setDefaultAttenuation(int model)
          Sets the default attenuation model to use when one is not specified.
static void setDefaultFadeDistance(float distance)
          Sets the default fade distance to use when one is not specified.
static void setDefaultRolloff(float rolloff)
          Sets the default rolloff factor to use when one is not specified.
static void setDopplerFactor(float factor)
          Sets the doppler factor, for determining Doppler Effect scale.
static void setDopplerVelocity(float velocity)
          Sets the Doppler velocity, for use in Doppler Effect.
static void setFileChunkSize(int size)
          Sets the size of each chunk to read at a time for loading (non-streaming) files.
static void setLogger(SoundSystemLogger l)
          Changes the message logger to use for handling status messages, warnings, and error messages.
static void setMasterGain(float value)
          Sets the varriable used for overall volume, affecting all sources.
static void setMaxFileSize(int size)
          Sets the maximum number of bytes to read in for (non-streaming) files.
static void setNumberNormalChannels(int number)
          Sets the maximum number of normal (non-streaming) channels that can be created.
static void setNumberStreamingBuffers(int num)
          Sets the number of buffers used for each streaming sorce.
static void setNumberStreamingChannels(int number)
          Sets the maximum number of streaming channels that can be created.
static void setOverrideMIDISynthesizer(java.lang.String name)
          Sets the name of the MIDI synthesizer to use instead of the default.
static void setSoundFilesPackage(java.lang.String location)
          Sets the package where sound files are located.
static void setStreamingBufferSize(int size)
          Sets the number of bytes to load at a time when streaming.
static void setStreamQueueFormatsMatch(boolean val)
          Enables a transition-speed optimization by assuming all sounds in each streaming source's queue will have exactly the same format once decoded (including channels, sample rate, and sample size).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

THREAD_SYNC

public static final java.lang.Object THREAD_SYNC
Lock object used to synchronize the three threads used by SoundSystem. Synchronize on this anytime you manually manipulate a Source's properties.


TYPE_NORMAL

public static final int TYPE_NORMAL
A normal (non-streaming) source. Also used to define a Channel type as normal.

See Also:
Constant Field Values

TYPE_STREAMING

public static final int TYPE_STREAMING
A streaming source. Also used to define a Channel type as streaming.

See Also:
Constant Field Values

ATTENUATION_NONE

public static final int ATTENUATION_NONE
Global identifier for no attenuation. Attenuation is how a source's volume fades with distance. When there is no attenuation, a source's volume remains constaint regardles of distance.

See Also:
Constant Field Values

ATTENUATION_ROLLOFF

public static final int ATTENUATION_ROLLOFF
Global identifier for rolloff attenuation. Rolloff attenuation is a realistic attenuation model, which uses a rolloff factor to determine how quickly a source fades with distance. A smaller rolloff factor will fade at a further distance, and a rolloff factor of 0 will never fade. NOTE: In OpenAL, rolloff attenuation only works for monotone sounds.

See Also:
Constant Field Values

ATTENUATION_LINEAR

public static final int ATTENUATION_LINEAR
Global identifier for linear attenuation. Linear attenuation is less realistic than rolloff attenuation, but it allows the user to specify a maximum "fade distance" where a source's volume becomes zero.

See Also:
Constant Field Values

EXTENSION_MIDI

public static java.lang.String EXTENSION_MIDI
A Regular expression for determining if a file's extension is MIDI.


PREFIX_URL

public static java.lang.String PREFIX_URL
A Regular expression for determining if a path is an online URL.

Constructor Detail

SoundSystemConfig

public SoundSystemConfig()
Method Detail

addLibrary

public static void addLibrary(java.lang.Class libraryClass)
                       throws SoundSystemException
Adds an entry to the list of library types. This method has no effect if the specified library type is already in the list of libraries. NOTE: The parameterless constructor of the SoundSystem class will try to load libraries in the order that they were entered into the list.

Parameters:
libraryClass - Derivitive of class 'Library'.
Throws:
SoundSystemException

removeLibrary

public static void removeLibrary(java.lang.Class libraryClass)
                          throws SoundSystemException
Removes the specified library from the list of library types.

Parameters:
libraryClass - Derivitive of class 'Library'.
Throws:
SoundSystemException

getLibraries

public static java.util.LinkedList<java.lang.Class> getLibraries()
Returns the list of library types.

Returns:
LinkedList of classes derived from 'Library', or null if none were specified.

libraryCompatible

public static boolean libraryCompatible(java.lang.Class libraryClass)
Checks if the specified library class is compatible on the user's machine.

Parameters:
libraryClass - Library type to check.
Returns:
True or false.

getLibraryTitle

public static java.lang.String getLibraryTitle(java.lang.Class libraryClass)
Return the short title of the specified library, or null if error.

Parameters:
libraryClass - Derivitive of class 'Library'.
Returns:
String containing the library title.

getLibraryDescription

public static java.lang.String getLibraryDescription(java.lang.Class libraryClass)
Return the longer description of the specified library, or null if error.

Parameters:
libraryClass - Derivitive of class 'Library'.
Returns:
String containing the library title.

reverseByteOrder

public static boolean reverseByteOrder(java.lang.Class libraryClass)
Return whether or not requires reversal of audio data byte-order.

Parameters:
libraryClass - Derivitive of class 'Library'.
Returns:
True if byte-order reversal is required.

setLogger

public static void setLogger(SoundSystemLogger l)
Changes the message logger to use for handling status messages, warnings, and error messages. This method should only be called BEFORE instantiating the SoundSystem class! If this method is called after the SoundSystem has been created, there will be handles floating around to two different loggers, and the results will be undesirable. This method can be used to change how messages are handled. First, the SoundSystemLogger class should be extended and methods overriden to change how messages are handled. Then, the overridden class should be instantiated, and a call made to SoundSystemConfig.setLogger() before creating the SoundSystem object. If an alternate logger is not set by the user before the SoundSystem is instantiated, then an instance of the base SoundSystemLogger class will be used by default.

Parameters:
l - Handle to a message logger.

getLogger

public static SoundSystemLogger getLogger()
Returns a handle to the message logger.

Returns:
The current message logger.

setNumberNormalChannels

public static void setNumberNormalChannels(int number)
Sets the maximum number of normal (non-streaming) channels that can be created. Streaming channels are created first, so the higher the maximum number of streaming channels is set, the fewer non-streaming channels will be available. If unable to create the number of channels specified, SoundSystem will create as many as possible. NOTE: Some sound library pluggins may require the total number of channels (non-streaming + streaming) to be 32.

Parameters:
number - How many normal audio channels.

getNumberNormalChannels

public static int getNumberNormalChannels()
Returns the maximum number of normal (non-streaming) channels that can be created.

Returns:
Maximum non-streaming channels.

setNumberStreamingChannels

public static void setNumberStreamingChannels(int number)
Sets the maximum number of streaming channels that can be created. Streaming channels are created first, so the higher the maximum number of streaming channels is set, the fewer non-streaming channels will be available. If unable to create the number of channels specified, SoundSystem will create as many as possible. NOTE: Some sound library pluggins may require the total number of channels (non-streaming + streaming) to be 32.

Parameters:
number - How many streaming audio channels.

getNumberStreamingChannels

public static int getNumberStreamingChannels()
Returns the maximum number of streaming channels that can be created.

Returns:
Maximum streaming channels.

setMasterGain

public static void setMasterGain(float value)
Sets the varriable used for overall volume, affecting all sources.

Parameters:
value - Float value (0.0f - 1.0f).

getMasterGain

public static float getMasterGain()
Returns the value for the overall volume.

Returns:
A float value (0.0f - 1.0f).

setDefaultAttenuation

public static void setDefaultAttenuation(int model)
Sets the default attenuation model to use when one is not specified. Attenuation is how a source's volume fades with distance.

Parameters:
model - A global attenuation model identifier.

getDefaultAttenuation

public static int getDefaultAttenuation()
Returns the default attenuation model used when one is not specified.

Returns:
A global attenuation model identifier

setDefaultRolloff

public static void setDefaultRolloff(float rolloff)
Sets the default rolloff factor to use when one is not specified.

Parameters:
rolloff - Rolloff factor.

getDopplerFactor

public static float getDopplerFactor()
Returns the doppler factor, for determining Doppler Effect scale.

Returns:
Doppler factor

setDopplerFactor

public static void setDopplerFactor(float factor)
Sets the doppler factor, for determining Doppler Effect scale. Use this method BEFORE instantiating the SoundSystem. To change the Doppler factor after the SoundSystem is instantiated, use the SoundSystem.changeDopplerFactor method instead.

Parameters:
factor - Doppler factor.

getDopplerVelocity

public static float getDopplerVelocity()
Returns the Doppler Velocity, for use in Doppler Effect.

Returns:
Doppler velocity.

setDopplerVelocity

public static void setDopplerVelocity(float velocity)
Sets the Doppler velocity, for use in Doppler Effect. Use this method BEFORE instantiating the SoundSystem. To change the Doppler velocity after the SoundSystem is instantiated, use the SoundSystem.changeDopplerVelocity method instead.

Parameters:
velocity - Doppler velocity.

getDefaultRolloff

public static float getDefaultRolloff()
Returns the default rolloff factor used when one is not specified.

Returns:
Default rolloff factor

setDefaultFadeDistance

public static void setDefaultFadeDistance(float distance)
Sets the default fade distance to use when one is not specified.

Parameters:
distance - Fade Distance.

getDefaultFadeDistance

public static float getDefaultFadeDistance()
Returns the default fade distance used when one is not specified.

Returns:
Default fade distance

setSoundFilesPackage

public static void setSoundFilesPackage(java.lang.String location)
Sets the package where sound files are located.

Parameters:
location - Path to the sound files location (must be followed by '/').

getSoundFilesPackage

public static java.lang.String getSoundFilesPackage()
Returns the package where sound files are located.

Returns:
Path to the sound files location

setStreamingBufferSize

public static void setStreamingBufferSize(int size)
Sets the number of bytes to load at a time when streaming.

Parameters:
size - Size in bytes.

getStreamingBufferSize

public static int getStreamingBufferSize()
Returns the number of bytes to load at a time when streaming.

Returns:
Size in bytes.

setNumberStreamingBuffers

public static void setNumberStreamingBuffers(int num)
Sets the number of buffers used for each streaming sorce. Slow codecs may require this number to be greater than 2 to prevent audio skipping during playback.

Parameters:
num - How many buffers.

getNumberStreamingBuffers

public static int getNumberStreamingBuffers()
Returns the number of buffers used for each streaming sorce.

Returns:
How many buffers.

setStreamQueueFormatsMatch

public static void setStreamQueueFormatsMatch(boolean val)
Enables a transition-speed optimization by assuming all sounds in each streaming source's queue will have exactly the same format once decoded (including channels, sample rate, and sample size). This is an advanced setting which should only be changed by experienced developers.

Parameters:
val - False by default.

getStreamQueueFormatsMatch

public static boolean getStreamQueueFormatsMatch()
Returns whether or not all sounds in each streaming source's queue will be handled as if they have exactly the same format once decoded (including channels, sample rate, and sample size). This is an advanced setting which should only be changed by experienced developers.

Returns:
Normally false.

setMaxFileSize

public static void setMaxFileSize(int size)
Sets the maximum number of bytes to read in for (non-streaming) files. Increase this value if non-streaming sounds are getting cut off. Decrease this value if large sound files are causing lag during load time.

Parameters:
size - Size in bytes.

getMaxFileSize

public static int getMaxFileSize()
Returns the maximum number of bytes to read in for (non-streaming) files.

Returns:
Size in bytes.

setFileChunkSize

public static void setFileChunkSize(int size)
Sets the size of each chunk to read at a time for loading (non-streaming) files. Increase if loading sound files is causing significant lag.

Parameters:
size - Size in bytes.

getFileChunkSize

public static int getFileChunkSize()
Returns the size of each chunk to read at a time for loading (non-streaming) files.

Returns:
Size in bytes.

getOverrideMIDISynthesizer

public static java.lang.String getOverrideMIDISynthesizer()
Returns the name of the MIDI synthesizer to use instead of the default, or empty string if none was specified.

Returns:
All or part of a MIDI device name, or empty string for not specified.

setOverrideMIDISynthesizer

public static void setOverrideMIDISynthesizer(java.lang.String name)
Sets the name of the MIDI synthesizer to use instead of the default. If 'name' is an empty string, the default Synthesizer will be used, or one of the common alternate synthesizers if the default Synthesizer is unavailable.

Parameters:
name - All or part of the MIDI device name.

setCodec

public static void setCodec(java.lang.String extension,
                            java.lang.Class iCodecClass)
                     throws SoundSystemException
Uses the specified file extension to associate a particular file format with the codec used to read audio data from it.

Parameters:
extension - File extension to be associated with the specified codec.
iCodecClass - Codec type to use for files with the specified extension.
Throws:
SoundSystemException

getCodec

public static ICodec getCodec(java.lang.String filename)
Returns the codec that can be used to read audio data from the specified file.

Parameters:
filename - File to get a codec for.
Returns:
Codec to use for reading audio data.

midiCodec

public static boolean midiCodec()
Indicates whether or not there is a codec for reading from MIDI files. If there is no codec for MIDI, then SoundSystem uses javax.sound.midi.

Returns:
True if there the user defined a MIDI codec.

addStreamListener

public static void addStreamListener(IStreamListener streamListener)
Adds an entry to the list of stream listeners. If the instance is already in the list, the command is ignored.

Parameters:
streamListener - Implementation of interface 'IStreamListener'.

removeStreamListener

public static void removeStreamListener(IStreamListener streamListener)
Removes an entry from the list of stream listeners.

Parameters:
streamListener - Implementation of interface 'IStreamListener'.

notifyEOS

public static void notifyEOS(java.lang.String sourcename,
                             int queueSize)
Notifies all stream listeners that an End Of Stream was reached. If there are no listeners, the command is ignored.

Parameters:
sourcename - String identifier of the source which reached the EOS.
queueSize - Number of items left the the stream's play queue, or zero if none.