Interface SoundEffect

All Superinterfaces:
com.badlogic.gdx.utils.Disposable, com.badlogic.gdx.audio.Sound

public interface SoundEffect extends com.badlogic.gdx.audio.Sound
This interface represents playback for an in-memory audio asset.

As a subinterface of Sound, this supports pausing, resuming and so on, even on multiple simultaneous instances. It also adds support for a callback function (see SoundEffect.OnCompletionListener) when an instance has stopped playing.

The audio data being play is fully loaded into memory, so this interface is primarily for short clips. While there is no upper limit on the audio file size, you should avoid using this class for any sound asset greater than 1 MB.

Sound effect instances are created via AudioEngine.newSound(com.badlogic.gdx.files.FileHandle). When you are done with using the sound effect instance you have to dispose it via the Sound.dispose() method.

This interface is not even remotely thread-safe. LibGDX requires that all audio interfaces be interacted with in the main application thread (for much the same reason that OpenGL requires this).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    The interface for a callback invoked as a sound instance is completed
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addEffect(long soundId, EffectFilter effect)
    Sets the effect that this instance is played through
    float
    Returns the duration of this audio asset in seconds.
    com.badlogic.gdx.files.FileHandle
    Returns the file that generated this asset.
    boolean
    getLooping(long soundId)
    Returns the loop setting of the given instance
    float
    getPan(long soundId)
    Returns the pan value of the given instance
    float
    getPitch(long soundId)
    Returns the pitch of the given instance
    float
    getPosition(long soundId)
    Returns the current position of this instance in seconds.
    int
    Returns the number of audio samples (per channel) per second.
    float
    getVolume(long soundId)
    Returns the volume of the given instance
    boolean
    Returns true if this is a mono audio asset.
    boolean
    isPlaying(long soundId)
    Returns true if the given instance is actively playing
    void
    removeEffect(long soundId, EffectFilter effect)
    Removes the effect that this instance is played through.
    void
    setLooping(long soundId, boolean looping)
    Sets the loop setting of the given instance
    void
    Registers a callback invoked as a sound instance completes.
    void
    setPan(long soundId, float pan)
    Sets the pan of the given instance
    void
    setPosition(long soundId, float seconds)
    Sets the current position of this instance in seconds.
    void
    setVolume(long soundId, float volume)
    Sets the volume of the given instance

    Methods inherited from interface com.badlogic.gdx.audio.Sound

    dispose, loop, loop, loop, pause, pause, play, play, play, resume, resume, setPan, setPitch, stop, stop
  • Method Details

    • setOnCompletionListener

      void setOnCompletionListener(SoundEffect.OnCompletionListener listener)
      Registers a callback invoked as a sound instance completes.
      Parameters:
      listener - The callback that will be run.
    • getFile

      com.badlogic.gdx.files.FileHandle getFile()
      Returns the file that generated this asset.

      The currently supported formats are WAV, MP3 and OGG.

      Returns:
      the file that generated this asset.
    • isMono

      boolean isMono()
      Returns true if this is a mono audio asset.

      LibGDX only supports mono and stereo audio assets. It does not support complex multi-channel assets (such as 7.1 surround).

      Returns:
      true if this is a mono audio asset.
    • getSampleRate

      int getSampleRate()
      Returns the number of audio samples (per channel) per second.
      Returns:
      the number of audio samples (per channel) per second.
    • getDuration

      float getDuration()
      Returns the duration of this audio asset in seconds.
      Returns:
      the duration of this audio asset in seconds.
    • isPlaying

      boolean isPlaying(long soundId)
      Returns true if the given instance is actively playing

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method returns false.

      Parameters:
      soundId - The playback instance
      Returns:
      true if the given instance is actively playing
    • getVolume

      float getVolume(long soundId)
      Returns the volume of the given instance

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method returns -1.

      Parameters:
      soundId - The playback instance
      Returns:
      the volume of the given instance
    • setVolume

      void setVolume(long soundId, float volume)
      Sets the volume of the given instance

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method does nothing

      Specified by:
      setVolume in interface com.badlogic.gdx.audio.Sound
      Parameters:
      soundId - The playback instance
      volume - The new volume
    • getLooping

      boolean getLooping(long soundId)
      Returns the loop setting of the given instance

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method returns false.

      Parameters:
      soundId - The playback instance
      Returns:
      the loop setting of the given instance
    • setLooping

      void setLooping(long soundId, boolean looping)
      Sets the loop setting of the given instance

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method returns false.

      Specified by:
      setLooping in interface com.badlogic.gdx.audio.Sound
      Parameters:
      soundId - The playback instance
      looping - Whether to loop the audio
    • getPitch

      float getPitch(long soundId)
      Returns the pitch of the given instance

      The pitch multiplier is value between 0.5 and 2.0, where 1 is unchanged, > 1 is faster, and < 1 is slower.

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method returns 1.

      Parameters:
      soundId - The playback instance
      Returns:
      the pitch of the given instance
    • setPan

      void setPan(long soundId, float pan)
      Sets the pan of the given instance

      The pan is a value -1 to 1. The value 0 is the default center position. -1 is full left and 1 is full right.

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method has no effect.

      Parameters:
      soundId - The playback instance
      pan - The pan value -1 (left) to 1 (right). Use 0 for center.
    • getPan

      float getPan(long soundId)
      Returns the pan value of the given instance

      The pan is a value -1 to 1. The value 0 is the default center position. -1 is full left and 1 is full right.

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method returns 0.

      Parameters:
      soundId - The playback instance
      Returns:
      the pan value of the given instance
    • getPosition

      float getPosition(long soundId)
      Returns the current position of this instance in seconds.

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method returns -1.

      Parameters:
      soundId - The playback instance
      Returns:
      the current position of this instance in seconds.
    • setPosition

      void setPosition(long soundId, float seconds)
      Sets the current position of this instance in seconds.

      The sound id should be one given by Sound.play() or Sound.play(float). If the sound id is not valid, this method has no effect. A value outside of the bounds of the assets sets the position to the appropriate end point.

      Parameters:
      soundId - The playback instance
      seconds - The current position of this instance in seconds.
    • addEffect

      void addEffect(long soundId, EffectFilter effect)
      Sets the effect that this instance is played through
      Parameters:
      soundId - The playback instance
      effect - the effect to add
    • removeEffect

      void removeEffect(long soundId, EffectFilter effect)
      Removes the effect that this instance is played through.
      Parameters:
      soundId - The playback instance
      effect - the effect to remove