| Category | Audio

It’s taken me quite some time to get to this, but here it is: All new Sound methods! Let’s get to the core of it.

Every time you call Sound#play() you will get a long. This long identifies that instance of the Sound being played back at the moment. You can use this id to manipulate that sound instance while its playing: loop it, change it’s pitch, volume and panning!

And here is the Sound interface for the lazy

public interface Sound extends Disposable {
   /** Plays the sound. If the sound is already playing, it will be played again, concurrently. 
    * @return the id of the sound instance. */
   public long play ();

   /** Plays the sound. If the sound is already playing, it will be played again, concurrently.
    * @param volume the volume in the range [0,1] 
    * @return the id of the sound instance 
    */
   public long play (float volume);
   
   /**
    * Plays the sound, looping. If the sound is already playing, it will be played again, concurrently.
    * @return the id of the sound instance
    */
   public long loop();
   
   /**
    * Plays the sound, looping. If the sound is already playing, it will be played again, concurrently.
    * @param volume the volume in the range [0, 1]
    * @return the id of the sound instance
    */
   public long loop(float volume);

   /** Stops playing all instances of this sound. */
   public void stop ();

   /** Releases all the resources. */
   public void dispose ();
   
   /**
    * Stops the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If
    * the sound is no longer playing, this has no effect.
    * @param soundId the sound id
    */
   public void stop(long soundId);
   
   /**
    * Sets the sound instance with the given id to be looping. If the sound is no longer playing this has no effect.s
    * @param soundId the sound id
    * @param looping whether to loop or not.
    */
   public void setLooping(long soundId, boolean looping);

   /**
    * Changes the pitch multiplier of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If
    * the sound is no longer playing, this has no effect.
    * @param soundId the sound id
    * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower
    */
   public void setPitch(long soundId, float pitch);
   
   /**
    * Changes the volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If
    * the sound is no longer playing, this has no effect.
    * @param soundId the sound id
    * @param volume the volume in the range 0 (silent) to 1 (max volume).
    */
   public void setVolume(long soundId, float volume);
   
   /**
    * Sets the panning and volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the 
    * sound is no longer playing, this has no effect.
    * @param soundId the sound id
    * @param pan panning in the range -1 (full right) to 1 (full left). 0 is center position.
    * @param volume the volume in the range [0,1].
    */
   public void setPan(long soundId, float pan, float volume);
}

public interface Sound extends Disposable {

/** Plays the sound. If the sound is already playing, it will be played again, concurrently.

* @return the id of the sound instance. */

public long play ();

/** Plays the sound. If the sound is already playing, it will be played again, concurrently.

* @param volume the volume in the range [0,1]

* @return the id of the sound instance

public long play (float volume);

/**

* Plays the sound, looping. If the sound is already playing, it will be played again, concurrently.

* @return the id of the sound instance

public long loop();

/**

* Plays the sound, looping. If the sound is already playing, it will be played again, concurrently.

* @param volume the volume in the range [0, 1]

* @return the id of the sound instance

public long loop(float volume);

/** Stops playing all instances of this sound. */

public void stop ();

/** Releases all the resources. */

public void dispose ();

/**

* Stops the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If

* the sound is no longer playing, this has no effect.

* @param soundId the sound id

public void stop(long soundId);

/**

* Sets the sound instance with the given id to be looping. If the sound is no longer playing this has no effect.s

* @param soundId the sound id

* @param looping whether to loop or not.

public void setLooping(long soundId, boolean looping);

/**

* Changes the pitch multiplier of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If

* the sound is no longer playing, this has no effect.

* @param soundId the sound id

* @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower

public void setPitch(long soundId, float pitch);

/**

* Changes the volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If

* the sound is no longer playing, this has no effect.

* @param soundId the sound id

* @param volume the volume in the range 0 (silent) to 1 (max volume).

public void setVolume(long soundId, float volume);

/**

* Sets the panning and volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the

* sound is no longer playing, this has no effect.

* @param soundId the sound id

* @param pan panning in the range -1 (full right) to 1 (full left). 0 is center position.

* @param volume the volume in the range [0,1].

public void setPan(long soundId, float pan, float volume);

}

Pretty simple eh? I’ll clean up the small inconsistencies in the Javadocs asap when we do our Javadoc sweep next week.

Three things:

setPan() takes the volume as well. Why? Cause i can’t get a hold of the volume of a stream (==sound instance) via Android’s SoundPool and keeping a list is tedious and bound to create leaks and GC invocations.
There is not Sound#isPlaying(long soundId). Why? Cause SoundPool doesn’t give me that information. There is no good work around for that (e.g. figuring out the sound length in seconds, and meassuring how long the sound’s been played back does not work as we don’t have an idea about latency on Android)
If a sound id is no longer valid and you pass it to any of the methods above… nothing will happen 😀
I might have mixed up linear and logarithmic gain/volume along the way for panning. If you find a problem let me know. The OpenAL implementation of panning is kinda hackish but is “good enough”(tm)

One more thing while i’m here: i haven’t been to the forums for a week, i’m sorry. Things are crazy at the moment and on top of that Stef came to SF. This means i won’t be back to the forums for another week.

Enjoy (and test)!

Audio

gdx-audio

Sound API additions for libgdx!

Tyonar – Just Cause