jarabica

jarabica

The jarabica package attempts to provide a type-safe, mildly object-oriented frontend to the OpenAL API. Currently, it uses the high-quality LWJGL bindings internally, and wraps them with a thin layer of short-lived immutable types for safety and efficiency. It strongly separates the API and implementation to allow for easy unit testing and mocking of code that calls OpenAL.

Features

• Type-safe OpenAL frontend.
• Strong separation of API and implementation to allow for switching to different bindings at compile-time.
• Strongly-typed interfaces with a heavy emphasis on immutable value types.
• Fully documented (JavaDoc).
• Example code included.
• High coverage test suite.
• OSGi-ready
• JPMS-ready
• ISC license.

Usage

The jarabica package works in the same manner as the OpenAL API, but with adjustments to make the API feel more like a Java API. Create a device factory from which to create devices. The device factory implementation chosen essentially decides which underlying OpenAL bindings will be used; currently, the only real implementation is based on LWJGL.

val devices = new JALWDeviceFactory();

Enumerate the available audio devices:

List<JADeviceDescription> deviceDescriptions = devices.enumerateDevices();

Inspect the list of returned devices, and select the one that is most appropriate to your application. Use the description of the device to open the device:

try (JADeviceType device = devices.openDevice(deviceDescriptions.get(0))) {
  ...
}

With the open device, it's necessary to create a context.

JAContextType context = device.createContext();

The context value follows the usual OpenAL thread-safety rules; a context must be made current on the current thread before any operations can be performed using it. Creating a context automatically makes it current on the calling thread.

The context value can then be used to create OpenAL sources and buffers in a manner familiar to anyone experienced with OpenAL.

try (var source = context.createSource()) {
  try (var buffer = context.createBuffer()) {
    ...
  }
}

Example Application

A demo application is included that demonstrates how to use the API correctly, and also demonstrates numerous extensions such as the ubiquitous EFX extension.