CustomDiscs

Custom Discs v6.0.4

For Paper, Folia and Forks (Purpur, Leaf, ...)

1.21.7 to 26.3

⚠️ Dependency notice — PacketEvents required

Since version 5.2.0, PacketEvents (v2.12.1+) is required.\
ProtocolLib is no longer used — it can be safely removed if no other plugin needs it.

⚠️ Java 25 required

Starting with version 6.0.0, this plugin requires Java 25 or newer to run on your server.

A Paper fork of henkelmax's Audio Player. Special thanks to Athar42 for maintaining this plugin.

Any Paper forks should be supported. In case of issues, reach us on our Discord server.

Play custom music discs, goat horns and player heads using the Simple Voice Chat API.

The Simple Voice Chat mod is required on both the client and the server.

• Music files go into plugins/CustomDiscs/musicdata/
• Subdirectories can be enabled in config.yml via the subdirectory-depth setting:
• none (default): all files must be in the root of musicdata/
• single: one level of subdirectory (e.g. musicdata/rock/song.mp3)
• unrestricted: unlimited depth (e.g. musicdata/rock/metal/song.mp3)
• Supported formats: .wav, .flac, .mp3
• Use /customdisc or /cd to see available commands

Join our Discord for support: discord.gg/rJtBRmRFCr

Dependencies

Plugin · Required · Notes
Simple Voice Chat · ✅ Required · v2.6.1 minimum
PacketEvents · ✅ Required · Since v5.2.0 — tested with v2.12.1
ProtocolLib · ⛔ Up to v5.1.4 only · No longer required as of v5.2.0

Downloading Files

Use the command /cd download to download an audio file directly to the server.

Always write the URL between double quotes.\

Without this, you'll get a command error.

Direct URL

Any URL that starts an immediate file download when opened in a browser.

/cd download "example.com/mysong.mp3"; mysong.mp3

• The file extension in ` must match the actual format of the file. Providing a wrong extension (e.g. naming a .wav file as .mp3) will cause an UnsupportedAudioFileException` in the server console.
• Google Drive — Convert your sharing link to a direct download link: lonedev6.github.io/gddl/

Filebin

Filebin is a free, no-registration file hosting service. Two URL formats are supported (final / is optional, www. prefix is accepted in both cases):

Bin URL — filebin.net/\
The plugin queries the Filebin API and automatically downloads the first (and only the first) supported audio file found in the bin.

/cd download "filebin.net/mybinname"; mysong.mp3

Direct Bin file URL — filebin.net//\
Downloads a specific file from the bin.

/cd download "filebin.net/mybinname/mysong.mp3"; mysong.mp3

In all cases, if a file with the requested name already exists on the server, a unique name is automatically assigned (e.g. mysong_1.mp3) and you are notified in chat.

Permissions

Permission · Description
customdiscs.* · Grants all CustomDiscs permissions
customdiscs.create · Create a custom disc, goat horn or player head
customdiscs.download · Download a file from a URL
customdiscs.range · Set the audio range of a custom disc, goat horn or player head
customdiscs.horncooldown · Set the cooldown for custom goat horns
customdiscs.revert · Revert a custom item back to its original vanilla state
customdiscs.setmodel · Apply a Custom Model Data to a custom item
customdiscs.revertmodel · Remove a Custom Model Data from a custom item
customdiscs.reload · Reload the plugin configuration and language files
customdiscs.update · Receive an update notification on join if a new version is available

Playing discs does not require any permission.

Setting the range

Use /cd range while holding a custom disc, goat horn, or player head to set its hearing range.\
The range must be between 1 and the maximum value set in config.yml for the respective item type (default: 256).

/cd range 100

Setting the goat horn cooldown

Use /cd goatcooldown while holding a custom goat horn to set its cooldown, in ticks (1 second is 20 ticks).\
The value must be between 1 and the maximum value set in config.yml for the setting horn-max-cooldown (default: 6000).

/cd goatcooldown 200

Reverting a custom item

Use /cd revert while holding a custom disc, goat horn, or player head to revert it back to its original vanilla state.\
All custom data (sound file, lore, range, cooldown) is then removed.

/cd revert

Custom Model Data

Custom Model Data lets you apply a custom visual to custom discs, goat horns, and player heads by setting an integer value that your Resource Pack maps to a different model or texture of your choice.

This feature requires a Resource Pack installed on the client. The plugin only applies the numeric value of the custom model defined in your Resource Pack for the specific item CustomDiscs handles.

No support of any kind will be provided for creating or configuring a Resource Pack.

Enabling the feature

The feature is disabled by default.

You can change this by setting the enabled key to true (under custom-model-data), located inside config.yml.

Commands

Command · Description
/cd setmodel · Open the Custom Model Data browser GUI for the custom item in hand
/cd setmodel · Apply a model by its name as defined inside models.yml
/cd setmodel · Apply the ResourcePack ID directly for that item
/cd revertmodel · Remove the Custom Model Data value from the custom item in hand

Note: /cd revert command also removes Custom Model Data.

Configuring models.yml

models.yml is located in plugins/CustomDiscs/ (and is generated on startup if not found).

