OpenAudioMc Commands & Api-Documentation


Note : These commands are for OpenAudioMc version 6.0.3 and up.

Introduction

Welcome to the OpenAudioMc 6.0 (2019) documentation.

Since 6.0 was a complete rewrite, your old commands might have changed and wont work anymore. The documentation is sorted by topic (as seen in the navbar to the left) You can click one of the topics to read more about it.


If you are still having problems, feel free to join our Discord and ask for help.


Media

The OpenAudioMc audio format is whats being used throughout the network. It contains the source and a UNIX timestamp for when the command was executed. This is defined by the plugin and does NOT get changed anywhere further on in the process.

Other optional meta data included:

  • fadeTime Integer

    Time for the sound to fade in (in MS)
  • id String

    The ID that will be assigned to the sound. This can be used to stop one specific sound later.
  • loop Boolean

    Decide whether the sound should restart after finishing or not. This will mean that the sound will keep playing until manually stopped.
  • pickUp Boolean

    Decides if the sound should continue (AKA Sync) between sessions and players
  • expirationTimeout Integer

    The amount of time (in seconds) a sound should be kept for. Setting it to 120 will mean that the client will hear the sound, even if it connected after it started.

All the optional tags should be included in the Play command as a JSON object with the spaces left out.

OpenAudioMc supports multiple file formats for your sounds, these are:

  • .MP3
  • .FLAC
  • .WEBM
  • .WAV
  • .OGG
  • Google Drive Public Share Link
  • DropBox Public Share Link
  • SoundCloud

If you are running the client over SSL (https) all your content is also expected to go over SSL, any other content WILL be denied and wont play. A solution will be to switch the client over to normal http

It is possible to add support for other sources as well. OpenAudioMc has an java api to add support for url manipulations. This means that there are add-on plugins like OpenAudioMc-Youtube to expand the feature set.


Configuration files

Note : Config files should not be changed/saved when the server is running since this can corrupt data and changes may not be saved properly

OpenAudioMc makes two files in the plugins/OpenAudioMc/ directory. config.yml and data.yml

The data.yml contains region data, speaker storage, the url to the web client and the API keys. Changing this file is not recommended, you should only change it if you really know what you are doing.

config.yml is where you will be spending the most of your time. Here follows a quick roundup of all the values and what they do

Other optional meta data included:

  • click-to-connect String

    The message that the player receives in chat after joining or requesting a url to connect.
  • client-opened String

    Th message that the player will receive in the chat once the client has connected
  • client-closed String

    The message that the player receives when the client has disconnected or lost connection
  • call-ringing String

    The message a player receives when a player get's a call
  • call-left String

    The message a player receives when a player leaves or gets kicked out of a call
  • click-link-expired String

    The message that the player receives if something happens that causes their link to become invalid
  • client-volume-changed String

    The message the player receives after changing the volume from in game. __amount__ will be replaced by the new volume (in %)
  • client-volume-invalid String

    The message the player receives after they change the volume to a invalid value
  • client-not-connected String

    The message the player receives after trying to do something that requires them to be connected when they are not
  • client-already-connected String

    The message the player receives when they are already connected
  • api-starting-up String

    The message the player receives when the API is still starting up and they need to wait before trying again
  • send-on-join Boolean

    If the player should get a url to connect upon joining the server
  • speaker-radius Integer

    The radius (in blocks) that speakers can be heard from
  • title String

    The title of the web page
  • background URL

    The source to an image to use as the background for the web client
  • welcome-message String

    The text that will be displayed in the web client after the client connected
  • error-message String

    The message the web client will see when an error occurs with the connection or they disconnect in game
  • hue-connected String

    The message that gets displayed on the web client when it is connected to a hue bridge
  • hue-linking String

    The message the player sees on the web client when they need to click the link button on the hue bridge
  • hue-bridge-found String

    The message that notifies the user that their hue bridge has been detected and asks them if they want to start the setup or not

Selectors

Selectors are used to specify to which clients a action should be executed. The selector format is inspired and partially compatible with the Mincecraft selection format. Usernames are also accaptable, but the main format goes as follows. Selectors start with a group of players, supported groups are:

  • @a

    Starts the query for all the players in the server
  • @p

    Starts the query for the nearest player in the server

You can just leave it there but you can also filter for some attributes like location , radius and worldguard region

Examples

For example, to start a sound for all players in a radius of 10 blocks

@a[r=10]

