OpenAudioMc

https://openaudiomc.net/docs
Admin
OpenAudioMc is an audio management and proximity voice chat system for Minecraft servers that...
Tokens:30,494
Snippets:299
Trust Score:7.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Full workflow example

Source: https://openaudiomc.net/docs/shows

Complete workflow: create show, add cues, start, inspect, and cancel.

```command
/openaudio show create demo
```

```command
/openaudio show add demo 0s command say Welcome to the show!
```

```command
/openaudio show add demo 10s chat @a[region=spawn] &7Enjoy the music!
```

```command
/openaudio show add demo 00:01:00 actionbar @a &eOne minute in...
```

```command
/openaudio show start demo
```

```command
/openaudio show info demo
```

```command
/openaudio show cancel demo
```

--------------------------------

### Start client for previewing language changes

Source: https://openaudiomc.net/docs/client_translations

Run this command in the repository root to start the client for previewing language changes. Requires Node.js and npm. After running, open http://localhost:3000 in a browser.

```bash
cd client/ && npm install --force && npm start
```

--------------------------------

### Build the OpenAudioMc client with npm

Source: https://openaudiomc.net/docs/deploying_web_client

Run these commands in the client directory to install dependencies, lint, and build the OpenAudioMc web client. Requires node and npm installed on the system.

```bash
npm install
npm run lint
npm run build
```

--------------------------------

### Play a sound with custom volume and starting point

Source: https://openaudiomc.net/docs/play_command

Plays a sound with custom volume (70) and starting point (5000 milliseconds).

```text
/oa play @a files:effect.mp3 {"volume":70,"startAtMillis":5000}
```

--------------------------------

### MediaApi.getInstance()

Source: https://openaudiomc.net/docs/play_command

Gets an instance of the media API.

```APIDOC
## getInstance()

### Description
Gets an instance of the media API.

### Method
getInstance

### Parameters
None

### Returns
static MediaApi
```

--------------------------------

### Start or cancel a running show

Source: https://openaudiomc.net/docs/shows

Starts the show or cancels it if it is running.

```command
/openaudio show start demo
```

```command
/openaudio show cancel demo
```

--------------------------------

### MediaApi.createMedia(@NotNull String source)

Source: https://openaudiomc.net/docs/play_command

Creates a new media instance with a source, automatically translating the source if needed and registering a normalized time for the start instant.

```APIDOC
## createMedia(@NotNull String source)

### Description
Creates a new media instance with a source, automatically translating the source if needed and registering a normalized time for the start instant.

### Method
createMedia

### Parameters
- **source** (String) - Required - The media source.

### Returns
@NotNull Media
```

--------------------------------

### Change volume for all players

Source: https://openaudiomc.net/docs/patch_command

Example that sets the volume of media 'my-song' to 60 for all players (@a).

```text
/oa patch @a my-song {"volume":60}
```

--------------------------------

### Add three cues to demo

Source: https://openaudiomc.net/docs/shows

Adds three command cues to the demo show at start, after 1 second, and after 1 minute.

```command
/openaudio show add demo 0s command say I fire at the start
```

```command
/openaudio show add demo 1s command say I fire after one second
```

```command
/openaudio show add demo 1m command say I fire after one minute
```

--------------------------------

### Change speed and fade time for nearest player

Source: https://openaudiomc.net/docs/patch_command

Example that sets speed to 120 and fadeTime to 1000 for media 'my-song' for the nearest player (@p).

```text
/oa patch @p my-song {"speed":120,"fadeTime":1000}
```

--------------------------------

### Get show status

Source: https://openaudiomc.net/docs/shows

Displays information about the specified show, including its state and cues.

```command
/openaudio show info demo
```

--------------------------------

### Language file key-value pair example

Source: https://openaudiomc.net/docs/client_translations

Shows the key-value format of a language file. The key is used by the web client to translate a string, and the value is the translated string. Values can include basic HTML, emojis, and HTML/UTF encoded characters, but cannot include line breaks or raw special characters.

```lang
home.confirmLoginHeader=Welcome back!
home.confirmLoginBody=Are you trying to login as <i>%player</i>?<br />If you are not, please clo
```

--------------------------------

### Maven dependency setup for OpenAudioMc API

Source: https://openaudiomc.net/docs/api

Add the OpenAudioMc API dependency to a Maven project. Requires the Mats public repository. Use version 6.10.16.

```xml
<repositories>
  <repository>
    <id>mats-public</id>
    <url>https://repo.mats.coffee/repository/mats-public</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>com.craftmend.openaudiomc</groupId>
        <artifactId>openaudiomc-api</artifactId>
        <version>6.10.16</version>
    </dependency>
</dependencies>
```

--------------------------------

