Class SoundPool

java.lang.Object
com.codename1.gaming.SoundPool
public class SoundPool extends Object

Plays many short, overlapping sound effects with low latency.

A SoundPool is built for game audio: gunshots, coins, footsteps -- sounds that must trigger instantly and play several at once. Load each clip once with #load(String) and trigger it repeatedly with #play(SoundEffect); the pool mixes up to #getMaxStreams() voices simultaneously and drops the request (returning -1) rather than blocking when that limit is reached.

SoundPool sfx = SoundPool.create(8);
SoundEffect coin = sfx.load("/coin.wav");
// ... in the game loop:
coin.play();

On platforms with a purpose built low latency audio engine (Android, iOS, the desktop simulator and the browser) the pool uses it directly, supporting per play volume, stereo pan and pitch/rate. Where no native backend exists it falls back to a com.codename1.media.MediaManager based pool that still works everywhere but has higher latency and ignores pan and rate -- #isNativeAccelerated() reports which path is in use.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    autoPause()
    Pauses all playback, for example when the app is backgrounded.
    void
    autoResume()
    Resumes playback paused by #autoPause().
    static SoundPool
    create(int maxStreams)
    Creates a sound pool that mixes up to maxStreams voices at once.
    int
    getMaxStreams()
    The maximum number of voices that can play simultaneously.
    boolean
    isNativeAccelerated()
    True if a native low latency audio backend is in use; false if the cross platform MediaManager fallback is in use.
    SoundEffect
    load(InputStream data, String mimeType)
    Loads a sound effect from a stream of the given mime type.
    SoundEffect
    load(String uri)
    Loads a sound effect from a uri (for example a /sound.wav resource path).
    AsyncResource<SoundEffect>
    loadAsync(String uri)
    Loads a sound effect from a uri on a background thread, completing the returned resource on success or error.
    void
    pause(int voiceId)
    Pauses a playing voice.
    int
    play(SoundEffect effect)
    Plays the effect once at full volume, centered, normal rate.
    int
    play(SoundEffect effect, float volume, float pan, float rate, int loop)
    Plays the effect with explicit parameters.
    void
    release()
    Releases the pool and all loaded effects.
    void
    resume(int voiceId)
    Resumes a paused voice.
    void
    setPan(int voiceId, float pan)
    Sets the stereo pan (-1.0 to 1.0) of a playing voice (native backends only).
    void
    setRate(int voiceId, float rate)
    Sets the playback rate / pitch of a playing voice (native backends only).
    void
    setVolume(int voiceId, float volume)
    Sets the volume (0.0 to 1.0) of a playing voice.
    void
    stop(int voiceId)
    Stops a voice.
    void
    stopAll()
    Stops every playing voice.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • create

      public static SoundPool create(int maxStreams)
      Creates a sound pool that mixes up to maxStreams voices at once.

    • isNativeAccelerated

      public boolean isNativeAccelerated()
      True if a native low latency audio backend is in use; false if the cross platform MediaManager fallback is in use.

    • getMaxStreams

      public int getMaxStreams()
      The maximum number of voices that can play simultaneously.

    • load

      public SoundEffect load(String uri) throws IOException
      Loads a sound effect from a uri (for example a /sound.wav resource path).
      Throws:
      IOException

    • load

      public SoundEffect load(InputStream data, String mimeType) throws IOException
      Loads a sound effect from a stream of the given mime type. The stream is fully read and closed.
      Throws:
      IOException

    • loadAsync

      public AsyncResource<SoundEffect> loadAsync(String uri)
      Loads a sound effect from a uri on a background thread, completing the returned resource on success or error.

    • play

      public int play(SoundEffect effect)
      Plays the effect once at full volume, centered, normal rate. Returns a voice id, or -1 if no voice was available.

    • play

      public int play(SoundEffect effect, float volume, float pan, float rate, int loop)

      Plays the effect with explicit parameters.

      Parameters

      • effect: the loaded sound to play

      • volume: 0.0 (silent) to 1.0 (full)

      • pan: -1.0 (full left) to 1.0 (full right), 0.0 centered (ignored by the fallback)

      • rate: playback rate / pitch, 1.0 normal, typically 0.5 to 2.0 (ignored by the fallback)

      • loop: 0 plays once, -1 loops forever, n repeats n extra times

      Returns

      a voice id usable with #stop(int) etc., or -1 if the pool is exhausted

    • setVolume

      public void setVolume(int voiceId, float volume)
      Sets the volume (0.0 to 1.0) of a playing voice.

    • setRate

      public void setRate(int voiceId, float rate)
      Sets the playback rate / pitch of a playing voice (native backends only).

    • setPan

      public void setPan(int voiceId, float pan)
      Sets the stereo pan (-1.0 to 1.0) of a playing voice (native backends only).

    • pause

      public void pause(int voiceId)
      Pauses a playing voice.

    • resume

      public void resume(int voiceId)
      Resumes a paused voice.

    • stop

      public void stop(int voiceId)
      Stops a voice.

    • stopAll

      public void stopAll()
      Stops every playing voice.

    • autoPause

      public void autoPause()
      Pauses all playback, for example when the app is backgrounded.

    • autoResume

      public void autoResume()
      Resumes playback paused by #autoPause().

    • release

      public void release()
      Releases the pool and all loaded effects. The pool must not be used afterwards.