Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
JukeboxRecords
license: NLL LICENSE
JukeboxRecords is a feature-rich custom music plugin for Paper Minecraft 1.21.xthat transforms the traditional jukebox experience into a fully configurable music system. It allows server administrators to add their own .ogg music files, organize them into an interactive in-game music library, and let players listen to custom tracks through a dedicated Musical Jukebox.
The plugin is designed to be lightweight, reliable, easy to configure, and suitable for both private servers and public Minecraft communities.
Features
Custom Musical Jukebox
JukeboxRecords introduces a completely custom item called Musical Jukebox.
Unlike a normal Minecraft jukebox, the Musical Jukebox is internally identified using persistent plugin data, ensuring that it can be reliably distinguished from vanilla jukeboxes.
Players can:
Craft the Musical Jukebox.
Place it in the world.
Right-click it to open the music library.
Select custom songs.
Stop currently playing music.
Break and pick up the Musical Jukebox.
Place it again without losing its custom identity.
Vanilla jukeboxes remain completely unaffected and continue working normally.
Custom Crafting Recipe
The Musical Jukebox can be crafted using a configurable recipe.
The default recipe uses eight oak planks arranged around an empty center:
The crafting material can be changed through config.yml, allowing server administrators to customize the recipe to fit their server's economy or gameplay style.
Custom .ogg Music
Adding music is extremely simple.
JukeboxRecords automatically creates:
plugins/JukeboxRecords/rrecords/
Administrators can simply place their .ogg files inside this folder.
For example:
rrecords/ ├── music1.ogg ├── epic_battle.ogg ├── boss-fight.ogg ├── peaceful_music.ogg └── my_song.ogg
The plugin automatically scans the folder and detects available tracks.
There is no need to manually register every song in a configuration file.
Intelligent Song Names
File names are automatically converted into clean, readable names for the in-game interface.
For example:
epic_battle.ogg
can appear as:
Epic Battle
while:
boss-fight.ogg
can appear as:
Boss Fight
This makes large music libraries much easier for players to navigate.
Interactive Music GUI
Right-clicking a Musical Jukebox opens a configurable inventory-based music menu.
Each available song is displayed as an individual item, with configurable icons and formatting.
The interface can include:
Song list
Song names
Previous page
Next page
Stop music
Configurable title
Configurable number of rows
The system supports large music libraries by using pagination, allowing up to 45 songs per page.
This means servers can have dozens or even hundreds of custom songs without creating an enormous inventory interface.
Player and Area Playback
JukeboxRecords supports multiple playback modes.
PLAYER
Only the player who selected the song hears it.
This is ideal for personal music libraries where each player wants to listen to something different.
AREA
The song is played for players within a configurable radius of the Musical Jukebox.
For example:
mode: AREA radius: 20.0
This allows the jukebox to function as an actual environmental music source for towns, shops, events, lobbies, or other locations.
Volume, pitch, streaming behavior, and other playback settings can also be configured.
Music Control
JukeboxRecords carefully manages active sounds to prevent music from continuing indefinitely.
Music is stopped when:
The player selects another song.
The player presses the stop button.
The Musical Jukebox is broken.
The player leaves the server.
The plugin is disabled.
The server shuts down.
This prevents abandoned sounds and unnecessary resource usage.
Automatic Resource Pack Generation
Because Minecraft cannot directly play arbitrary server-side .ogg files as custom sounds, JukeboxRecords automatically generates a resource pack containing the music files.
The generated file is:
plugins/JukeboxRecords/JukeboxRecords-resourcepack.zip
The resource pack contains the required Minecraft sound structure, including:
assets/ └── jukeboxrecords/ ├── sounds/ │ ├── music1.ogg │ ├── epic_battle.ogg │ └── ... └── sounds.json
The plugin also generates the necessary pack.mcmeta and sounds.json files automatically.
Administrators therefore do not need to manually build a resource pack every time they add a song.
Automatic Resource Pack Updates
When new music is added, administrators can use:
/jukeboxrecords reload
or:
/jrecords reload
The plugin can then:
-
Reload the configuration.
-
Scan the music directory.
-
Detect new songs.
-
Detect removed songs.
-
Regenerate the resource pack.
-
Update the sound definitions.
-
Update connected players when appropriate.
This makes it possible to expand the music library without restarting the Minecraft server.
Built-in Resource Pack Server
JukeboxRecords can optionally provide a small built-in HTTP server capable of serving the generated resource pack.
For example:
http://YOUR_SERVER_IP:8123/JukeboxRecords-resourcepack.zip
The plugin calculates the resource pack's SHA-1 hash and can use it when sending the resource pack to players.
Administrators can configure whether the resource pack is:
Automatically sent when players join.
Optional.
Required.
Displayed with a custom prompt.
For public servers, administrators must ensure that the configured URL is accessible to players. A local address such as 127.0.0.1 is generally only accessible from the same machine and should not be used as the public URL.
Depending on the server setup, port forwarding, a public web server, or HTTPS hosting may be required.
Fully Configurable
JukeboxRecords is designed to avoid hard-coded behavior wherever practical.
Administrators can configure:
Musical Jukebox name.
Lore.
Crafting material.
GUI title.
GUI size.
Music folder.
Sound namespace.
Playback mode.
Playback radius.
Volume.
Pitch.
Streaming.
Resource pack URL.
Resource pack port.
Resource pack prompt.
Automatic resource pack delivery.
Required resource pack behavior.
Plugin messages.
This makes the plugin suitable for many different server styles.
Safe Vanilla Compatibility
JukeboxRecords does not replace or modify vanilla jukeboxes.
The plugin specifically identifies its own Musical Jukebox objects using persistent metadata.
This ensures that:
Vanilla jukeboxes remain vanilla.
Vanilla jukeboxes do not open the custom GUI.
Custom jukeboxes are not confused with vanilla blocks.
Breaking a custom jukebox returns the correct custom item.
The plugin does not accidentally convert ordinary jukeboxes.
Performance and Reliability
The plugin is designed with server performance in mind.
It avoids unnecessary repeating tasks and cleans up resources when they are no longer required.
It also handles situations such as:
Empty music folders.
Missing resource-pack files.
Invalid file names.
Missing songs.
Players disconnecting.
Plugin reloads.
Server shutdown.
Large music libraries.
Invalid or unsupported files are ignored rather than causing the entire plugin to fail.
Commands
Reload
/jukeboxrecords reload
Reloads the configuration and music library and regenerates the resource pack.
Alias:
/jrecords reload
Permission
jukeboxrecords.admin
The permission controls administrative commands such as reloading the plugin.
Example Directory
After the first startup, the plugin creates a structure similar to:
plugins/ └── JukeboxRecords/ ├── config.yml ├── JukeboxRecords-resourcepack.zip └── rrecords/ ├── epic_battle.ogg ├── peaceful_music.ogg ├── boss_fight.ogg └── ...
Simply place your .ogg files into the rrecords folder and run:
/jrecords reload
The plugin handles the rest.
Designed for Modrinth
JukeboxRecords is structured as a professional Paper plugin project and is suitable for distribution through Modrinth.
The project includes:
Maven build configuration.
Paper API dependency.
plugin.yml.
Default configuration.
Documentation.
License.
Changelog.
Clean Java package structure.
Build-ready source code.
The resulting plugin can be compiled with:
mvn clean package
producing a .jar file ready to place inside the server's:
plugins/
folder.
Compatibility
Platform: Paper Minecraft: 1.21.x Java: 21 Build System: Maven Music Format: .ogg
JukeboxRecords is intended to provide a modern, expandable, and server-friendly way of bringing custom music into Minecraft without requiring administrators to manually configure every individual sound.
Whether you want background music for a survival town, atmospheric tracks for an RPG server, boss music for custom events, or a massive personal music library, JukeboxRecords turns the humble jukebox into a complete custom music system
Support by Unleashor