### Gradle dependency setup for OpenAudioMc API

Source: https://openaudiomc.net/docs/api

Add the OpenAudioMc API dependency to a Gradle project. Requires the Mats public repository. Use version 6.10.16.

```groovy
repositories {
    maven {
        url = uri("https://repo.mats.coffee/repository/mats-public")
    }
}

compileOnly("com.craftmend.openaudiomc:openaudiomc-api:6.10.16")
```

--------------------------------

### MediaApi.getNormalizedCurrentEpoch()

Source: https://openaudiomc.net/docs/play_command

Gets the current epoch time, but normalized to the start of the current media.

```APIDOC
## getNormalizedCurrentEpoch()

### Description
Gets the current epoch time, but normalized to the start of the current media.

### Method
getNormalizedCurrentEpoch

### Parameters
None

### Returns
long
```

--------------------------------

### Create a playlist with /openaudiomc playlist create

Source: https://openaudiomc.net/docs/media_playlists

Creates a new playlist with a unique name. The playlist is referenced by this name later, so choose something descriptive like 'my-cool-playlist'.

```bash
/openaudiomc playlist create my-cool-playlist
```

--------------------------------

### Create a new show named demo

Source: https://openaudiomc.net/docs/shows

Creates a new show with the specified name. Required for adding cues.

```command
/openaudio show create demo
```

--------------------------------

### List all playlists with /openaudiomc playlist list

Source: https://openaudiomc.net/docs/media_playlists

Lists all available playlists.

```bash
/openaudiomc playlist list
```

--------------------------------

### Open the show editor GUI (no name)

Source: https://openaudiomc.net/docs/shows

Opens the GUI editor for the show. The show name is not specified in this command.

```command
/openaudio show gui
```

--------------------------------

### Play a playlist in a region (all songs in order) with /openaudiomc region create

Source: https://openaudiomc.net/docs/media_playlists

Assigns a playlist to a region, playing all songs in order. The 'list:' prefix targets the playlist.

```bash
/openaudiomc region create my-region list:my-cool-playlist
```

--------------------------------

### Play a sound for a client

Source: https://openaudiomc.net/docs/api

Constructs a Media object with a source, sets optional properties like loop, volume, and media ID, then plays it for a client using MediaApi.playFor(). The source is automatically translated to the client's format.

```java
// lets construct a media object, the source we pass in here will be automatically translated
Media sound = new Media("files:mysong.mp3");

// configure some pr
sound.setLoop(true);
sound.setVolume(50);
sound.setMediaId("example-sound");

// play the sound for mats (but the last argument is an optional array, so you can play the sound for multiple clients at once)
MediaApi.getInstance().playFor(sound, mats);
```

--------------------------------

### Open the show editor GUI

Source: https://openaudiomc.net/docs/shows

Opens a graphical interface to visually inspect and edit the show.

```command
/openaudio show gui demo
```

--------------------------------

### TrainCarts sign with alias

Source: https://openaudiomc.net/docs/traincarts_integration

Example sign using an alias created with `/openaudiomc alias myTrainMusic https://soundcloud.com/creide13/a-kings-request-cutscene`. The alias is referenced as `a:myTrainMusic`.

```plaintext
[!train]
audio
a:myTrainMusic
```

--------------------------------

### Add media to a playlist with /openaudiomc playlist add

Source: https://openaudiomc.net/docs/media_playlists

Adds a media source (e.g., SoundCloud song) to an existing playlist. The media source must be valid in the play command.

```bash
/openaudiomc playlist add my-cool-playlist https://soundcloud.com/lobsta-b/not-so-bad
```

--------------------------------

### Basic syntax for /oa play

Source: https://openaudiomc.net/docs/play_command

Basic syntax for the play command. The selector and source are required, while options are optional.

```text
/oa play <selector> <source> [options]
```

--------------------------------

### Get a client instance by UUID

Source: https://openaudiomc.net/docs/api

Retrieves a Client object from the ClientApi using a UUID. The client may be null if not online or just joined. Checks if the client is connected to the web client.

```java
UUID myUuid = UUID.fromString("88243ba3-382f-4eb0-874f-c5831eb3c0a6");
Client mats = ClientApi.getInstance().getClient(myUuid);

// the client may be null if they aren't online, or just joined (due to event order)
if (mats == null) {
    System.out.println("Mats is not loaded yet, you may need to wait a tick after joining");
    return;
}

// lets check if they are connected to the web client
if (mats.isConnected()) {
    System.out.println("Mats is connected!");
} else {
    System.out.println("Mats is not connected to the web client!");
}
```

--------------------------------

### Cancel proximity voice chat with ClientPeerAddEvent

Source: https://openaudiomc.net/docs/api

