The Audio Class - Hangman/TuningFork GitHub Wiki

Before any function of TuningFork can be called, the Audio class must be initialized. Only one Audio instance may exist at any time. The returned Audio instance is null in case of an initialization failure.

Audio audio = Audio.init();

AudioConfig config = new AudioConfig();
config.setDistanceAttenuationModel(DistanceAttenuationModel.INVERSE_DISTANCE);
config.setIdleTasks(numberOfIdleTasks); 
config.setSimultaneousSources(numberOfSimultaneousSources);
config.setLogger(new YourLogger());
config.getDeviceConfig().deviceSpecifier = "yourAudioDevice";
Audio audio = Audio.init(config);

Acoustic attenuation is a measure of the energy loss of sound propagation in media. The farther the listener is from the sound source, the quieter it appears. How attenuation is calculated can be changed.

Changing the attenuation model will take effect immediately, it also overwrites the current default values for the attenuation factor as well as the min and max attenuation distance. However, obtained audio sources and existing StreamedSoundSources stay unaffected by these new default values.

audio.setDistanceAttenuationModel(DistanceAttenuationModel.INVERSE_DISTANCE)

The min distance value defines how far away the listener must be from the sound source for the attenuation to kick in.

audio.setDefaultAttenuationMinDistance(1f);

The max distance value defines how far away the listener must be from the sound source for the attenuation to stop. With almost all DistanceAttenuationModels this does not mean that the sound is no longer audible from there on. The volume of the sound merely remains the same. With the linear model, however, it means that the sound is no longer audible.

audio.setDefaultAttenuationMaxDistance(100f);

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.

audio.setDefaultAttenuationFactor(0.5f);

A general volume value that affects all sound sources and is therefore global.
Range: 0.0 - 1.0

audio.setMasterVolume(1f);

Changing the doppler factor exaggerates or deemphasizes 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 greater than 1 will increase the strength of the doppler effect.

audio.setDopplerFactor(1f);

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

BufferedSoundSource mySource = audio.obtainSource(sound);

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

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.

mySource.free();

Audio offers methods to stop, pause and resume all sound sources (except PcmSoundSources) at once. This can be helpful if you want to switch to a pause mode, for example. Resume will only make sound sources play again, that were paused earlier.

audio.stopAll();
audio.pauseAll();
audio.resumeAll();

There are also methods to stop, pause or resume only buffered or streamed sound sources.

audio.stopAllStreamedSources();
audio.stopAllBufferedSources();

audio.pauseAllStreamedSources();
audio.pauseAllBufferedSources();

audio.resumeAllStreamedSources();
audio.resumeAllBufferedSources();

If a sounds sample rate doesn't match the devices sample rate, it needs to be resampled. This is done automatically. However, there's different resampling techniques available depending on the hardware. If you don't want to let OpenAL decide for you, you can set a default resampling technique in TuningFork. Since what's available depends on the hardware, you have to ask the device what it provides first.

AudioDevice device = audio.getDevice();
Array<String> availableResamplers = device.getAvailableResamplers();

This list is ordered by performance impact. That is, indices closer to 0 are of lower impact, and the higher index values have higher impact. Mostly, a higher performance impact also means a better result in terms of quality, though this isn't true in all cases.
If you need more information on what resampler is best for you, here's a video recommendation: https://www.youtube.com/watch?v=62U6UnaUGDE

And finally, to set a default resampler:

String resampler = availableResamplers.get(0); // pick an appropriate resampler here
audio.setDefaultResampler(resampler);

Note: This will affect all sources immediately, regardless of their state (playing, obtained, paused, etc.), potentially overwriting a resampler that you set on a source directly. Also, all sources that are created afterwards will be initialized with the new resampler.

If you want to shutdown TuningFork, you have to call dispose() on Audio. Note that you should have all sound resources disposed before calling dispose on audio.

// clean up resources first
mySoundBuffer.dispose();
myStreamedSoundSource.dispose();
...

// finally close TuningFork
audio.dispose();