CustomJukebox

Real music on your Minecraft server. CustomJukebox turns jukeboxes into a full music system: custom discs with your own .ogg tracks, playlists, and ambient zones that play background music automatically as players walk into an area — all without replacing a single vanilla disc.

Built for Paper and Folia, configured in JSON, and translated into four languages.

---

🎧 Bedrock players?

CustomJukebox streams audio from a Java resource pack, which Bedrock clients handle differently. If you run Geyser/Floodgate, install the companion plugin:

➡️ BS-CustomJukebox Bedrock Extension

It hooks into the public API events this plugin fires, so no extra configuration is needed on the CustomJukebox side — install both and they work together.

---

🛠️ No resource pack yet?

Getting the pack right is the fiddly part. Four names have to line up — the .ogg path, the event key in sounds.json, the name inside it and sound in disc.json — and a single mismatch means silence, with no error on either side.

➡️ CustomJukebox Pack Generator

Drop your audio in and get a ready-to-host pack.zip, a matching disc.json and the two server.properties lines with the SHA-1 already calculated. It converts mp3, wav and flac to Ogg Vorbis in your browser — no upload, your music never leaves your machine — draws disc and fragment textures, and can load an existing pack so you can add tracks without breaking what already works.

---

✨ Features

🎵 Custom Music Discs

• Add your own music discs without overriding vanilla ones
• Real audio via resource pack (.ogg) — full quality, not note blocks
• Customisable title, author, lore and CustomModelData
• Automatic stop at the configured track length
• Managed in disc.json, or entirely in-game through the admin GUI

📻 Ambient Zones & Server Radio

Background music that starts on its own for everyone who enters an area — no disc, no command, no redstone.

• Four area types: radius, cuboid, WorldGuard region, or global (a server-wide radio station reaching every player in every world)
• Priority decides which zone wins where several overlap — a lobby zone can override the radio
• Two playback modes: synced (everyone hears the same track together — ideal for events) or individual (each player hears complete tracks from the moment they arrive — ideal for lobbies)
• Height range: cover the full column (default) or bound the zone in Y as a true 3D sphere/box
• Loop and shuffle, reshuffled on every lap
• Per-zone volume and playlist

🎶 Playlists & Categories

• Group discs into playlists and play them in sequence
• Shuffle and repeat modes (loop, repeat-one)
• Playback range per playlist: normal, whole world, server-wide, or a custom radius in blocks
• Categories to keep large disc collections organised

👤 Player Controls

Every player gets these by default — no permission setup required.

• /cjb music on|off — opt out of plugin music entirely, saved across sessions
• /cjb music volume — a personal volume, independent of the server setting
• /cjb skip — skip the track you are currently hearing
• /cjb favorite — keep a personal favourites list and play it as a playlist; discs can also be favourited by shift-clicking them in the disc menu
• Progress bar — an optional boss bar showing the current track and how far into it you are

🧩 Fragment System

• Collect disc fragments and craft them into complete discs (shapeless, count configurable)
• Creeper drops: guaranteed when a skeleton kills a creeper, configurable chance for player kills
• Loot integration: fragments appear in dungeons, bastions, end cities, trail ruins and more

🖥️ In-Game Administration

• Jukebox GUI — right-click an empty jukebox to pick a disc
• Admin panel (/cjb gui) — create, edit and delete discs, playlists and categories without touching a file
• Step-by-step creation wizards with input validation
• Zone editor GUI that tells you exactly why a zone is not playing yet
• Every list paginates, so large collections stay fully reachable
• Delete confirmations on destructive actions

🌍 Integrations & Compatibility

• Paper 1.21.4 – 26.x and Folia (region-threaded scheduling, auto-detected)
• WorldGuard — respects the USE flag, and can bind ambient zones to regions
• GriefPrevention — respects container trust
• PlaceholderAPI — 16 placeholders (disc in hand, volume, mute state, totals, and more)
• Multi-language: English, German, Spanish, Italian — fully translated, editable
• Developer API with four Bukkit events (DiscPlaybackStart/Stop, DiscRegistered/Removed)
• bStats metrics (opt-out)

🦜 Parrot Dancing