Note : You need to have WorldGuard installed to use this feature

You can also filter players by the worldguard region they are in, for example to select everyone in the region spawn

@a[region=spawn]

Note : You need to have BungeeCord for this feature

When executed by a player, you can use server to select all players in a server server

@a[server=lobby-1]

And last but not least, you can also select player (near) a specific location, for example, lets select everyone near the block at X:10, Y:12, Z:15

@a[x=10,y=12,z=15,r=5]

Bungeecord configuration

Since 6.0, OpenAudioMc has full BungeeCord support.

If you install the plugin in all your Spigot servers and your BungeeCord server it will automatically enter BungeeCord mode and link the servers together in a proxy. Players will then be able to use one OpenAudioMc web client instance across your whole network, without needing to re-open it. Due to the magical inner workings of OpenAudioMc, you can still use Command Blocks, Regions, and Speakers in all of your servers. There's no manual config, everything will just work <3

Please remember to keep your OpenAudioMc the same across your whole network for everything to stay supported. For changing messages, URL's and more you should use the config.yml in your bungeecord OpenAudioMc plguin folder.


Voice Chat/Calls

Starting 6.0, OpenAudioMc has a build in voice chat system.

The voice chat uses the principle of one-time private rooms with your players. The voice-chat client is build into the existing web-client and the player doesn't need to do anything else than press one popup to accept the call and optionally select a microphone if they have multiple connected to their system.

A user will Allways be asked and informed if they want to join a call before anyone can hear them, where they can review a list with who is in the call to then accept or deny the invatation. In case of a minigame-like system, a Player can chose to automatically join calls and skip this process via a checkbox. (off by default)

Voice chat is only available for enterprise partners, which you can read more about in the Partners section.

Voice chat will work with up to 16 people and has a high quality and low latency connection

The base command format is as follows

/openaudio call create <selector>...

You can use a list of names or selectors, for example

/openaudio call create Mindgamesnl @p

Will add me and whoever is nearest into a call together.


OpenAudioMc partners

new starting this launch is the OpenAudioMc Partner Program. We understand that for bigger servers and networks control can be of great importance. For partners we can offer extra features, these are (but not limited to)

  • Dedicated (and scalable) private hosting solutions
  • Dedicated Voice Chat servers
  • Custom build addon’s and API’s
  • Listed on the official Spigot page, website, and discord
  • Discord role and access to special chats for announcements and discussion
  • Prioritized support (call me out of bed if you absolutely need to)

Not everyone will be accepted in the partner program. This is an option specifically created for enterprise servers. You'll need to contact me privately (via Spigot or the Discord) where we'll discuss your application to see if we both can come to terms.

Because a partnersip like this costs the project a lot more resources and thus leading to extra costs it'll be a payed plan in most cases, alltough this can't be quoted since everyone will have specific needs.

The main points we look for in a partnership are

  • (if and) how the server in question will use OpenAudioMc to the benifit of the Player
  • (if and) how OpenAudioMc is used in the user experiance
  • The resource demands of the server and if they really need a dedicated for their playerbase
  • branding of the OpenAudioMc system
  • ... and some more that will be discussed in private

The Play Command

The play command is used to start Media for a client or to schedule it to play. It follows the syntax of

/openaudio play <selector> <source> [media options]

selector and source are the two required arguments and media options is optional and can be left out. The usage of the media options can be found Here

Examples

An example command for starting a simple sound for the player Mindgamesnl with the ID baron_onride

/openaudio play Mindgamesnl https://soundcloud.com/mrfijiwiji/imalright {id:"chill_station"}

The Notification Command

The Notification command can be used to send a push Notification to a client. If the client does not have Push Notifications enabled then they'll see it as a badge in the web client.

We advice you only to use Push Notifications for important messages as to not be annoying.

/openaudio notification <selector> <message> 

Example

/openaudio notification @a Welcome to the server!

The Stop Command

