JOAL, OpenAL API Binding for Java™

Original document location

Git Repository

This project's canonical repositories is hosted on JogAmp.

Overview

The JOAL Project hosts a reference implementation of the Java bindings for OpenAL API, and is designed to provide hardware-supported 3D spatialized audio for applications written in Java.

This project also hosts the Sound3D Toolkit, a high level API for spatialized audio built on top of the OpenAL bindings. This toolkit is designed to provide access to all the features of OpenAL through an intuitive, easy to use, object-oriented interface.

JOAL is part of the JogAmp project.

The JogAmp project needs funding and we offer commercial support!
Please contact Göthel Software (Jausoft).

License

See LICENSE.txt.

Platform Support

JOAL is tested against OpenAL-Soft (github repo), the cross-platform, software implementation of the OpenAL 3D audio API.

See OpenAL-Soft environment variables and configuration example.

All JOAL platform builds contain a self-build native library of OpenAL-Soft, version v1.23.1 from our fork.

Our builds expose the following audio backends:

GNU/Linux

• PipeWire
• PulseAudio
• ALSA
• OSS
• SndIO (linked)
• WaveFile
• Null

Android/Linux

• PipeWire
• OpenSL
• WaveFile
• Null

Windows

• WinMM
• DirectSound
• WASAPI
• WaveFile
• Null

MacOS

• CoreAudio
• WaveFile
• Null

Build Requirements

This project has been built under Win32, GNU/Linux, Android/Linux and MacOS.

Check GlueGen's HowToBuild for basic prerequisites.

Additionally the following packages and tools have been used:

• All Systems:

  • See GlueGen's HowToBuild
  • OpenAL-Soft (github repo)

• Windows:

  • CMake 3.15.2
  • OpenAL Soft: Audio-Backends: WinMM, DirectSound, WASAPI, WaveFile, Null

• GNU/Linux:

  • cmake
  • OpenAL Soft: OpenAL: PipeWire, PulseAudio, ALSA, OSS, SndIO (linked), WaveFile, Null

     apt-get install cmake autoconf \
             libpipewire-0.3-dev \
             libpulse-dev libpulse0:amd64 libpulse0:i386 pulseaudio \
             libsndio-dev \
             libasound2-dev libasound2:amd64 libasound2:i386

On Debian 11 Bullseye, use bullseye-backports apt -t bullseye-backports install libpipewire-0.3-dev to have libpipewire-0.3>=0.3.23, i.e. version 0.3.65.

• Android/Linux:

  • cmake
  • OpenAL Soft: Audio-Backends: PipeWire, OpenSL, WaveFile, Null

• OSX

  • OSX 10.2 or later
  • OSX Developer Tools Xcode
  • CMake 3.15.2 https://cmake.org/download/ and install the commandline tools https://stackoverflow.com/questions/30668601/installing-cmake-command-line-tools-on-a-mac
  • OpenAL Soft: Audio-Backends: CoreAudio, WaveFile, Null

JOAL requires the GlueGen workspace to be checked out as a sibling directory to the joal directory. See GlueGen's HowToBuild https://jogamp.org/gluegen/doc/HowToBuild.html

Directory Organization:

make/           Build-related files and the main build.xml
src/            The actual source for the JOAL APIs.
src/test/       A couple of small tests
build/          (generated directory) Where the Jar and DLL files get built to
www/            JOAL project webpage files

GIT

JOAL can be build w/ openal-soft, which is a git submodule of JOAL. This is the default for our JogAmp build on all platforms.

Cloning [and pulling] JOAL incl. openal-soft can be performed w/ the option '--recurse-submodules'.

   > cd /home/dude/projects/jogamp/
   > git clone --recurse-submodules git://jogamp.org/srv/scm/joal.git
   > cd joal ; git pull --recurse-submodules

JOAL Build Instructions:

Change into the joal/make directory

   > cd /home/dude/projects/jogamp/make/

To clean:

   > ant clean

To build:

   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar

To build docs:

   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar javadoc

To test:

   > ant -Dtarget.sourcelevel=1.8 -Dtarget.targetlevel=1.8 -Dtarget.rt.jar=/your/openjdk8/lib/rt.jar runtests

Instead of properties, you may also use environment variables, see GlueGen's HowToBuild https://jogamp.org/gluegen/doc/HowToBuild.html.

Contact Us

• JogAmp http://jogamp.org/
• JOAL Web http://jogamp.org/
• Forum/Mailinglist http://forum.jogamp.org/
• Repository http://jogamp.org/git/
• Wiki https://jogamp.org/wiki/
• Maintainer https://jogamp.org/wiki/index.php/Maintainer_and_Contacts
• Sven's Blog https://jausoft.com/blog/tag/jogamp/
• Email sgothel at jausoft dot com

Acknowledgments

Original JOAL and Sound3D authors

• Athomas Goldberg
• Wildcard
• Java Games Initiative
• Software Advanced Technologies Group
• Sun Microsystems

Since roughly 2010, JOAL development has been continued by individuals of the JogAmp community, see git log for details.