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

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

You can then obtain your api instance with

AudioApi api = AudioApi.getInstance();

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, "https://example.com/a.mp3");

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();
options.setLoop(true);
options.setId("example");
options.setVolume(50);
api.getMediaApi().playMedia(client, "https://example.com/a.mp3", options);

Stopping sounds

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");

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, "https://example.com/a.mp3", 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);

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.

The rest

This just covers the basics but there’s a lot more you can do, please look in the Javadoc for more details at https://javadoc.openaudiomc.net/