CustomJukebox
在你的 Minecraft 服务器上播放真正的音乐。 CustomJukebox 将唱片机转变为完整的音乐系统:支持使用你自己的 .ogg 音轨制作自定义唱片、播放列表,以及当玩家进入特定区域时自动播放背景音乐的动态区域——这一切都无需替换任何原版唱片。
专为 Paper 和 Folia 构建,通过 JSON 进行配置,并已翻译为四种语言。
? 使用 Bedrock 版玩家?
CustomJukebox 从 Java 版的资源包中流式传输音频,而 Bedrock 客户端对其处理方式不同。如果你运行 Geyser/Floodgate,请安装配套插件:
它会挂钩到此插件触发的公共 API 事件,因此 CustomJukebox 端无需额外配置——只需同时安装两者即可协同工作。
?️ 还没有资源包?
正确设置资源包是最繁琐的部分。有四个名称必须一致——.ogg 路径、sounds.json 中的事件键、其中的 name 字段以及 disc.json 中的 sound 字段——只要有一个不匹配就会导致无声,且两侧都不会报错。
将你的音频放入其中,即可获得一个可直接托管的 pack.zip、匹配的 disc.json 以及两条已计算好 SHA-1 值的 server.properties 行。它会在你的浏览器中将 mp3、wav 和 flac 转换为 Ogg Vorbis 格式——无需上传,你的音乐永远不会离开你的设备——还会绘制唱片和碎片的纹理,并支持加载现有资源包,以便你在不破坏现有功能的情况下添加新音轨。
✨ 功能特性
? 自定义音乐唱片
- 添加你自己的音乐唱片,而无需覆盖原版唱片
- 通过资源包(
.ogg)实现真实音频——全音质,而非音符盒
- 可自定义标题、作者、描述文本(Lore)和 CustomModelData
- 在配置的曲目长度到达时自动停止
- 可在
disc.json 中管理,或通过管理员 GUI 在游戏中完全管理
? 动态区域与服务器广播
让背景音乐在玩家进入区域时自动开始播放——无需唱片、指令或红石。
- 四种区域类型: 半径、长方体、WorldGuard 区域,或全局(一种覆盖所有世界每位玩家的服务器级广播电台)
- 优先级决定当多个区域重叠时哪个生效——例如大厅区域的优先级可以高于广播电台
- 两种播放模式:
synced(所有人同时听到同一首曲目——适合活动场合)或 individual(每位玩家从进入时刻起听到完整的曲目——适合大厅场景)
- 高度范围: 覆盖整个垂直柱体(默认),或在 Y 轴上限制区域,形成真正的 3D 球体/立方体
- 循环与随机播放,每次循环结束后重新洗牌
- 每个区域可独立设置音量和播放列表
? 播放列表与分类
- 将唱片分组到播放列表中并按顺序播放
- 随机播放和重复模式(
loop、repeat-one)
- 每个播放列表的播放范围:正常、整个世界、服务器全局,或自定义半径(以方块为单位)
- 分类功能,用于整理大型唱片收藏
? 玩家控制
默认情况下每位玩家都拥有这些权限——无需进行权限设置。
/cjb music on|off —— 完全退出插件音乐,设置跨会话保存
/cjb music volume —— 个人音量,独立于服务器设置
/cjb skip —— 跳过当前正在播放的曲目
/cjb favorite —— 创建个人收藏列表并将其作为播放列表播放;也可在唱片菜单中按住 Shift 右键点击唱片来收藏
- 进度条 —— 可选的 Boss 栏,显示当前曲目及其播放进度
? 碎片系统
- 收集唱片碎片并合成为完整唱片(无形状合成,数量可配置)
- 爬行者掉落: 骷髅击杀爬行者时必定掉落,玩家击杀时掉落概率可配置
- 战利品集成: 碎片会出现在地牢、堡垒遗迹、末地城、遗迹废墟等地方
?️ 游戏内管理
- 唱片机 GUI —— 右键点击空的唱片机以选择唱片
- 管理面板 (
/cjb gui) —— 创建、编辑和删除唱片、播放列表和分类,无需触碰文件
- 带有输入验证的分步创建向导
- 区域编辑器 GUI,明确指出某个区域尚未播放的原因
- 所有列表均支持分页,确保大型收藏仍可完全访问
- 对破坏性操作提供删除确认
? 集成与兼容性
- Paper 1.21.4 – 26.x 和 Folia(区域线程调度,自动检测)
- WorldGuard —— 尊重
USE 标志,并可将动态区域绑定到指定区域
- GriefPrevention —— 尊重容器信任机制
- PlaceholderAPI —— 16 个占位符(手中持有的唱片、音量、静音状态、总数等)
- 多语言支持: 英语、德语、西班牙语、意大利语——完全翻译,可编辑
- 开发者 API,包含四个 Bukkit 事件(
DiscPlaybackStart/Stop、DiscRegistered/Removed)
- bStats 指标数据(可选择退出)
? 鹦鹉跳舞
鹦鹉会对一定半径内的自定义音乐做出反应。
? 命令
对所有玩家可用
| 命令 |
描述 |
/cjb music <on|off|toggle|volume <0-4|reset>|status> |
你的个人音乐设置 |
/cjb skip |
跳过当前正在听到的曲目 |
/cjb favorite <add|remove|toggle|list|play|clear> |
管理和播放你的收藏 |
/cjb gui |
打开唱片菜单 |
/cjb list [page] · /cjb info <disc> |
浏览唱片 |
对管理员可用
| 命令 |
描述 |
/cjb zone <...> |
创建和管理动态区域及广播电台 |
/cjb playlist <...> |
创建和播放播放列表 |
/cjb play <disc> [loop] [global|world|<radius>] |
在你所在位置播放一张唱片 |
/cjb give · /cjb fragment |
发放唱片和碎片 |
/cjb volume · /cjb mute · /cjb unmute |
服务器全局音量 |
/cjb stop · /cjb reload |
停止播放 / 重载配置 |
别名:/customjukebox, /jukebox, /jb
? 权限
| 权限 |
默认值 |
说明 |
customjukebox.use |
everyone |
使用唱片机 |
customjukebox.gui · .list · .info |
everyone |
浏览唱片 |
customjukebox.music · .favorite · .skip |
everyone |
个人设置、收藏、跳过 |
customjukebox.admin |
op |
所有管理命令(父级) |
customjukebox.zone · .playlist · .play · .stop · .volume |
op |
独立的管理权限 |
customjukebox.give · .fragment · .reload |
op |
物品发放与重载 |
customjukebox.bypass.protection |
op |
忽略 WorldGuard/GriefPrevention 检查 |
? 依赖项
- 服务端: Paper 1.21.4+ 或 Folia(也可在 26.x 上运行)
- Java: 21 或更高版本
- 一个资源包,其中包含你的
.ogg 文件 —— 用于使自定义音效可被听到
- 可选: WorldGuard、GriefPrevention、PlaceholderAPI、Geyser/Floodgate(需配合 Bedrock Extension)
? 快速开始
- 将 JAR 放入
plugins/ 目录并启动服务器。它将创建 config.json、disc.json、zones.json 以及 languages/ 文件夹。
- 将你的
.ogg 文件放入资源包并在 sounds.json 中注册它们 —— 或者让 Pack Generator 为你构建资源包、纹理以及匹配的 disc.json。
- 托管该资源包,并在
server.properties 中设置 resource-pack 和 resource-pack-sha1。
- 创建一张唱片 —— 最简单的方法是通过
/cjb gui → Admin Panel → Disc Management,或编辑 disc.json。
/cjb reload
大厅音乐仅需四条命令
/cjb playlist create lobby-mix
/cjb playlist add lobby-mix my_track
/cjb zone create lobby # 以你站立的位置为中心
/cjb zone radius lobby 60
/cjb zone playlist lobby lobby-mix
区域默认启用且循环播放。若要覆盖整个服务器的电台,请使用 /cjb zone global <id> 代替半径设置。
⚙️ 配置
config.json —— 显示的每个值均为默认值:
{
"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
}
}
环境区域位于 zones.json,唱片和播放列表位于 disc.json,每位玩家的设置位于 players.json。所有文件均以异步方式写入并原子替换,因此保存操作永远不会阻塞服务器主线程,且中断的写入不会导致配置文件损坏。
? 链接
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:
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.
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
- Drop the JAR into
plugins/ and start the server. It creates config.json, disc.json, zones.json and the languages/ folder.
- 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.
- Host the pack and set
resource-pack plus resource-pack-sha1 in server.properties.
- Create a disc — easiest through
/cjb gui → Admin Panel → Disc Management, or by editing disc.json.
/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
评论 0
登录后参与评分
还没有评论,来抢沙发吧