The Basics

Here we'll go over the basics of TuningFork. The topics are partly redundant and will be explained in more detail elsewhere in the wiki. However, this article should make sure that it covers everything you need to know to get started.

Initialization

The first thing you always need to do is disabling audio in libGDX, so TuningFork can take over. Open up the DesktopLauncher (Lwjgl3Launcher in liftoff projects) and add this to your Lwjgl3ApplicationConfiguration:

config.disableAudio(true);

The whole class could then look like this:

public class DesktopLauncher {
    public static void main (String[] arg) {
        Lwjgl3ApplicationConfiguration config = new Lwjgl3ApplicationConfiguration();
        config.disableAudio(true);
        new Lwjgl3Application(new MyGdxGame(), config);
    }
}

Initialize Audio

First, you need to initialize TuningFork and get a handle on the Audio class. Add the audio variable to your main class and put the init code into the create method.

private Audio audio;

@Override
public void create() {
    audio = Audio.init();
}

This will initialize TuningFork with default settings. More information on different initialization methods and settings here: The Audio Class

Loading Sounds

For sounds that should be loaded completely into memory:

SoundBuffer wavSound = SoundLoader.load(Gdx.files.internal("sound.wav"));
SoundBuffer oggSound = SoundLoader.load(Gdx.files.internal("sound.ogg"));
SoundBuffer flacSound = SoundLoader.load(Gdx.files.internal("sound.flac"));
SoundBuffer mp3Sound = SoundLoader.load(Gdx.files.internal("sound.mp3"));
SoundBuffer aiffSound = SoundLoader.load(Gdx.files.internal("sound.aiff"));
SoundBuffer qoaSound = SoundLoader.load(Gdx.files.internal("sound.qoa"));

We won't cover asynchronous loading in this article. More information here: Loading/Unloading Sounds

Playing via Fire & Forget

Fire & Forget sounds are sounds you want to play but not modify while they play.

// available 2D sound playback methods
sound.play();
sound.play(effect);
sound.play(volume);
sound.play(volume, filter);
sound.play(volume, effect);
sound.play(volume, pitch);
sound.play(volume, pitch, filterLow, filterHigh);
sound.play(volume, pitch, pan);
sound.play(volume, pitch, pan, effect);

// available 3D sound playback methods
sound.play3D(position);
sound.play3D(position, filter);
sound.play3D(position, effect);
sound.play3D(position, filter, effect);
sound.play3D(volume, position);
sound.play3D(volume, position, filterLow, filterHigh);
sound.play3D(volume, position, effect);
sound.play3D(volume, pitch, position);
sound.play3D(volume, pitch, position, effect);

More information about playing via fire & forget here.

Playing via SoundSource

In order to manipulate a sound while playing, you must obtain a sound source instance first.

BufferedSoundSource soundSource = audio.obtainSource(wavSound);

// now you can call whatever you need on the sound source
soundSource.setRelative(true);
soundSource.setVolume(0.5f);
soundSource.setPitch(0.7f);
soundSource.play();

Here is an excerpt of the methods that sound sources provide:

• play
• pause
• stop
• setVolume
• setFilter
• setPitch
• setLooping
• setPosition
• setSpeed
• isPaused
• isPlaying
• getDuration
• attachEffect

After you're done using the sound source, you must call "free" on it, in order to release it back to the pool of available sound sources.

soundSource.free();

More information here: Sound Sources

Streaming sounds

Streaming is especially useful for long sounds like music that you don't want to keep entirely in memory.

// load
StreamedSoundSource source = new StreamedSoundSource(Gdx.files.internal("music.ogg"));

// a StreamedSoundSource is an implementation of a SoundSource, so you get all the features you already know from the BufferedSoundSource
source.setVolume(0.5f);
source.setLooping(true);
source.play();

Because this source loads resources, you need to dispose it when no longer needed:

source.dispose();

The Listener

The listener is your head with two ears and therefore determines the sound output from spatial sound sources by its position, orientation and speed.
Get The Listener:

SoundListener listener = audio.getListener();

You can update its position, orientation and speed. The speed is only used to simulate a Doppler-effect.

listener.setPosition(position);
listener.setOrientation(at, up);
listener.setSpeed(speed);

// or for simplicity:
listener.setPosition(position).setOrientation(at, up).setSpeed(speed);

More information here: Sound Listener

Applying Effects

First you need to create an effect. We use the reverb effect in this example. You can then attach it to a source:

SoundEffect effect = new SoundEffect(new Reverb());
soundSource.attachEffect(effect);

More information here: Sound Effects

Applying Filters

Filters provide a simple way to filter out high or low frequencies.

soundSource.setFilter(1f, 0f); // lets low frequencies pass, fully blocks high frequencies in this example

More information here: Filters

Unloading and shutdown

Like other resources in libGDX, some TuningFork resources need to be disposed when no longer needed. You need to dispose these classes manually:

• SoundBuffer
• StreamedSoundSource
• PcmSoundSource
• SoundEffect
• Audio
• CaptureDevice

Example code:

effect1.dispose();
effect2.dispose();
soundBuffer1.dispose();
streamedSound1.dispose();

// make sure to always dispose Audio last
audio.dispose();