The play command is used to stop Media it it is playing. When executed, all media will be stopped for a player (with exception for Regoins and Speaker

You can also add an id to the end, and only the sound with that ID will be stopped. The code follows the following format

/openaudio stop <selector> [id]

selector is the only required argument.

Examples

An to stop the sound with the id baron_onride for the player Mindgamesnl

/openaudio stop Mindgamesnl chill_station

The Show Command

With shows you can make timecoded shows. Our definition of a show is a list of cues, or scheduled events.

The major benefit about shows is that they are multithreaded. Meaning that in-game lag (TPS drops) will NOT effect or hinder the timing of your show to always keep it in sync with the audio.

So get started, make a show called "demo"

/openaudio show create demo

We now have a show called demo. We can start/stop it but this won't really do anything, we need to add cues first. To do so, you fist need to understand what a timecode is.

A timecode is the amount of time from when the start command is executed. OpenAudioMc supports the followiing formats:

  • m Minutes

    1m = 1 minute, 1.5m = 1 minute and 30 seconds.
  • s Seconds

    1s = 1 second, 1.5s = 1 second and 50 milliseconds
  • ms Milliisecond

    1ms = 1 millisecond
  • t Tick

    1t = 1 minecraft tick, or 50 mlliseconds
  • HH:mm:ss HourHour:MinuteMinute:SecondSecond

    00:05:00 = 5 minutes

Out of the box, OpenAudioMc supports one trigger type, this is command. This will execute a command as consolue. Other triggers can be added via addons or the API.

For this demo, we are gonna add two cues. One cue after 0 seconds, a cue after 1 second and a cue after 1 minute. To add these cues, use the following commands

/openaudio show add demo 0s command say I fire at the start
/openaudio show add demo 1s command say I fire after one second
/openaudio show add demo 1m command say I fire after one minute

The basic format here is

/openaudio show add <show name> <timecode> <type> <data>

To get the status of a show, you can use

/openaudio show info demo

To start or cancel

/openaudio show add <start/cancel> <showname>

You can also edit a show via a gui using

/openaudio show gui <show name>

From here, you can change the show state, scroll through cues and delete them.


Speakers

Speakers are little blocks you can place in your Minecraft world. Just like real speakers in a themepark, all of them play synchronized and can be hidden. The thing that makes them special is that they share some properties just like real audio sources, You cant hear them from too far away and the volume depends on your location relative to a speaker.

There's only one command that gives you the speaker, after executing you will receive a Speaker in your inventory. You can place it via creative mode. To remove them, you just go up to one and destroy the block like normal, this can also only be done when you are in creative mode.

New in 6.0.3, you can also set an optional range for a speaker (measured in blocks)

The command follows the following format:

/openaudio speaker <source> [radius]

Examples

To receive a speaker playing the park entrance sound

/openaudio speaker https://soundcloud.com/mrfijiwiji/imalright 10

To change the spaker radius, you can also right-click on a speaker. A GUI will open where you can select a new radius.


Regions

Note : You need to have WorldGuard installed to use this feature

Note : OpenAudioMc does not create the region for you. You'll have to create it manually via the WorldGuard commands.

Note : Deleting the sound form a region does not delete the WorldGuard region itself, it just removes the sound.

OpenAudioMc has an integration for WorldGuard (both 1.8 to 1.12.2 and the 1.13/1.14 update)

This enables you to add music to your regions. The media will be synced between everyone in the region and those who enter it later. When two bordered regions have the same sound selected OpenAudioMc will handle them as extentions and not re-start the sound when the player moves from one to the other. When both regions have different sounds then the old one will slowly fade out while the new sound starts. Overlapping regions are also supported.

Regions have two commands (for adding and removing), the format goes as follows

/openaudio region <create/delete> <worldguard-region-name> [source if created]

Examples

In this example, we want to add a sound to our WorldGuard region called station

/openaudio region create station https://soundcloud.com/mrfijiwiji/imalright

And we can remove the sound from the region if we've had enough of it

Examples

To receive a speaker playing the park entrance sound

/openaudio region delete station

You can also get fancy and create temporary regions.

Temporary regions function just like regions, except that they dissapear after a some time and syncronize based on when they where created. This is very usefull for systems like shows, where you want users to join later on.

The base command is

/openaudio region <temp> <worldguard-region-name> <duration in seconds>

Example,

/openaudio region temp my-show https://soundcloud.com/mrfijiwiji/reality-is-more-beautiful 70

This will create a region with that song for 1 minute and 10 seconds


The Hue Command

The OpenAudioMc command is used to change the colors and brightness of specific lights or groups.

All color codes are explicitly in RGBA, with values for Red, Green, Blue and Brightness defined in a range from 0 to 255 . So red at max brightness will be 255 0 0 255 . The light selection is a Json array of integers that are mapped to the light id's of the selected room. Example, the philips hue starter kit has 4 lights, to change all the lights the array would be [1,2,3,4] or if you would only want to change light 2 it is [2]

The command follows the format of:

/openaudio hue set <selector> <lights> <red> <green> <blue> <brightness>

Examples

Example, if i would want to change the lights of my setup to blue the command will be

/openaudio hue set Mindgamesnl [1,2,3] 0 0 255 255

Note : Due to a limitation in the Philips Hue api, it only works over HTTP and not HTTPS, the client will be notified when they try to connect over HTTPS

The Hue Connection

OpenAudioMc has a build in Philips-Hue integration this can be used to add real time lighting effects to your Minecraft server


The hue integration is designed to work with colors, but white lights are also supported (along with Led strips). When a hue bridge gets detected on the local network of a client, it will show a little bottom right corner.


hue button

If the user clicks the button it prompts them though the setup process where they need to select a room. The messages for this setup can be changed in the config. If the user already linked their lights before, OpenAudioMc will automatically when connected.


The API

Java is cool. I think it is.

OpenAudioMc is based on a custom framework, and it has some neat toys for you to play with.

These functions can be used by adding OpenAudioMc to your maven dependency list as so

<dependencies>
    <dependency>
        <groupId>com.craftmend.openaudiomc</groupId>
        <artifactId>OpenAudioMc</artifactId>
        <version>LATEST</version>
    </dependency>
</dependencies>

Interfaces

The main interface used is ClientConnection. Every online player has it's own instance specific to them. With this object you can control the player's network connection (with the web application) and trigger manual effects or request data.

Methods in this Class:

  • isConnected() returns Boolean

    If the client is connected to the web client
  • getPin() returns String

    The current personal authentication token for the client
  • getOngoingMedia() returns List<Media>

    A list of the current sounds that are specified to continue playing for the client
  • getRegions() returns List<IRegion>

    A list of all the current regions, along with their id and sound
  • getSpeakers() returns List<ApplicableSpeaker>

    A list of all current speakers, with their sound and distance
  • playMedia(Media) returns void

    Start a sound for a player, takes a Media object, but we'll take a closer look to that later
  • setVolume(Integer) returns void

    Sets the volume for the client

Plain API

The main OpenAudioMc api class can be accessed via

OpenAudioApi api = OpenAudioMc.getApi();

The methods are:

  • getClient(UUID/Player) returns ClientConnection

    Get the ClientConnection that is used by a specific online player
  • registerMutation() returns void

    Register a mutation. Please scroll down to learn more
  • getRegion(Location) returns List<IRegion>

    Get all media regions on a location
  • getSpeaker(Location) returns Speaker

    Get the speaker on a location

Media

The Media object is really the beating heart for OpenAudioMc. It contains the sound, and everything related to it.

You can create a Media as follows

Media mySound = new Media("url source");

The url can be anything. It WILL get converted by any add-ons using the url manipulation API, you don't need to worry about that.

You can add extra attributes to the media, the functions are:

  • setMediaId(String) returns void

    Sets the media ID to a String
  • setMediaTimeout(Integer) returns void

    Sets the amount of seconds where the sound should be hold on to. For more information, please see experationTimeout in the media documentation
  • doPickup(Boolean) returns void

    Determine if the sound should have a synced timestamp between players and sessions
  • setLoop(Boolean) returns void

    Determine if the sound should repeat after finishing
  • setFadeTime(Integer) returns void

    The amount of milliseconds the file should take to fade in

Event's

OpenAudioMc has two events, both will be executed form the main (Sync) thread.

Examples

On connect

@EventHandler
public void onWebConnect(ClientConnectEvent event) {
    ClientConnection clientConnection = event.getClient();
    Player player = event.getPlayer();
}

On disconnect

@EventHandler
public void onWebDisconnect(ClientDisconnectEvent event) {
    Player player = event.getPlayer();
}

Url Manipulations

You can also register "proxy's" for media sources.

This will mean that all url's starting with a certain string will be processed by your handler. Example for a SSL proxy:

Step one: create your class

import com.craftmend.openaudiomc.OpenAudioMc;
import com.craftmend.openaudiomc.modules.media.interfaces.UrlMutation;

public class SslProxy implements UrlMutation {

    @Override
    public String onRequest(OpenAudioMc openAudioMc, String original) {
        //replace http with https on all url's
        return original.replace("http", "https");
    }

}

Next up is registering your handler with the prefix. The first argument is the query, and the second argument is an instance of your mutation.

OpenAudioMc.getApi().registerMutation("http", new SslProxy());