SoundSystemConfig (Etyl Commons 1.0.2 API)

java.lang.Object
- paulscode.sound.SoundSystemConfig

```
public class SoundSystemConfig
extends 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

Fields
Modifier and Type	Field and Description
`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 String`	`EXTENSION_MIDI` A Regular expression for determining if a file's extension is MIDI.
`static String`	`PREFIX_URL` A Regular expression for determining if a path is an online URL.
`static 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

Constructors
Constructor and Description

SoundSystemConfig()

Constructors
Constructor and Description
`SoundSystemConfig()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addLibrary(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(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 LinkedList<Class>`	`getLibraries()` Returns the list of library types.
`static String`	`getLibraryDescription(Class libraryClass)` Return the longer description of the specified library, or null if error.
`static String`	`getLibraryTitle(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 String`	`getOverrideMIDISynthesizer()` Returns the name of the MIDI synthesizer to use instead of the default, or empty string if none was specified.
`static 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`	`libraryCompatible(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(String sourcename, int queueSize)` Notifies all stream listeners that an End Of Stream was reached.
`static void`	`removeLibrary(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(Class libraryClass)` Return whether or not requires reversal of audio data byte-order.
`static void`	`setCodec(String extension, 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(String name)` Sets the name of the MIDI synthesizer to use instead of the default.
`static void`	`setSoundFilesPackage(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.

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 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 String EXTENSION_MIDI
```
    A Regular expression for determining if a file's extension is MIDI.
  - PREFIX_URL
```
public static 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(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(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 LinkedList<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(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 String getLibraryTitle(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 String getLibraryDescription(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(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(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 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.
  - 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 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(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(String extension,
                            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(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(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.

Class SoundSystemConfig

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

THREAD_SYNC

TYPE_NORMAL

TYPE_STREAMING

ATTENUATION_NONE

ATTENUATION_ROLLOFF

ATTENUATION_LINEAR

EXTENSION_MIDI

PREFIX_URL

Constructor Detail

SoundSystemConfig

Method Detail

addLibrary

removeLibrary

getLibraries

libraryCompatible

getLibraryTitle

getLibraryDescription

reverseByteOrder

setLogger

getLogger

setNumberNormalChannels

getNumberNormalChannels

setNumberStreamingChannels

getNumberStreamingChannels

setMasterGain

getMasterGain

setDefaultAttenuation

getDefaultAttenuation

setDefaultRolloff

getDopplerFactor

setDopplerFactor

getDopplerVelocity

setDopplerVelocity

getDefaultRolloff

setDefaultFadeDistance

getDefaultFadeDistance

setSoundFilesPackage

getSoundFilesPackage

setStreamingBufferSize

getStreamingBufferSize

setNumberStreamingBuffers

getNumberStreamingBuffers

setMaxFileSize

getMaxFileSize

setFileChunkSize

getFileChunkSize

getOverrideMIDISynthesizer

setOverrideMIDISynthesizer

setCodec

getCodec

midiCodec

addStreamListener

removeStreamListener

notifyEOS