hangman / tuningfork

Advanced 3D audio features for libGDX desktop users.

TuningFork

Introduction

TuningFork is a library for libGDX that provides advanced audio features. The goal was to make most of the features of OpenAL Soft accessible and provide a comfortable, easy to use, low overhead and object oriented high-level API. In addition, the library offers some convenience features that are needed for most games, such as the music player.
Note that TuningFork is not an extension to libGDX audio but a replacement.

Main Features

• Spatial 3D and 2D audio
• Directional audio (3D)
• Real-time effects such as Reverb, Echo, Flanger, Distortion (and many more)
• Loop-points
• Filters
• HRTF
• Music player with support for playlists and fading
• Streaming is handled on a background thread
• AssetManager integration
• Play raw PCM data
• Record audio

Supported Formats

This library widens the range of supported audio formats compared to libGDX, such as 8-Bit / 24-Bit / 32-Bit wav's, IMA and MS ADPCM, surround sound, just to name a few. Here's the full list.

• wav
• ogg
• mp3
• flac
• aiff
• qoa

Limitations

• Desktop only

I didn't want to make any compromises by finding the lowest common denominator between platforms and instead give access to the full feature-set of OpenAL Soft + more.

Install

Add TuningFork as a dependency to your project (I recommend to add it in the core project if you develop for desktop only):

implementation 'com.github.Hangman:TuningFork:4.3.0'

Compatibility

Java 8 is required, make sure to set sourceCompatibility = JavaLanguageVersion.of(8) (or higher) in your gradle scripts.

Version of libGDX	Latest compatible version of TuningFork
1.12.1	4.3.0
1.12.0	4.1.0
1.9.12 - 1.11.0	3.3.0
1.9.11	2.0.1
< 1.9.11	not supported, might work though: 2.0.1

Upgrading

This library follows semantic versioning. Breaking changes are indicated by a major version increase.
You can find the release notes here.

Getting Started

The wiki should provide all the information you need to get started quickly. If something is missing, please open an issue.
Link to the Wiki!

Building From Source

To build the library from source, you need a JDK >= 8 installed. You can grab one here: Liberica JDK.
TuningFork uses Gradle as it's build tool (you don't need to have Gradle installed).

This will compile the library. The resulting jar can be found under core/build/libs/.

./gradlew build

This will publish the core artifact to your local Maven repository.

./gradlew publishToMavenLocal

tuningfork's Issues

TuningFork:4.2.0 - AudioDevice#disableHrtf() throws exception

Enabling HRTF works, but the disable method crashes with

Caused by: java.lang.IllegalArgumentException: Missing termination

	at org.lwjgl.system.Checks.checkNTSafe(Checks.java:275)
	at org.lwjgl.openal.SOFTHRTF.alcResetDeviceSOFT(SOFTHRTF.java:130)
	at de.pottgames.tuningfork.AudioDevice.disableHrtf(AudioDevice.java:488)

Changing method code to

public void disableHrtf() {
        if (this.isHrtfSupported()) {
            // SET NEW DEVICE ATTRIBUTES
            final ContextAttributes oldAttributes = this.contextAttributes;
            final int[] attributes = new int[9];
            attributes[0] = SOFTHRTF.ALC_HRTF_SOFT;
            attributes[1] = ALC10.ALC_FALSE;
            attributes[2] = EXTEfx.ALC_MAX_AUXILIARY_SENDS;
            attributes[3] = this.config.getEffectSlots();
            attributes[4] = SOFTOutputLimiter.ALC_OUTPUT_LIMITER_SOFT;
            attributes[5] = this.config.isEnableOutputLimiter() ? ALC10.ALC_TRUE : ALC10.ALC_FALSE;
            attributes[6] = SOFTOutputMode.ALC_OUTPUT_MODE_SOFT;
            attributes[7] = this.config.getOutputMode().getAlId();
            attributes[8] = 0;
            this.contextAttributes = new ContextAttributes(attributes);

            // RESET DEVICE
            if (SOFTHRTF.alcResetDeviceSOFT(this.deviceHandle, attributes)) {
                this.hrtfEnabled = false;
                this.logger.info(this.getClass(), "HRTF disabled.");
            } else {
                this.contextAttributes = oldAttributes;
                this.logger.error(this.getClass(), "Failed to reset device: " + ALC10.alcGetString(this.deviceHandle, ALC10.alcGetError(this.deviceHandle)));
            }
        } else {
            this.logger.warn(this.getClass(), "HRTF is not supported by this device and was therefore never enabled.");
        }
    }

seems to fix the issue (Tried this with reflection), but I'm not sure if this solution is the correct one.