Prevents survival players from hearing spectator players in proximity voice chat by cancelling the ClientPeerAddEvent. Only handles the initial connection; if a peer changes gamemode later, use client#kickProximityPeer(client). This example is for single-sided voice chat only; use filters for actual peer filtering.

```java
EventApi.getInstance().registerHandler(ClientPeerAddEvent.class, event -> {
    // first of, convert both Clients to a Player
    Player player = Bukkit.getPlayer(event.getClient().getActor().getUniqueId());
    Player possiblePeer = Bukkit.getPlayer(event.getPeer().getActor().getUniqueId());
    
    if (player.getGameMode() == GameMode.SURVIVAL && possiblePeer.getGameMode() == GameMode.SPECTATOR) {
        // cancel the event, as we don't want the players to be able to hear eachother
        event.setCancelled(true);
    }
});
// this will only handle when the players are initially are being connected to eachother.
// If the peer changes gamemode, you can kick player A using client#kickProximityPeer(client)
```

--------------------------------

### MediaApi.pathMedia(String mediaId, @NotNull MediaPatchOptions options, @NotNull Client... clients)

Source: https://openaudiomc.net/docs/play_command

Updates playing media (like volume, pitch, etc) for a client.

```APIDOC
## pathMedia(String mediaId, @NotNull MediaPatchOptions options, @NotNull Client... clients)

### Description
Updates playing media (like volume, pitch, etc) for a client.

### Method
pathMedia

### Parameters
- **mediaId** (String) - Required - The ID of the media to update.
- **options** (MediaPatchOptions) - Required - The patch options to apply.
- **clients** (Client...) - Required - The clients to update media for.

### Returns
void
```

--------------------------------

### Create an audio region with /oa region create

Source: https://openaudiomc.net/docs/region_command

Creates a region that links a WorldGuard region to a media file. The region name must match the WorldGuard region name. Overlapping regions stack by default; priority support can be enabled in the OpenAudioMc config. The command accepts an optional third argument to set the volume during creation.

```text
/oa region create <regionName> <source>
```

```text
/oa region create spawn files:spawn-music.mp3
```

--------------------------------

### MediaApi.preloadMedia(Client client, Media media, boolean keepCopy)

Source: https://openaudiomc.net/docs/play_command

Forces a client to preload a media, so it's ready to play when needed.

```APIDOC
## preloadMedia(Client client, Media media, boolean keepCopy)

### Description
Forces a client to preload a media, so it's ready to play when needed.

### Method
preloadMedia

### Parameters
- **client** (Client) - Required - The client to preload media for.
- **media** (Media) - Required - The media to preload.
- **keepCopy** (boolean) - Required - Whether to keep a copy of the media.

### Returns
void
```

--------------------------------

### MediaApi.playFor(@NotNull Media media, @NotNull Client... clients)

Source: https://openaudiomc.net/docs/play_command

Plays a media for a client.

```APIDOC
## playFor(@NotNull Media media, @NotNull Client... clients)

### Description
Plays a media for a client.

### Method
playFor

### Parameters
- **media** (Media) - Required - The media to play.
- **clients** (Client...) - Required - The clients to play the media for.

### Returns
void
```

--------------------------------

### MediaApi.preloadMediaSource(Client client, String mediaSource, boolean keepCopy)

Source: https://openaudiomc.net/docs/play_command

Forces a client to preload a media source, so it's ready to play when needed.

```APIDOC
## preloadMediaSource(Client client, String mediaSource, boolean keepCopy)

### Description
Forces a client to preload a media source, so it's ready to play when needed.

### Method
preloadMediaSource

### Parameters
- **client** (Client) - Required - The client to preload media for.
- **mediaSource** (String) - Required - The media source to preload.
- **keepCopy** (boolean) - Required - Whether to keep a copy of the media.

### Returns
void
```

--------------------------------

### View a playlist with /openaudiomc playlist view

Source: https://openaudiomc.net/docs/media_playlists

Lists all entries of a playlist in chat, allowing you to click on entries to remove them.

```bash
/openaudiomc playlist view my-cool-playlist
```

--------------------------------

### Preload media with MediaApi.preloadMediaSource

Source: https://openaudiomc.net/docs/api

Forcefully preloads media for the client. The keepCopy flag keeps one instance in cache unless explicitly removed, which is useful for repetitive sounds but risks memory leaks.

```java
// this makes the client re-add it to the cache if its played, always keeping one instance ready
// unless it is explicitly removed from the cache. Great for repetitive sounds, but dangerous for memory leaks
boolean keepCopy = true;
// request the client to preload the media from "sound" which we defined earlier
MediaApi.getInstance().preloadMediaSource(mats, sound, keepCopy);
```
Tokens:
Raw