Skip to the content second.

Java API

The OpenAudioMc Java API is split into three parts, these are

To get started, clone the github repository and build the latest release locally through maven, then add it in your project by adding the following to your pom


You can then obtain your api instance with

AudioApi api = AudioApi.getInstance();

Using events

OpenAudioMc has an internal event driver which is used to process requests and important state changes. You can access an instance of the driver to catch and process events yourself (this example shows you how to cancel voice chat for certain users)

        // subscribe to an event
        // what to do?
        .setHandler(event -> {
            // event is a dynamic instance from the on method

            // check if the name isn't Mindgamesnl
            if (event.getRequester().getPlayer().getName() != "Mindgamesnl") {
                // cancel the event, therefor blocking voice chat

OpenAudioMc has a few events build in, these are;

Getting a Client

A client object resembles the web-connection of a given player and contains api methods (like isConnected(), onConnect etc) and is used to specify a player in other API methods. You can request a Client by Player-UUID on both bungeecord and spigot, but note that it’ll only be available a few ticks after joining. Example for getting my own connection:

Client mindgamesnl = api.getClient(UUID.fromString("f0c8657b-f384-4df6-9d66-e9f36c36ce8a"));

We can also hook on connection events, which is as simple as

mindgamesnl.onConnect(() -> {
    // I opened the web client!

Playing a sound

Starting a simple sound is as easy as

api.getMediaApi().playMedia(client, "");

but we can get a lot more creative then that with media options (like setting a Sound ID, playback volume etc), which still is pretty simple, starting a looping sound at half volume with the id “example” would be like

MediaOptions options = new MediaOptions();
api.getMediaApi().playMedia(client, "", options);

Stopping sounds

Stopping sounds is even simpler, we can stop all normal sounds through


or stop a single sound with the ID “example” with

api.getMediaApi().stopMedia(client, "example");

Spatial Audio

Explosions are cool, but explosions that spook the living ghost out of someone are even cooler. OpenAudioMc supports spatial audio, and we can simply create it like this

String spatialSoundId = api.getMediaApi().playSpatialSound(client, "", x, y, z, 10, true);

This will start a 3D spatial sound at a given location for the player with a radius of 10 blocks. You can also just make a simple sound (so one that just does volume instead of 3D orientation by setting the mode to false, which is the last argument). the playSpatialSound method returns a string, which is the spatial-id for that player (and unique to that player). You can remove it again with

api.getMediaApi().stopSpatialSound(client, spatialSoundId);

Hooking into internal services and using dependency injection

Most of the internal codebase was re-written and refactored during the 6.5.5 update, where we migrated to a custom service manager with support for annotation based dependency injection, service abstraction and to provide pointer safety during reloads. The service manager is registered in the main OpenAudioMc class and is accessible through all platforms. The entire ecosystem consists of two main registration types types

There are a few ways to receive services, simplest one being the most common one, which is by just requesting the service manually. You can do this at any time through

// Get the current MyService instance, or initialize it if it isn't mapped yet
MyService myService = OpenAudioMc.getService(MyService.class);

Or you can alternatively use dependency injection using the @Inject annotation. This supports values and constructors.

Field example:

public class TestService extends Service {
    // inject the main openaudio instance
    private OpenAudioMc openAudioMc;
    public TestService() {
        // this module is being loaded
    public void onEnable() {
        // the injections have been done, so we can safely call this.openAudioMc

or through the constructor, like so

public class TestService extends Service {

    public TestService(OpenAudioMc openAudioMc, NetworkingService networkingService) {
        // both the 'openAudioMc' and 'networkingService' parameters will be injected during init


K/V Cache

Keeping track of all spatial ID’s can be a pain, so we can keep track of it with a simple map. You can just put and get player metadata via the map we provide with the getKeyValue method in Client