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.

✨ 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

For admins

Aliases: /customjukebox, /jukebox, /jb

🔑 Permissions

📦 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.
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

• 🎧 Bedrock Extension — for Geyser/Floodgate servers
• 🐙 Source on GitHub
• 🐛 Report an issue