Cobbleworks - Custom Jukebox Plugin

Play Note Block Studio songs through signs, redstone, or a personal music browser.
Organize large song libraries into folders and control playback without leaving the game.

          

Custom Jukebox indexes .nbs songs only when needed and presents them through an inventory-based browser. Players can listen privately, administrators can create world signs, and songs can be bound to persistent custom records that play in ordinary jukebox blocks. Folder navigation keeps even large song collections manageable.

Core Features

• Folder-aware song browser: Subdirectories become navigable folders in the in-game GUI
• Personal playback: Play or stop a song without creating a world jukebox
• Jukebox signs: Store the selected song, volume, looping, and redstone mode directly on a sign
• Three redstone modes: Toggle, pulse, or ignore external redstone power
• Registered-sign index: List configured signs and their locations with an admin command
• Lazy song loading: Scan metadata without keeping every complete song in memory
• Action-bar status: Show the active personal song while it is playing
• Live reload: Rescan the song library without restarting the server
• Persistent custom records: Create a physical record for any indexed song and play it in a vanilla jukebox
• Random intact disc artwork: Each created record uses a randomly selected full music-disc icon; the cracked 11 disc and disc fragments are excluded
• Block lifecycle support: Custom record playback resumes after a restart or chunk reload and follows player or hopper insertion and removal

Supported Platforms

• Server Software: Paper
• Minecraft Version: 26.2
• Java Requirement: Java 25+
• Required Plugin: NoteBlockAPI 1.7.0

Table of Contents

1. Core Features
2. Supported Platforms
3. Getting Started
   • Prerequisites
   • Installation Steps
   • Verifying Installation
4. Third-Party Plugins
   • NoteBlockAPI
5. Configuration
6. How It Works
   • Song Library
   • Jukebox Signs
   • Redstone Modes
   • Custom Records
7. Commands
8. Permissions
9. Building from Source
10. License
11. Screenshots

Getting Started

Prerequisites

• A Paper 26.2 server
• Java 25 or newer
• NoteBlockAPI 1.7.0

Installation Steps

1. Download the latest Custom Jukebox jar from Releases
2. Download NoteBlockAPI-1.7.0.jar from the official NoteBlockAPI release page
3. Stop the server and copy both jars into its plugins/ directory
4. Start the server once, then add .nbs files under plugins/CustomJukebox/songs/
5. Use /jukebox play to browse the library or create a [jukebox] sign
6. Use /jukebox disc <player> <song> as an operator to create a physical custom record

Song subfolders are shown as folders in the browser, so the directory structure can be used to group albums, areas, or event music.

Verifying Installation

• Run /plugins and confirm that both NoteBlockAPI and CustomJukebox are green
• Run /jukebox play and confirm that the song browser opens
• Run /jukebox reload after adding a test .nbs file and confirm that it appears

Third-Party Plugins

NoteBlockAPI

NoteBlockAPI reads and plays Note Block Studio files. It is a required server plugin and is not included in the Custom Jukebox release artifact. Version 1.7.0 or a compatible newer release must be installed separately.

NoteBlockAPI is maintained by its own contributors and distributed under the GNU Lesser General Public License v3.0. Questions about song parsing or sound playback should first be checked against its project documentation.

Configuration

The generated config.yml controls playback volume and source limits.

Setting	Description	Default
volume.min	Lowest value accepted by signs and the GUI	0
volume.max	Highest value accepted by signs and the GUI	10
volume.default	Initial volume for a new jukebox sign	3
personal-default-volume	Initial personal playback volume	3
max-active-sources	Combined limit for sign, record, and personal playback sources	20
log-invalid-songs	Log malformed or unreadable .nbs files during scans	true

Values above 1 use Minecraft's extended audible radius behavior. A volume of 0 is silent.

How It Works

Song Library

Songs are stored below plugins/CustomJukebox/songs/. The plugin indexes the library and opens folders as inventory screens. /jukebox reload refreshes the index after files are added, replaced, or removed.

Jukebox Signs

Write [jukebox] on the first line of a sign. The configuration screen opens after the sign editor closes, allowing the creator to select a song, volume, looping option, and redstone mode. Right-clicking a configured sign opens its controls; sneak-right-click uses normal sign editing.

The sign stores its own configuration using Paper's persistent data container. signs.yml maintains a separate location index used by /jukebox list-signs.

Redstone Modes

Mode	Behavior
Toggle	Plays while the sign is powered and stops when power is removed
Pulse	Starts playback on a rising redstone edge
Ignore	Ignores redstone and responds only through the GUI

Custom Records

/jukebox disc <player> <song> creates a music disc whose persistent item data stores the song's relative library path. Its material is selected randomly from Minecraft's intact music discs; MUSIC_DISC_11 and all disc fragments are deliberately excluded. The title and author shown on the item come from the indexed NBS metadata.

Insert the record into an ordinary jukebox to play the bound NBS song at the configured default volume. The record remains inside the block like a vanilla disc and can be ejected normally. Its song binding survives inventory transfers, dropped items, chunk unloads, hopper movement, and server restarts. If the corresponding .nbs file is renamed or removed, the record remains intact but cannot play until that song path is restored and /jukebox reload is run.

Commands

Command	Description
/jukebox play	Open the personal song browser and playback controls
/jukebox play <path or title>	Start a song directly
/jukebox stop	Stop personal playback
/jukebox disc <player> <path or title>	Create a persistent physical record for an indexed song
/jukebox reload	Rescan the song library
/jukebox list-signs	List registered jukebox signs and their locations

Permissions

Permission	Description	Default
customjukebox.play	Use personal playback	true
customjukebox.sign.place	Create and configure jukebox signs	op
customjukebox.disc.create	Create song-bound custom records	op
customjukebox.disc.use	Insert and play custom records in jukebox blocks	true
customjukebox.admin	Reload songs and list registered signs	op

Building from Source

Requirements: Java 25 and Maven 3.9+

git clone https://github.com/Cobbleworks/Custom-Jukebox-Plugin.git
cd Custom-Jukebox-Plugin
mvn clean verify

The plugin jar is written to target/custom-jukebox-x.x.x.jar. NoteBlockAPI is resolved from CodeMC for compilation and remains a separate runtime plugin.

License

This project is licensed under the MIT License. See LICENSE for details.

Screenshots

Custom Jukebox - Management GUI	Custom Jukebox - Adventure Playback
Custom Jukebox - Sign Creation	Custom Jukebox - Redstone Sign Setup
Custom Jukebox - Registered Signs	Custom Jukebox - Reload Command