# Class SoundPool

java.lang.Object
com.codename1.gaming.SoundPool

public final 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.
  `boolean`
  `isVoiceCompletionSupported()`
  True if this pool can report voice completion to a `VoiceListener`.
  `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`
  `setVoiceListener(VoiceListener listener)`
  Registers a listener notified (on the EDT) as each voice finishes playing, or `null` to clear it.
  `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.

  - ### isVoiceCompletionSupported

    public boolean isVoiceCompletionSupported()
    True if this pool can report voice completion to a `VoiceListener`. The cross-platform fallback mixer supports it; some native engines (e.g. Android's `SoundPool`) do not.

  - ### setVoiceListener

    public void setVoiceListener(VoiceListener listener)
    Registers a listener notified (on the EDT) as each voice finishes playing, or `null` to clear it. Has no effect on backends where `#isVoiceCompletionSupported()` is false.

  - ### 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.