Class Audio

java.lang.Object
de.pottgames.tuningfork.Audio
All Implemented Interfaces:
com.badlogic.gdx.utils.Disposable
public class Audio extends Object implements com.badlogic.gdx.utils.Disposable
The main management and entry point of TuningFork. This class initializes the sound device and gives access to SoundSource's for advanced manual playback control.

  • Method Details

    • init

      public static Audio init()
      Initializes an Audio instance with the default AudioConfig. Errors are logged but exceptions are silently ignored. Call initSafe(AudioConfig) instead, if you want to handle exceptions.
      Returns:
      the initialized Audio instance or null on failure

    • initSafe

      public static Audio initSafe() throws OpenDeviceException, UnsupportedAudioDeviceException
      Initializes an Audio instance with the default AudioConfig. If you don't want to take care of exceptions, call init(AudioConfig) instead.
      Returns:
      the initialized Audio instance
      Throws:
      OpenDeviceException - is thrown when a device couldn't be opened
      UnsupportedAudioDeviceException - is thrown when the desired device couldn't be found or isn't a valid device

    • init

      public static Audio init(AudioConfig config)
      Initializes an Audio instance with the given AudioConfig. Errors are logged but exceptions are silently ignored. Call initSafe(AudioConfig) instead, if you want to handle exceptions.
      Parameters:
      config - the audio config
      Returns:
      the initialized Audio instance or null on failure

    • initSafe

      public static Audio initSafe(AudioConfig config) throws OpenDeviceException, UnsupportedAudioDeviceException
      Initializes an Audio instance with the given AudioConfig. If you don't want to take care of exceptions, call init(AudioConfig) instead.
      Parameters:
      config - the audio config
      Returns:
      the initialized Audio instance
      Throws:
      OpenDeviceException - is thrown when a device couldn't be opened
      UnsupportedAudioDeviceException - is thrown when the desired device couldn't be found or isn't a valid device

    • get

      public static Audio get()
      Returns the currently active instance of Audio.
      Returns:
      the instance

    • getDevice

      public AudioDevice getDevice()
      Returns the currently used AudioDevice.
      Returns:
      the device in charge

    • setDistanceAttenuationModel

      public void setDistanceAttenuationModel(DistanceAttenuationModel model)
      As the listener moves away from a sound source, the volume of the sound source decreases for the listener. The Attenuation Model is responsible for this calculation.

      Note: Setting a DistanceAttenuationModel overwrites the default min and max attenuation distance as well as the attenuation factor that is used for new sound sources. It won't affect existing ones.

      There are several models to choose from, including a linear model and a semi-realistic model based on the real world. By default the INVERSE_DISTANCE_CLAMPED model is used.
      Parameters:
      model - the model

    • setDefaultAttenuationMinDistance

      public void setDefaultAttenuationMinDistance(float distance)
      Sets the distance the listener must be from the sound source at which the attenuation should begin. The attenuation itself is controlled by the attenuation model and the attenuation factor of the source. This value is used for all sources that are created/obtained afterwards, it doesn't affect existing or already obtained sources. If you want to set this per source, you can do so: SoundSource.setAttenuationMinDistance(float).
      Parameters:
      distance - (default depends on the attenuation model)

    • setDefaultAttenuationMaxDistance

      public void setDefaultAttenuationMaxDistance(float distance)
      Sets the distance the listener must be from the sound source at which the attenuation should stop. The attenuation itself is controlled by the attenuation model and the attenuation factor of the source. This value is used for all sources that are created/obtained afterwards, it doesn't affect existing or already obtained sources. If you want to set this per source, you can do so: SoundSource.setAttenuationMaxDistance(float).
      Parameters:
      distance - (default depends on the attenuation model)

    • setDefaultAttenuationFactor

      public void setDefaultAttenuationFactor(float rolloff)
      This factor determines how slowly or how quickly the sound source loses volume as the listener moves away from the source. A factor of 0.5 reduces the volume loss by half. With a factor of 2, the source loses volume twice as fast. This factor is used for all sources that are created/obtained afterwards, it doesn't affect existing or already obtained sources. If you want to set this per source, you can do so: SoundSource.setAttenuationFactor(float).
      Parameters:
      rolloff - (default depends on the attenuation model)

    • getDefaultAttenuationMinDistance

      public float getDefaultAttenuationMinDistance()
      Returns the default attenuation minimum distance that is used to calculate the attenuation by the current default attenuation model.
      Returns:
      the default attenuation min distance

    • getDefaultAttenuationMaxDistance

      public float getDefaultAttenuationMaxDistance()
      Returns the default attenuation maximum distance that is used to calculate the attenuation by the current default attenuation model.
      Returns:
      the default attenuation max distance

    • getDefaultAttenuationFactor

      public float getDefaultAttenuationFactor()
      Returns the default attenuation factor that is used to calculate the attenuation by the current default attenuation model.
      Returns:
      the default attenuation factor

    • getDefaultVirtualization

      public AudioConfig.Virtualization getDefaultVirtualization()
      Returns whether virtualization is enabled or disabled by default for all sound sources. See AudioConfig.setVirtualization(Virtualization) for more info.
      Returns:
      the virtualization method

    • setDefaultVirtualization

      public void setDefaultVirtualization(AudioConfig.Virtualization virtualization)
      Immediately sets the virtualization method for all sound sources, regardless of their state (playing, paused, obtained, etc.).
      Sources that are created afterward are also initialized with the new default virtualization method.
      Unless you have a specific reason to change this at runtime, it's recommended to set the default via AudioConfig on init(AudioConfig).

      See AudioConfig.Virtualization for the different options available.
      Parameters:
      virtualization - the virtualization

    • getDefaultSpatialization

      public AudioConfig.Spatialization getDefaultSpatialization()

    • setDefaultSpatialization

      public void setDefaultSpatialization(AudioConfig.Spatialization spatialization)

    • getMasterVolume

      public float getMasterVolume()
      Returns the global volume value that is applied to all sources.
      Returns:
      the master volume in the range: 0 - 1

    • setMasterVolume

      public void setMasterVolume(float volume)
      Sets the global volume that is applied to all sources. Values above 1 or below 0 will be clamped.
      Parameters:
      volume - range: 0 - 1

    • setDopplerFactor

      public void setDopplerFactor(float dopplerFactor)
      Changing the doppler factor exaggerates or de-emphasizes the doppler effect. Physically accurate doppler calculation might not give the desired result, so changing this to your needs is fine. The default doppler factor is 1. Values < 0 are ignored, 0 turns the doppler effect off, values > 1 will increase the strength of the doppler effect.
      Parameters:
      dopplerFactor - (default 1)

    • obtainSource

      public BufferedSoundSource obtainSource(SoundBuffer buffer)
      Returns a BufferedSoundSource for permanent use. Call free() on it to return it to the pool of available sources.
      Parameters:
      buffer - the sound buffer
      Returns:
      the BufferedSoundSource

    • play

      protected void play(SoundBuffer buffer)
      Plays the sound.
      Parameters:
      buffer - the sound buffer

    • playAtTime

      protected void playAtTime(SoundBuffer buffer, long time)
      Plays the sound at the specified time. Negative values for time will result in an error log entry but do nothing else. Positive values that point to the past will make the source play immediately. The source will be in playing-state while waiting for the start time to be reached.
      Parameters:
      buffer - the sound buffer
      time - the time in nanoseconds, use AudioDevice.getClockTime() to get the current time

    • play

      protected void play(SoundBuffer buffer, SoundEffect effect)
      Plays a sound with an effect.
      Parameters:
      buffer - the sound buffer
      effect - the sound effect

    • play

      protected void play(SoundBuffer buffer, float volume)
      Plays the sound with the given volume.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)

    • play

      protected void play(SoundBuffer buffer, float volume, SoundEffect effect)
      Plays the sound with the given volume and effect.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      effect - the sound effect

    • play

      protected void play(SoundBuffer buffer, float volume, float pitch)
      Plays the sound with the given volume and pitch.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      pitch - in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster (default 1)

    • play

      protected void play(SoundBuffer buffer, float volume, float pitch, float lowFreqVolume, float highFreqVolume)
      Plays the sound with the given volume, pitch and filter.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      pitch - in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster (default 1)
      lowFreqVolume - the volume of low frequencies
      highFreqVolume - the volume of high frequencies

    • play

      protected void play(SoundBuffer buffer, float volume, float pitch, SoundEffect effect)
      Plays the sound with the given volume, pitch and effect.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      pitch - in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster (default 1)
      effect - the sound effect

    • play

      protected void play(SoundBuffer buffer, float volume, float pitch, float pan)
      Plays the sound with the given volume, pitch and pan.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      pitch - in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster (default 1)
      pan - in the range of -1.0 (full left) to 1.0 (full right). (default center 0.0)

    • play

      protected void play(SoundBuffer buffer, float volume, float pitch, float pan, SoundEffect effect)
      Plays the sound with the given volume, pitch, pan and effect.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      pitch - in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster (default 1)
      pan - in the range of -1.0 (full left) to 1.0 (full right). (default center 0.0)
      effect - the sound effect

    • play3D

      protected void play3D(SoundBuffer buffer, com.badlogic.gdx.math.Vector3 position)
      Plays a spatial sound at the given position.
      Parameters:
      buffer - the sound buffer
      position - the position in 3D space

    • play3D

      protected void play3D(SoundBuffer buffer, com.badlogic.gdx.math.Vector3 position, float lowFreqVolume, float highFreqVolume)
      Plays a spatial sound with the given filter at the given position.
      Parameters:
      buffer - the sound buffer
      position - the position in 3D space
      lowFreqVolume - the volume of low frequencies
      highFreqVolume - the volume of high frequencies

    • play3D

      protected void play3D(SoundBuffer buffer, com.badlogic.gdx.math.Vector3 position, SoundEffect effect)
      Plays a spatial sound at the given position with an effect.
      Parameters:
      buffer - the sound buffer
      position - the position in 3D space
      effect - the sound effect

    • play3D

      protected void play3D(SoundBuffer buffer, com.badlogic.gdx.math.Vector3 position, float lowFreqVolume, float highFreqVolume, SoundEffect effect)
      Plays a spatial sound at the given position with the given effect and filter.
      Parameters:
      buffer - the sound buffer
      position - the position in 3D space
      lowFreqVolume - the volume of low frequencies
      highFreqVolume - the volume of high frequencies
      effect - the sound effect

    • play3D

      protected void play3D(SoundBuffer buffer, float volume, com.badlogic.gdx.math.Vector3 position)
      Plays a spatial sound with the given volume at the given position.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      position - the position in 3D space

    • play3D

      protected void play3D(SoundBuffer buffer, float volume, com.badlogic.gdx.math.Vector3 position, float lowFreqVolume, float highFreqVolume)
      Plays a spatial sound with the given volume and filter at the given position.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      position - the position in 3D space
      lowFreqVolume - the volume of low frequencies
      highFreqVolume - the volume of high frequencies

    • play3D

      protected void play3D(SoundBuffer buffer, float volume, com.badlogic.gdx.math.Vector3 position, SoundEffect effect)
      Plays a spatial sound with the given volume and effect at the given position.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      position - the position in 3D space
      effect - the sound effect

    • play3D

      protected void play3D(SoundBuffer buffer, float volume, float pitch, com.badlogic.gdx.math.Vector3 position)
      Plays a spatial sound with the given volume and pitch at the given position.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      pitch - in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster (default 1)
      position - the position in 3D space

    • play3D

      protected void play3D(SoundBuffer buffer, float volume, float pitch, com.badlogic.gdx.math.Vector3 position, SoundEffect effect)
      Plays a spatial sound with the given volume, pitch and effect at the given position.
      Parameters:
      buffer - the sound buffer
      volume - in the range of 0.0 - 1.0 with 0 being silent and 1 being the maximum volume. (default 1)
      pitch - in the range of 0.5 - 2.0 with values < 1 making the sound slower and values > 1 making it faster (default 1)
      position - the position in 3D space
      effect - the sound effect

    • setDefaultResampler

      public boolean setDefaultResampler(String resampler)
      Immediately sets the resampler for all sound sources, regardless of their state (playing, paused, obtained, etc.).
      Sources that are created afterward are also initialized with the new default resampler.

      Check AudioDevice.getAvailableResamplers() for a list of available resamplers.
      Parameters:
      resampler - the resampler
      Returns:
      true if successful, false if the desired resampler isn't available

    • resumeAll

      public void resumeAll()
      Resumes to play all BufferedSoundSources and StreamedSoundSources that are paused.

    • resumeAllStreamedSources

      public void resumeAllStreamedSources()
      Resumes to play all StreamedSoundSources that are paused at the moment.

    • resumeAllBufferedSources

      public void resumeAllBufferedSources()
      Resumes to play all BufferedSoundSources that are paused at the moment.

    • pauseAll

      public void pauseAll()
      Pauses all BufferedSoundSources and StreamedSoundSources.

    • pauseAllStreamedSources

      public void pauseAllStreamedSources()
      Pauses all StreamedSoundSource.

    • pauseAllBufferedSources

      public void pauseAllBufferedSources()
      Pauses all BufferedSoundSources.

    • stopAll

      public void stopAll()
      Stops all BufferedSoundSources and StreamedSoundSources.

    • stopAllStreamedSources

      public void stopAllStreamedSources()
      Stops all StreamedSoundSources.

    • stopAllBufferedSources

      public void stopAllBufferedSources()
      Stops all BufferedSoundSources.

    • getListener

      public SoundListener getListener()
      Returns the SoundListener.
      Returns:
      the SoundListener

    • registerAssetManagerLoaders

      public void registerAssetManagerLoaders(com.badlogic.gdx.assets.AssetManager manager)
      Registers TuningFork's async loaders on libGDX's AssetManager. If you provided an AssetManager in the AudioConfig, loaders have been registered and you can skip this step.
      Parameters:
      manager - the libGDX asset manager

    • getWavDecoderProvider

      public WavDecoderProvider getWavDecoderProvider()
      Returns the wav decoder provider that is used by WavInputStream.
      Returns:
      the resampler provider

    • getLogger

      public TuningForkLogger getLogger()

    • isNativeDecodersAvailable

      public boolean isNativeDecodersAvailable()
      Returns true if the native decoders are available. Java decoders will be used as a fallback.
      Returns:
      native decoders available

    • dispose

      public void dispose()
      Shuts down TuningFork.
      Specified by:
      dispose in interface com.badlogic.gdx.utils.Disposable