My dependencies are TuningFork:4.2.0, libgdx:1.12.1 and lwjgl-openal:3.3.3, running on MacOS 10.15.7

Filter only works for really small values.

When using

• filter.setLowFrequencyVolume(float volume)
• filter.setHighFrequencyVolume(float volume)

there isn't any audible change for values of volume 0.2 - 1.0.
Only for very small values the relevant frequencies seem to get turned down.

Error when applying SoundEffect

Hi I tried to apply a Reverb effect to my soundsource like this:

        soundSource = audio.obtainSource(sound)
        soundSource.setRelative(true)
        soundSource.setLooping(true)

        var effect = SoundEffect(Reverb())
        soundSource.attachEffect(effect)

        soundSource.play()

But then I get this error:
failed to access class de.pottgames.tuningfork.SoundEffectData from class com.alfredo.games.FirstScreen (de.pottgames.tuningfork.SoundEffectData and com.alfredo.games.FirstScreen are in unnamed module of loader 'app')
Maybe I just messed up something in Intellij because i followed the examples exactly like in the wiki.

Duration resolution is inaccurate for MS ADPCM in an AL buffer

TuningFork/core/src/main/java/de/pottgames/tuningfork/SoundBuffer.java

Lines 139 to 144 in bbc9d21

	protected float calculateDuration(int bytes, int bitsPerSample, int channels, int sampleRate) {
	// FIXME: fetch duration from OpenAL using AL_SOFT_buffer_length_query extension when the bindings got added https://github.com/LWJGL/lwjgl3/issues/885
	// the current calculation is okay but not 100% precise with compressed audio data
	final float samplesPerChannel = bytes / (bitsPerSample / 8f * channels);
	return samplesPerChannel / sampleRate;
	}

We are waiting for libGDX to update to lwjgl 3.3.3!

Alternatively, we could fetch the duration from the decoder, but I think it's cleaner to have this one-for-all-solution via AL.

changing theme in jukebox not working at runtime, but does work while debugging

I have the following code

	case MUSIC_CHANGE_THEME:
		provider.setTheme(audioData.getTheme());
		jukeBox.softStopAndResume(Interpolation.linear, 2f);
		break;

When i play my game normally the song does not change.
When I put a debug point here

    /**
     * Updates the JukeBox. This method should be called every frame.
     */
    public void update() {
        if (this.stopped) {
            this.handleEvents();
            return;
        }

        SongSource source = null;
        SongSettings settings = null;
        if (this.currentSong != null) {
            source = this.currentSong.getSource();
            settings = this.currentSong.getSettings();
        }

        if (source != null && source.isPlaying()) {
            final float fadeVolume = this.determineFadeVolume(source, settings);
            if (this.softStop) {
                this.softStopFade(source);  =====> HERE IS THE DEBUG POINT
            } else {
                source.setVolume(fadeVolume);
            }
        } else {
            this.resetSoftStop(true);
            this.eventSongEnd = this.currentSong;
            this.nextSong();
        }

        this.handleEvents();
    }

Then the debugger stops there and at that line the music stops and it changes to another song.
Do you have any explanation for this?

Add support for ALC_SOFT_pause_device

Reminder for myself.
https://openal-soft.org/openal-extensions/SOFT_pause_device.txt

Implement event listener

Reminder for myself.
https://openal-soft.org/openal-extensions/SOFT_events.txt
Implement listener interfaces once libGDX runs on LWJGL 3.3.0, which is using AL Soft 1.21.1.

FLAC 8-Bit

There is currently a problem with the playback of 8-bit FLAC data. The FLAC decoder spits out signed bytes, but OpenAL expects unsigned bytes.

Question: Smart limiting/grouping of 2D spatial sound instances

Hi, I'm looking for a sound library and this one seems pretty cool since I am using the jwgl3 backend anyways.
I have a small question whether this library supports an easy way to (smartly) limit/group multiple spatial 2d sound emitters?
In my use case i have a 2d game where there are enemies (spiders) which emit a constant looping movement sound (crawling).
There can be tens of spiders in a level. Of course I don't want to play the same looped sounds tens of times because it sounds awful.
I would like there to only be like 2-4 instances, depending on where the spiders are located.
E.g. if there are multiple spiders left and right of the player, it should only play one 2d sound on the left, and one on the right, etc.
The grouping/limit should also update when the player moves.
Right now I only have a very naive sound instance limitation, which can cause problems with many spiders because only certain spiders emit sounds and it's not consistent, especially when moving around.
Is there any easy way to achieve this with this library?

Add support for AL_SOFT_loop_points

Reminder for myself.
https://openal-soft.org/openal-extensions/SOFT_loop_points.txt