Parrots react to custom music within a configurable radius.

---

📋 Commands

For everyone

Command	Description
/cjb music <on|off|toggle|volume <0-4|reset>|status>	Your personal music settings
/cjb skip	Skip the track you are hearing
/cjb favorite <add|remove|toggle|list|play|clear>	Manage and play your favourites
/cjb gui	Open the disc menu
/cjb list [page] · /cjb info <disc>	Browse discs

For admins

Command	Description
/cjb zone <...>	Create and manage ambient zones and radio stations
/cjb playlist <...>	Create and play playlists
/cjb play <disc> [loop] [global|world|<radius>]	Play a disc at your position
/cjb give · /cjb fragment	Hand out discs and fragments
/cjb volume · /cjb mute · /cjb unmute	Server-wide volume
/cjb stop · /cjb reload	Stop playback / reload configuration

Aliases: /customjukebox, /jukebox, /jb

---

🔑 Permissions

Permission	Default	Grants
customjukebox.use	everyone	Use jukeboxes
customjukebox.gui · .list · .info	everyone	Browse discs
customjukebox.music · .favorite · .skip	everyone	Personal settings, favourites, skip
customjukebox.admin	op	All admin commands (parent)
customjukebox.zone · .playlist · .play · .stop · .volume	op	Individual admin permissions
customjukebox.give · .fragment · .reload	op	Item handout and reload
customjukebox.bypass.protection	op	Ignore WorldGuard/GriefPrevention checks

---

📦 Requirements

• Server: Paper 1.21.4+ or Folia (also runs on 26.x)
• Java: 21 or newer
• A resource pack containing your .ogg files — required for custom sounds to be audible
• Optional: WorldGuard, GriefPrevention, PlaceholderAPI, Geyser/Floodgate (with the Bedrock Extension)

---

🚀 Quick Start

1. Drop the JAR into plugins/ and start the server. It creates config.json, disc.json, zones.json and the languages/ folder.
2. Put your .ogg files into a resource pack and register them in sounds.json — or let the Pack Generator build the pack, the textures and a matching disc.json for you.
3. Host the pack and set resource-pack plus resource-pack-sha1 in server.properties.
4. Create a disc — easiest through /cjb gui → Admin Panel → Disc Management, or by editing disc.json.
5. /cjb reload

Lobby music in four commands

/cjb playlist create lobby-mix
/cjb playlist add lobby-mix my_track
/cjb zone create lobby            # centred on where you stand
/cjb zone radius lobby 60
/cjb zone playlist lobby lobby-mix

The zone is enabled and looping by default. For a station covering the entire server, use /cjb zone global <id> instead of a radius.

---

⚙️ Configuration

config.json — every value shown is the default:

{
  "settings": {
    "enabled": true,
    "language": "en",
    "enable-gui": true,
    "debug": false,
    "max-backups": 5,
    "backup-min-interval-minutes": 5
  },
  "discs": {
    "creeper-drops": true,
    "creeper-drop-chance": 0.05,
    "dungeon-loot": true,
    "trail-ruins-loot": true,
    "max-loot-discs": 2,
    "loot-chance": 0.15,
    "enable-crafting": true,
    "fragments-per-disc": 9
  },
  "playback": {
    "volume": 4.0,
    "default-loop": false,
    "jukebox-hearing-radius": 64,
    "show-title": true,
    "show-actionbar": true,
    "show-progress-bar": true,
    "progress-update-ticks": 20
  },
  "parrots": {
    "enable-dancing": true,
    "dance-radius": 3
  },
  "ambient-zones": {
    "enabled": true,
    "sound-category": "RECORDS"
  },
  "integrations": {
    "worldguard": true,
    "griefprevention": true
  }
}

Ambient zones live in zones.json, discs and playlists in disc.json, per-player settings in players.json. All files are written asynchronously and replaced atomically, so saving never stalls the server tick and an interrupted write cannot corrupt a config.

---

🔗 Links

• 🛠️ Pack Generator — build a resource pack in your browser
• 🎧 Bedrock Extension — for Geyser/Floodgate servers
• 🐙 Source on GitHub
• 🐛 Report an issue