Package com.ardor3d.audio

Class SoundSystemConfig

java.lang.Object
com.ardor3d.audio.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
    Description
    static final int
    ATTENUATION_LINEAR
    Global identifier for linear attenuation.
    static final int
    ATTENUATION_NONE
    Global identifier for no attenuation.
    static final 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 final Object
    THREAD_SYNC
    Lock object used to synchronize the three threads used by SoundSystem.
    static final int
    TYPE_NORMAL
    A normal (non-streaming) source.
    static final int
    TYPE_STREAMING
    A streaming source.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SoundSystemConfig()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    addLibrary(Class<? extends Library> 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<? extends Library>>
    getLibraries()
    Returns the list of library types.
    static String
    getLibraryDescription(Class<? extends Library> libraryClass)
    Return the longer description of the specified library, or null if error.
    static String
    getLibraryTitle(Class<? extends Library> 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
    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(Class<? extends Library> 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<? extends Library> 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<? extends Library> libraryClass)
    Return whether or not requires reversal of audio data byte-order.
    static void
    setCodec(String extension, Class<? extends ICodec> 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.
    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 Details

    • 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:

    • TYPE_STREAMING

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

    • 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:

    • 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:

    • 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:

    • 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 Details

    • SoundSystemConfig

      public SoundSystemConfig()

  • Method Details

    • addLibrary

      public static void addLibrary(Class<? extends Library> 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<? extends Library> 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<? extends Library>> 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<? extends Library> 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<? extends Library> 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<? extends Library> 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<? extends Library> 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.

    • 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 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<? extends ICodec> 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.