Using the OpenAudioMc API through Maven

Blue pill	Red Pill
Pull from JitPack. Wait for it to compile, and just use it out of the box. Nothing to mess with (which is fine)	This pill is the size of a large pumpkin and it goes in your ass. Install libraries, build from source, know everything

amazing quote from justcallmekoko/ESP32Marauder

Blue Pill (easy)

Add the jitpack repository:

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

And then the dependency, the version should be a git commit on master.

<dependency>
    <groupId>com.github.Mindgamesnl</groupId>
    <artifactId>OpenAudioMc</artifactId>
    <version>962246e169</version>
    <scope>provided</scope>
</dependency>

Red Pill (from source)

1. Clone https://github.com/Mindgamesnl/OpenAudioMc.git
2. CD into the openaudio directory
3. Run mvn clean install -DskipTests=true

then include it locally, with the release version you just installed

<dependency>
    <groupId>com.craftmend.openaudiomc</groupId>
    <artifactId>openaudiomc</artifactId>
    <version>6.8.2</version>
    <scope>provided</scope>
</dependency>

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. The following example shows you how to cancel voice chat for certain users:

AudioApi.getInstance().getEventDriver()
    // subscribe to an event
    .on(ClientRequestVoiceEvent.class)
    // 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, therefore blocking voice chat
            event.setCanceled(true);
        }
    });

Available events

OpenAudioMc has a few events built-in, these are:

• ClientConnectEvent: Fires when a client opens the web client, this is supported on all platforms.
• ClientDisconnectEvent: Fires when a client closes the web client, this is supported on all platforms.
• ClientRequestVoiceEvent: A cancellable event that gets fired when a voice chat session is initializing. This only fires on the top-level server.
• ClientErrorEvent: Event that fires when the client encounters a media error (http failure when trying to load a media sound). This only fires on the top-level server.
• StateChangeEvent: Fires whenever the plugin changes state (idle, online, fatal error, etc.). This only fires on the top-level server.
• AccountAddTagEvent: Fires whenever the server receives a new module/add-on or update from the owning Craftmend Account (example, VOICE_CHAT).
• AccountRemoveTagEvent: Mirror opposite of the AccountAddTagEvent.
• MicrophoneMuteEvent: Fires when a player mutes their microphone.
• MicrophoneUnmuteEvent: Fires when a player unmutes their microphone (and when it activates for the first time).
• PlayerEnterVoiceProximityEvent: Fires when player A joins the voice range of player B.
• PlayerLeaveVoiceProximityEvent: Fires when player A leaves the voice range of player B.
• PlayerLoudnessEvent: Fires when the speaking loudness of a player changes (between normal, whispering and shouting).
• ClientPreAuthEvent: A cancellable event that fires whenever a web client attempts to log in. Canceling the event will block the login.
• VoiceChatPeerTickEvent: This event fires before AND after voice chat peer updates (it has a variable letting you know if it was pre-or post).
• SystemReloadEvent: Called whenever the plugin reloads completely or updates state.
• ConfigurationPushEvent: Fires whenever a new version of the config.yml is loaded through networking, migrations or perhaps redis. It contains the (supposedly) yaml file content as a string.

These events allow you to perform actions based on what is happening within the plugin. To use them, you can access an instance of the event driver and subscribe to specific events, as demonstrated in the previous code block

Interacting with the 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, "files:mysong.mp3");

But we can get a lot more creative than 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();
options.setLoop(true);
options.setId("example");
options.setVolume(50);
api.getMediaApi().playMedia(client, "files:mysong.mp3", options);

Stopping a sound

Stopping sounds is even simpler. We can stop all normal sounds through:

api.getMediaApi().stopMedia(client);

Or stop a single sound with the ID “example” with:

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

Using Spatial Audio

In addition to regular audio, OpenAudioMc also supports spatial audio, which can be used to create immersive 3D sound effects. To create a 3D spatial sound, you can use the following code:

String spatialSoundId = api.getMediaApi().playSpatialSound(client, "https://example.com/a.mp3", x, y, z, 10, true);

This will play a spatial sound with the given URL at the location (x, y, z) for the specified player client. The last two arguments determine the maximum radius (in blocks) for the sound and whether it should be a 3D sound (set to true). The method returns a unique identifier for the spatial sound, which can be used to stop it later:

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

Full API interfaces

Please visit GitHub for the most recent and full list of API methods and their javadoc:

• RegistryApi - GitHub file - Responsible for internal handlers and mutators
• MediaApi - GitHub file - Responsible for media playback
• Client - GitHub file - Represents a web client
• WorldApi - GitHub file - Responsible for world interactions such as regions and speakers