Integrating OpenAudioMc into your Java plugin
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
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>
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>
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); } });
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
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! });
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 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");
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);
Please visit GitHub for the most recent and full list of API methods and their javadoc: