Package com.ardor3d.audio

Class SoundSystem

java.lang.Object
com.ardor3d.audio.SoundSystem
public class SoundSystem extends 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 Julien Gouesse: I removed Midi support in order to stop depending on javax.sound more easily and I replaced a deprecated call

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected String
    className
    Name of this class.
    protected 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.
    Random
    randomNumberGenerator
    Generates random numbers.
    protected Library
    soundLibrary
    Handle to the active sound library.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SoundSystem()
    Constructor: Create the sound system using the default library.
    SoundSystem(Class<? extends Library> libraryClass)
    Constructor: Create the sound system using the specified library.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    activate(String sourcename)
    Activates the specified source after it was culled, so it can be played again.
    void
    backgroundMusic(String sourcename, String filename, boolean toLoop)
    Creates a new permanant, streaming, priority source with zero attenuation.
    void
    backgroundMusic(String sourcename, URL url, 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(String sourcename)
    Culls the specified source.
    static Class<? extends Library>
    currentLibrary()
    Returns the currently loaded library, or -1 if none.
    void
    dequeueSound(String sourcename, 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, String message, int indent)
    Prints the specified message if error is true.
    protected void
    errorMessage(String message, int indent)
    Prints an error message.
    void
    fadeOut(String sourcename, 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(String sourcename, URL url, 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(String sourcename, 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(String sourcename, URL url, 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(String sourcename, byte[] buffer)
    Feeds raw data through the specified source.
    void
    flush(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(String sourcename)
    Returns the pitch of the specified source.
    float
    getVolume(String sourcename)
    Returns the current volume of the specified source, or zero if the specified source was not found.
    protected void
    importantMessage(String message, int indent)
    Prints an important message.
    protected void
    init(Class<? extends Library> 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(Class<? extends Library> 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, AudioFormat format, String identifier)
    Saves raw PCM audio data in the specified audio format, under the specified identifier.
    void
    loadSound(String filename)
    Pre-loads a sound into memory.
    void
    loadSound(URL url, 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(String message, int indent)
    Prints a message.
    float
    millisecondsPlayed(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(Class<? extends Library> libraryClass)
    Switches to the specified library, loosing all sources.
    void
    newSource(boolean priority, String sourcename, String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a new non-streaming source.
    void
    newSource(boolean priority, String sourcename, URL url, String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a new non-streaming source.
    void
    newStreamingSource(boolean priority, String sourcename, String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a new streaming source.
    void
    newStreamingSource(boolean priority, String sourcename, URL url, String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a new streaming source.
    void
    pause(String sourcename)
    Pauses the specified source.
    void
    play(String sourcename)
    Plays the specified source.
    boolean
    playing()
    Returns true if anything is currently playing.
    boolean
    playing(String sourcename)
    Returns true if the specified source is playing.
    void
    queueSound(String sourcename, 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(String sourcename, URL url, 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.
    String
    quickPlay(boolean priority, String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a temporary source and plays it.
    String
    quickPlay(boolean priority, URL url, String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a temporary source and plays it.
    String
    quickStream(boolean priority, String filename, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a temporary source and streams it.
    String
    quickStream(boolean priority, URL url, String identifier, boolean toLoop, float x, float y, float z, int attmodel, float distOrRoll)
    Creates a temporary source and streams it.
    void
    rawDataStream(AudioFormat audioFormat, boolean priority, String sourcename, float x, float y, float z, int attModel, float distOrRoll)
    Opens a direct line for streaming audio data.
    void
    removeSource(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(String sourcename)
    Rewinds the specified source.
    void
    setAttenuation(String sourcename, int model)
    Changes a source's attenuation model.
    void
    setDistOrRoll(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(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(String sourcename, float value)
    Manually sets the specified source's pitch.
    void
    setPosition(String sourcename, float x, float y, float z)
    Move a source to the specified location.
    void
    setPriority(String sourcename, boolean pri)
    Set a source's priority factor.
    void
    setTemporary(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(String sourcename, float x, float y, float z)
    Sets the specified source's velocity, for use in Doppler effect.
    void
    setVolume(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(String sourcename)
    Stops the specified source.
    boolean
    switchLibrary(Class<? extends Library> 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(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 Details

    • logger

      protected SoundSystemLogger logger
      Processes status messages, warnings, and error messages.

    • soundLibrary

      protected Library soundLibrary
      Handle to the active sound library.

    • commandQueue

      protected List<CommandObject> commandQueue
      List of queued commands to perform.

    • commandThread

      protected CommandThread commandThread
      Processes queued commands in the background.

    • randomNumberGenerator

      public Random randomNumberGenerator
      Generates random numbers.

    • className

      protected String className
      Name of this class.

  • Constructor Details

    • 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(Class<? extends Library> 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 Details

    • 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(Class<? extends Library> 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(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(URL url, 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, AudioFormat format, 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(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(String sourcename, 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(String sourcename, URL url, 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(String sourcename, 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(String sourcename, 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(String sourcename, URL url, 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(String sourcename, 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(String sourcename, URL url, 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(String sourcename, 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(String sourcename, URL url, 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, String sourcename, 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, String sourcename, URL url, 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, String sourcename, 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, String sourcename, URL url, 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(AudioFormat audioFormat, boolean priority, 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 String quickPlay(boolean priority, 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 String quickPlay(boolean priority, URL url, 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 String quickStream(boolean priority, 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 String quickStream(boolean priority, URL url, 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(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(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(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(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(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(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(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(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(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(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(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(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(String sourcename)
      Plays the specified source.
      Parameters:
      sourcename - Identifier for the source.

    • pause

      public void pause(String sourcename)
      Pauses the specified source.
      Parameters:
      sourcename - Identifier for the source.

    • stop

      public void stop(String sourcename)
      Stops the specified source.
      Parameters:
      sourcename - Identifier for the source.

    • rewind

      public void rewind(String sourcename)
      Rewinds the specified source.
      Parameters:
      sourcename - Identifier for the source.

    • flush

      public void flush(String sourcename)
      Flushes all previously queued audio data from a streaming source.
      Parameters:
      sourcename - Identifier for the source.

    • cull

      public void cull(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(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(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(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(Class<? extends Library> 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(Class<? extends Library> 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(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(Class<? extends Library> libraryClass)
      Checks if the specified library type is compatible.
      Parameters:
      libraryClass - Libary type to check.
      Returns:
      True or false.

    • currentLibrary

      public static Class<? extends Library> 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(String message, int indent)
      Prints a message.
      Parameters:
      message - Message to print.
      indent - Number of tabs to indent the message.

    • importantMessage

      protected void importantMessage(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, 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(String message, int indent)
      Prints an error message.
      Parameters:
      message - Message to print.
      indent - Number of tabs to indent the message.