The material key (used in each item type) is the lowercase material name (for instance: music_disc_cat, music_disc_11, goat_horn, player_head, zombie_head, ...).

disc:
music_disc_cat:

• value: 1

name: "Meow Record"

• value: 2

name: "Magic Music"
music_disc_11:

• value: 1

name: "Mystery song"

horn:
goat_horn:

• value: 1

name: "Beware of the Horn"

head:
player_head:

• value: 1

name: "Head me"
zombie_head:

• value: 1

name: "Zombie me"

• value is the integer threshold in your Resource Pack item definition.
• name is the displayed label used in the GUI and for command (with autocomplete) /cd setmodel .
• Only the entries declared for the held item's material appear in the GUI.

Hint: Use /cd reload to apply changes to models.yml without restarting your server.

Languages

Language files are located in plugins/CustomDiscs/langs/.\
Each player receives the messages in their own client language automatically — no configuration needed per player!

Available languages

The following languages are included by default:

Code · Language · Code · Language
en · English · nl · Dutch
fr · French · it · Italian
de · German · tr · Turkish
ru · Russian · cs · Czech
es · Spanish · hu · Hungarian
pt · Portuguese (BR/PT) · ko · Korean
zh · Chinese (Simplified/Traditional) · tt · Tatar
pl · Polish

pt covers both pt_BR and pt_PT.\

zh covers both zh_CN and zh_TW.

Found a translation error or just want your language added?\

Reach us on our Discord or submit a Pull Request on GitHub — your contributions are always welcome!

Server default language

Set the fallback language used for console output and when a player's language has no matching file:

config.yml

default-lang: en

Adding a custom language

Create a new file in plugins/CustomDiscs/langs/ named after the ISO 639-1 two-letter language code "Set 1" (e.g. ja.yml for Japanese).\
Copy the contents of en.yml and translate the values.\
Use /cd reload to load it without restarting the whole server.

Notice on updates behaviour

When the plugin is updated with new messages:

• Bundled language files (en, fr, de, ...): new messages are automatically added to your existing files using the plugin original translation.\

Keys that you have already customised are never overwritten.

• Custom language files (made by you): new messages are added using the default English language.\

So keep an eye in your own lang if you don't want to have a mix with the default values.

Reloading the configuration

Use /cd reload to reload config.yml, all language files in langs/ and models.yml (if the Custom Model Data feature is enabled) without restarting the server.

/cd reload

Configuration

config.yml

[General CustomDiscs Config]

The maximum download size in megabytes.

max-download-size: 50

The maximum length the file name (including the file extension) should be when downloaded. Using a too high value could crash the server.

filename-maximum-length: 100

The master volume of music discs from 0-1. (You can set values like 0.5 for 50% volume).

music-disc-volume: 1

Subdirectory depth allowed in musicdata folder. Possible values are :

none: all files must be in the root of musicdata (default)

single: one level of subdirectory allowed (e.g., musicdata/rock/song.mp3)

unrestricted: unlimited subdirectory depth (e.g., musicdata/rock/metal/song.mp3)

subdirectory-depth: none

Default language for player messages.

Must match a file name in the langs/ folder (e.g. "en", "fr", "de", "ru").

Players whose client language has no matching file will fall back to this selected language.

default-lang: en

Debug Mode - To display some more logging information and Stack Trace informations

debugMode: false

[Music Discs Config]

Enable custom music discs.

music-disc-enable: true

Enable "Now playing" message for custom music discs.

music-disc-playing-enable: true

The distance from which music discs can be heard in blocks.

music-disc-distance: 16

The max distance from which music discs can be heard in blocks.

music-disc-max-distance: 256

[Goat Horns Config]

Enable custom goat horns.

custom-horn-enable: true

Enable "Now playing" message for custom horns.

custom-horn-playing-enable: true

The distance from which custom horns can be heard in blocks.

custom-horn-distance: 16

The max distance from which custom horns can be heard in blocks.

custom-horn-max-distance: 256

The default instrument to restore when reverting a custom goat horn.

Used only if the original instrument could not be saved at creation time.

Valid values: ponder_goat_horn, sing_goat_horn, seek_goat_horn, feel_goat_horn,

admire_goat_horn, call_goat_horn, yearn_goat_horn, dream_goat_horn

default-horn-instrument: ponder_goat_horn

The default cooldown time for horns in ticks from 1 to the max value of horn-max-cooldown (1 second is 20 ticks).

horn-cooldown: 140

The default max cooldown time for horns in ticks (1 second is 20 ticks).

horn-max-cooldown: 6000

[Player Heads Config]

Enable custom player heads.

custom-head-enable: true

Enable "Now playing" message for player heads.

custom-head-playing-enable: true

The distance from which player heads can be heard in blocks.

custom-head-distance: 16

The max distance from which player heads can be heard in blocks.

custom-head-max-distance: 256

[Custom Model Data Config]

Enable the Custom Model Data feature.

Configure available models in models.yml (need a resourcepack active on the server to work).

custom-model-data:
enabled: false

[Update Checker Config]

Enable automatic update checks against Modrinth.

Operators or players with permission "customdiscs.update" are notified on join when an update is available.

An initial check is performed on startup, then every 24 hours as long as the server is running.

update-check