---

📑 Table of Contents

• Overview
• Dependencies
• Core Features
  • 88-Key Piano Keyboard
  • Piano-Screen MIDI Playback
  • In-Game NBS Editor
  • Real-Time Spectrum
  • NBS Playback & Repair
  • MIDI Import & Export
  • Preview System
  • Lyrics Output
  • Instrument Management
  • Speed & Transpose
• Command Reference
• GUI Cheat Sheet
• Notes
• Technical

---

Overview

Disc Jockey Plus is an unofficial fork of the original Disc Jockey, fully ported to Minecraft Java 26.2 – 26.3. On top of the original feature set it adds an 88-key piano keyboard, real-time spectrum visualization, bidirectional MIDI ↔ NBS conversion, non-destructive NBS pitch repair (Clamp / Fold), instrument remapping, a preview system, a sleep timer, an in-game NBS editor, and full localization.

Press J or run /discjockey to open the main GUI.

Check for updates in-game with:

/discjockey update

---

Dependencies

Fabric

Dependency	Version	Required
Fabric Loader	≥ 0.19.5	✅
Fabric API	≥ 0.161.0	✅
Cloth Config API	≥ 26.2.155	✅
Mod Menu	≥ 20.0.1	⬜ Optional
PianoLib	≥ 1.0.7+DJP2.7.7	⬜ Optional

NeoForge

Dependency	Version	Required
NeoForge Loader	≥ 26.3.0.52	✅

PianoLib provides the 88 high-quality piano samples used by the piano screen. Without it the mod falls back to NOTE_BLOCK_HARP with pitch shifting.

---

Core Features

🎹 88-Key Piano Keyboard

• Covers all 88 semitones, A0 (−39) ~ C8 (48), zeroed at A0 — mapped one-to-one to PianoLib / NoteBlock pitches.

• Physical keyboard mapping (C-major layout): A S D F G H J K L ; ' for white keys, W E T Y U O P for black keys. Keys 1 / 2 / 3 are fixed to A0 / A#0 / B0 for quick testing and recording.

• Octave transposition: [−] / [+] buttons, or 0 to jump back to C4. getDisp() shows the current octave offset.

• Three-tier sound path, tried in order:

  1. PianoAPI (sqlmc.api.PianoAPI)
  2. PianoLib 88-note cache (pianolib:key_0 … key_87)
  3. NOTE_BLOCK_HARP with pitch fallback

  …so sound works both on the main menu and in-world.

• MIDI recording: built-in MidiRecorder supports sustain pedal (CC64), reverb (CC91 / CC93), ADSR envelopes and per-note release times. Recordings are auto-saved to recordings/.

▶️ Piano-Screen MIDI Playback _NEW

Play .mid files straight from the piano screen — with note-block / piano timbre, live key highlighting and piano-roll animation.

Button	Position (top-left row)	Action
● REC	x=10	Start / stop MIDI recording
▶ PLAY	x=74	Play / stop the selected .mid
♪ filename.mid	x=138	Cycle to the next .mid in the folder

• MIDI files are read from config/disc_jockey/midi/ — the same folder used by Import MIDI and Export MIDI, so anything you export can be played back immediately.
• Uses javax.sound.midi.Sequencer with no internal synthesizer attached (getSequencer(false)), so notes are routed to the mod's own sound path instead of doubling up with Java's synth.
• Percussion (channel 9) is skipped; notes outside A0–C8 are ignored safely.
• While playing, the button becomes ■ STOP, keys light up, and the roll scrolls.

✏️ In-Game NBS Editor _NEW

A full piano-roll NBS editor (NoteBlockEditScreen) — write and edit .nbs songs without leaving the game.

How to open: in the Disc Jockey GUI, select a song and click ✏ 编辑 (top-left corner of the screen).

Operation	Effect
Left-click empty cell	Place a note (previews immediately)
Left-click existing note	Delete it
Space	Play / stop
← →	Scroll the timeline
↑ ↓	Scroll the pitch axis
+ / −	Zoom (row height 5–13, column width 4–16)
乐器 button	Cycle through the 16 NBS instruments
t− / t+	Tempo ±50 (range 100–4000)
SAVE	Save to config/disc_jockey/songs/<name>.nbs
AS	Save as <name>_edit.nbs
MIDI	Load the next .mid from config/disc_jockey/midi/

Details

• Pitch range −33 … 54 (88 rows), matching MidiToNbsImporter (signedNoteId = midi − 54).
• The keyboard column highlights the playable note-block range (noteId 0–24) in yellow; the grid tints that band green, so you can see at a glance which notes will need octave folding.
• Notes are packed with Note.packNoteId(packed, noteId), where packed = tick | layer<<16 | instrument<<32; uniqueNotes is rebuilt on save.
• Playback timing follows NbsToWavExporter: tickMs = 100000 / tempo.
• Preview audio uses note-block timbres (NBS is a note-block format), octave-folded into 0–24 and pitched with 2^((n−12)/12).

📊 Real-Time Spectrum

• 16-band spectrum with peak-hold and exponential decay — smooth, no ghosting.
• Five render styles, switchable with one click in the GUI: BAR · WAVE · RING · MIRROR · PARTICLE
• Shown on the main menu and as an in-world HUD (controlled by the spectrumAlwaysVisible config). Both playback and preview drive the spectrum.

🎵 NBS Playback & Repair

• Loads .nbs songs with play / pause / stop / resume / loop / shuffle / autoplay.
• Clamp / Fold (non-destructive): performs runtime octave folding for songs outside the 0–24 range. The original file is never modified and nothing is written to disk — only a foldedNotes cache is generated.
  • fold auto — enable automatic repair
  • fold scan — scan every song
  • fold info <song> — pitch-range report for one song
• Transpose: runtime octave-fold transposition that keeps #F24 from being clipped.

🎼 MIDI Import & Export

• NBS → MIDI export (disc_jockey.screen.export_midi): writes a standard .mid containing tempo, 4/4 time signature and bar markers; output goes to the midi/ folder and is opened automatically.
• MIDI → NBS import (disc_jockey.screen.import_midi): reads .mid / .midi through a built-in file chooser, parses note events, builds a Song, and falls back safely on empty files or parse failures.

👂 Preview System

• Preview from both the main menu and in-world — uses SoundSource.MASTER outside a world, then auto-switches to playLocalSound after joining one.
• M mutes / unmutes preview; P toggles preview looping. Both keybindings are customizable in Controls.
• Preview and playback are mutually exclusive — starting one stops the other.
• /discjockey autoplay now governs both the song player and the previewer, so turning it off stops the preview after the current song instead of continuing through the whole list.

📝 Lyrics Output

• Loads companion lyric data alongside songs and can output lines to chat.
• Configurable: chat output, public output, minimum interval, and DM-style delivery (burst limit, max targets, radius) — see the config screen.

🎷 Instrument Management

• instrument <name> counts nearby note blocks of the specified instrument.
• remapInstruments manages instrument mapping — map / unmap / show / clear — resolving server-side instrument detection differences.

⚡ Speed & Transpose

• speed <value> adjusts playback / preview speed (default 1.0, shared with preview stepping).
• transpose transposes the current song (octave folding, preserving #F24).

🛡️ Anti-Anti-Cheating

Reinforced anti-anti-cheat handling compared with the original Disc Jockey.

---

📜 Command Reference

Basic Playback

Command	Description
/discjockey	Open the Disc Jockey GUI
/discjockey play <song>	Play the specified song
/discjockey pause	Pause playback
/discjockey stop	Stop playback
/discjockey resume	Resume playback
/discjockey now	Show the song currently playing
/discjockey info	Show current song info and playback speed
/discjockey progress	Show playback progress

Playback Modes

Command	Description
/discjockey loop yes|no	Enable / disable single-song loop
/discjockey shuffle	Toggle shuffle mode
/discjockey autoplay	Toggle auto-play (queue continuation)
/discjockey random	Play a random song from the GUI list

Preview

Command / Key	Description
/discjockey preview <song>	Preview a song, or show preview status
M	Mute / unmute preview
P	Enable / disable preview looping

Keybindings are customizable in Controls.

Speed & Transpose

Command	Description
/discjockey speed <value>	Adjust playback speed
/discjockey transpose	Transpose the current song

NBS Repair (Clamp / Fold)

Non-destructive and temporary — the original file is never modified.

Command	Description
/discjockey clamp <xxx.nbs>	Temporarily repair the specified song
/discjockey unclamp	Cancel repair
/discjockey clampstatus	Show the current repair status
/discjockey fold auto	Enable automatic repair
/discjockey fold info <xxx.nbs>	Pitch-range report for one song
/discjockey fold rebuild	Re-run repair (refresh status)
/discjockey fold scan	Scan all songs for needed repair
/discjockey fold status	Same as clampstatus

Instrument Management

Command	Description
/discjockey instrument <name>	Count nearby note blocks of an instrument
/discjockey remapInstruments map <src> <dst>	Create an instrument mapping
/discjockey remapInstruments unmap <src> <dst>	Remove a mapping
/discjockey remapInstruments show	Show current mappings
/discjockey remapInstruments clear	Clear all mappings

Utilities

Command	Description
/discjockey reload	Reload all songs (includes hot-reload watching)
/discjockey spectrum	Toggle the in-GUI spectrum display
/discjockey sleep <seconds>	Stop playback after a timer / cancel it
/discjockey update	Check for updates in-game
/discjockey help	Show help

---

🖥️ GUI Cheat Sheet

Disc Jockey main screen

Control	Location	Action
✏ 编辑	Top-left	Open the NBS editor for the selected song
⚙	Bottom-left	Open the config screen
🎹 🎶→	Bottom bar	Open the piano screen
Search box	Top	Filter songs
Right-click a song	List	Show song details

Piano screen

Control	Location	Action
● REC	x=10	Start / stop MIDI recording
▶ PLAY	x=74	Play / stop the selected .mid
♪ filename	x=138	Cycle to the next .mid
🔊 / 🔇	Top-right	Toggle note-block broadcast
X	Top-right	Close (auto-saves any recording)
[−] [+] C4 CLR SCN	Below the roll	Octave / reset / clear / rescan

NBS editor

See In-Game NBS Editor.

---

📌 Notes

• Only legal .nbs files are supported.
• Clamp / Fold is non-destructive: it only takes effect at runtime and reverts when disabled or cancelled.
• The GUI includes real-time spectrum visualization (5 styles).
• All keybindings can be customized in Controls.
• Requires Fabric Loader + Minecraft 26.2–26.3 (NeoForge support is in development); optionally depends on PianoLib / sqlmc.PianoAPI for high-quality piano sound.
• MIDI playback and the NBS editor read from config/disc_jockey/midi/; songs live in config/disc_jockey/songs/.

---

🔧 Technical

• Two-layer spectrum architecture — SpectrumDataSmoother (peak-hold + exponential decay) and SpectrumVisualizer (unified playback/preview source) — for stable, non-pegging rendering.
• Playback uses SongPlayer (configurable async playback, RateLimiter-based packet rate limiting, sleep timer) together with Tuner (multi-layer fallback note-block lookup after octave folding).
• Cross-frame safe GUI opening: Main.openScreenOnNextTick defers screen requests to the next tick via a ConcurrentLinkedQueue, avoiding the race where a closing chat screen carries the new GUI away with it.
• NBS editor reuses the existing conversion layer: MidiToNbsImporter for MIDI → NBS, NbsToMidiExporter.writeNbs() for saving, and Note.packNoteId / Note.extractNoteId for note packing — so edited files stay byte-compatible with the rest of the mod.
• Obfuscation-friendly: all Screen subclasses, MidiRecorder, and reflection-using classes (PianoPlayer / DiscJockeyHud) are preserved verbatim via ProGuard keep rules to prevent VerifyError.

---

---

📑 目录

• 简介
• 依赖项目
• 核心功能
  • 88 键钢琴键盘
  • 钢琴界面 MIDI 回放
  • 游戏内 NBS 编辑器
  • 实时频谱可视化
  • NBS 播放与修复
  • MIDI 双向转换
  • 预览系统
  • 歌词输出
  • 乐器管理
  • 速度与移调
• 指令大全
• 界面速查
• 注意事项
• 技术说明

---

简介

Disc Jockey Plus 是原版 Disc Jockey 的非官方分支，已完整适配 Minecraft Java 版 26.2 – 26.3。在原版基础上追加了 88 键钢琴键盘、 实时频谱可视化、MIDI ↔ NBS 双向转换、NBS 音域修复（Clamp / Fold）、 音色映射、预览系统、睡眠定时器、游戏内 NBS 编辑器，并内置完整多语言支持。

按 J 键或输入 /discjockey 即可打开主界面。

游戏内检查更新：

/discjockey update

---

依赖项目

Fabric

依赖	版本	必需
Fabric Loader	≥ 0.19.5	✅
Fabric API	≥ 0.161.0	✅
Cloth Config API	≥ 26.2.155	✅
Mod Menu	≥ 20.0.1	⬜ 可选
PianoLib	≥ 1.0.7+DJP2.7.7	⬜ 可选

NeoForge

依赖	版本	必需
NeoForge Loader	≥ 26.3.0.76	✅

PianoLib 提供钢琴界面所用的 88 个高品质钢琴采样；未安装时自动回退到 NOTE_BLOCK_HARP 变调发声。

---

核心功能

🎹 88 键钢琴键盘

• 完整覆盖 88 个半音，A0（−39）~ C8（48），零点为 A0，与 PianoLib / NoteBlock 音高一一对应。

• 物理键盘映射（C 大调布局）：白键 A S D F G H J K L ; '， 黑键 W E T Y U O P；1 / 2 / 3 固定映射 A0 / A#0 / B0，便于试音与录制。

• 八度移调：[−] / [+] 按钮，或 0 键一键回到 C4； getDisp() 显示当前八度偏移。

• 三级发声路径，依次择优：

  1. PianoAPI（sqlmc.api.PianoAPI）
  2. PianoLib 88 音缓存（pianolib:key_0 … key_87）
  3. NOTE_BLOCK_HARP 变调兜底

  因此主菜单与世界内均可发声。

• MIDI 录制：内置 MidiRecorder，支持延音踏板（CC64）、混响（CC91 / CC93）、 ADSR 包络与按音区分段的释放时间；录音自动保存至 recordings/ 目录。

▶️ 钢琴界面 MIDI 回放 _NEW

在钢琴界面直接播放 .mid 文件，使用音符盒 / 钢琴音色，并同步点亮琴键、驱动滚落动画。

按钮	位置（左上角一行）	作用
● REC	x=10	开始 / 停止 MIDI 录制
▶ PLAY	x=74	播放 / 停止当前 .mid
♪ 文件名.mid	x=138	切换到下一首 .mid

• MIDI 文件读取自 config/disc_jockey/midi/ —— 与「导入 MIDI」「导出 MIDI」 共用同一目录，导出的文件可立即回放。
• 使用 javax.sound.midi.Sequencer 且不挂载 Java 自带合成器 （getSequencer(false)），音符统一走模组自身发声通道，避免双重发声。
• 自动跳过打击乐轨（通道 9）；超出 A0–C8 的音符安全忽略。
• 播放中按钮变为 ■ STOP，琴键高亮、Piano Roll 同步滚落。

✏️ 游戏内 NBS 编辑器 _NEW

内置完整的钢琴卷帘 NBS 编辑器（NoteBlockEditScreen），无需离开游戏即可编写、 修改 .nbs 曲目。

打开方式：在 Disc Jockey 主界面选中一首曲子，点击 ✏ 编辑 （位于界面左上角）。

操作	效果
左键点击空格	放置音符（立即试听）
左键点击已有音符	删除该音符
空格	播放 / 停止
← →	横向滚动时间轴
↑ ↓	纵向滚动音高轴
+ / −	缩放（行高 5–13、列宽 4–16）
乐器 按钮	循环切换 16 种 NBS 乐器
t− / t+	速度 ±50（范围 100–4000）
SAVE	保存到 config/disc_jockey/songs/<名称>.nbs
AS	另存为 <名称>_edit.nbs
MIDI	载入 config/disc_jockey/midi/ 中的下一个 .mid

实现要点

• 音高范围 −33 … 54（共 88 行），与 MidiToNbsImporter 完全一致 （signedNoteId = midi − 54）。
• 左侧键盘列用黄色标出音符盒可发声区（noteId 0–24），网格中该区间带绿色底色， 一眼即可看出哪些音符需要八度折叠。
• 音符打包复用 Note.packNoteId(packed, noteId)，其中 packed = tick | layer<<16 | instrument<<32；保存时自动重建 uniqueNotes。
• 播放时序沿用 NbsToWavExporter：tickMs = 100000 / tempo。
• 试听使用音符盒音色（NBS 属音符盒格式），先八度折叠到 0–24， 再以 2^((n−12)/12) 计算音高。

📊 实时频谱可视化

• 16 段频谱，峰值保持 + 指数衰减，渲染丝滑无重影。
• 5 种渲染样式，GUI 内一键切换： 条形 BAR · 波形 WAVE · 圆环 RING · 镜像 MIRROR · 粒子 PARTICLE
• 主菜单与世界内 HUD 常驻显示（由 spectrumAlwaysVisible 配置项控制）； 播放与预览均驱动频谱。

🎵 NBS 播放与修复

• 加载 .nbs 曲目，支持播放 / 暂停 / 停止 / 恢复 / 循环 / 随机 / 自动连播。
• Clamp / Fold（非破坏性）：对超出 0~24 音域的曲目做运行时八度折叠， 不改原文件、不写盘，仅生成 foldedNotes 缓存。
  • fold auto 启用自动修复
  • fold scan 扫描全部曲目
  • fold info <曲目> 查看单首音域报告
• 移调：运行时八度折叠移调，保护 #F24 不被压掉。

🎼 MIDI 双向转换

• NBS → MIDI 导出（disc_jockey.screen.export_midi）：导出标准 .mid， 含速度、4/4 拍号与小节线标记，输出至 midi/ 目录并自动打开。
• MIDI → NBS 导入（disc_jockey.screen.import_midi）：通过内置文件选择器读取 .mid / .midi，解析音符事件并生成 Song，空文件与解析失败均有安全兜底。

👂 预览系统

• 主菜单与世界内均可预览；世界外使用 SoundSource.MASTER，进世界后自动切换为 playLocalSound。
• M 预览静音 / 取消静音；P 开启 / 关闭预览循环； 按键绑定可在「控制」中自定义。
• 预览与播放互斥：启动一方自动停止另一方。
• /discjockey autoplay 现在同时控制播放器与预览器 —— 关闭后预览会在 当前这首播完时停止，而不再继续串联整个列表。

📝 歌词输出

• 随曲目加载配套歌词数据，并可输出到聊天栏。
• 可配置项：聊天输出、公共输出、最小间隔，以及私信式推送 （突发上限、最大目标数、推送半径）—— 详见配置界面。

🎷 乐器管理

• instrument <名称> 统计周围指定乐器的音符盒数量。
• remapInstruments 音色映射管理：map / unmap / show / clear， 把一种乐器映射到另一种，解决服务器乐器判定差异。

⚡ 速度与移调

• speed <数值> 调整播放 / 预览速度（默认 1.0，与预览步进共享）。
• transpose 对当前曲目移调（八度折叠，保护 #F24 不被压掉）。

🛡️ 防反作弊

增强了原版 Disc Jockey 的防反作弊处理。

---

📜 指令大全

基础播放控制

指令	说明
/discjockey	打开 Disc Jockey GUI
/discjockey play <曲目>	播放指定曲目
/discjockey pause	暂停播放
/discjockey stop	停止播放
/discjockey resume	恢复播放
/discjockey now	查看当前正在播放的曲目
/discjockey info	查看当前曲目信息与播放速度
/discjockey progress	查看播放进度

播放模式

指令	说明
/discjockey loop yes|no	开启 / 关闭单曲循环
/discjockey shuffle	切换随机播放模式
/discjockey autoplay	开启 / 关闭自动连播
/discjockey random	随机播放 GUI 列表中的一首曲目

预览系统

指令 / 按键	说明
/discjockey preview <曲目>	预览指定曲目或查看预览状态
M	预览静音 / 取消静音
P	开启 / 关闭预览循环

按键绑定可在「控制」设置中修改。

速度与移调

指令	说明
/discjockey speed <数值>	调整播放速度
/discjockey transpose	对当前曲目进行移调

NBS 修复

修复为临时、非破坏性操作，不会改动原文件。

指令	说明
/discjockey clamp <xxx.nbs>	对指定曲目进行临时修复
/discjockey unclamp	取消修复
/discjockey clampstatus	检查当前修复状态
/discjockey fold auto	启用自动修复
/discjockey fold info <xxx.nbs>	查看单首曲目的修复状态
/discjockey fold rebuild	重新执行修复（刷新状态）
/discjockey fold scan	扫描所有曲目是否需要修复
/discjockey fold status	等同于 clampstatus

乐器管理

指令	说明
/discjockey instrument <名称>	统计周围指定乐器的音符盒数量
/discjockey remapInstruments map <源> <目标>	建立音色映射
/discjockey remapInstruments unmap <源> <目标>	移除指定映射
/discjockey remapInstruments show	查看当前映射状态
/discjockey remapInstruments clear	清空所有音色映射

实用工具

指令	说明
/discjockey reload	重新加载所有曲目（含热重载监听）
/discjockey spectrum	开启 / 关闭 GUI 内频谱显示
/discjockey sleep <秒数>	定时停止播放 / 取消定时
/discjockey update	游戏内检查更新
/discjockey help	查看帮助信息

---

🖥️ 界面速查

Disc Jockey 主界面

控件	位置	作用
✏ 编辑	左上角	为选中曲目打开 NBS 编辑器
⚙	左下角	打开配置界面
🎹 🎶→	底部栏	打开钢琴界面
搜索框	顶部	过滤曲目
右键曲目	列表	查看曲目详情

钢琴界面

控件	位置	作用
● REC	x=10	开始 / 停止 MIDI 录制
▶ PLAY	x=74	播放 / 停止当前 .mid
♪ 文件名	x=138	切换到下一首 .mid
🔊 / 🔇	右上角	切换音符盒广播
X	右上角	关闭（自动保存录音）
[−] [+] C4 CLR SCN	滚落区下方	八度 / 复位 / 清空 / 重扫

NBS 编辑器

详见 游戏内 NBS 编辑器。

---

📌 注意事项

• 仅支持带有 .nbs 后缀名的合法音乐文件。
• Clamp / Fold 为非破坏性操作，仅临时生效，关闭或取消后恢复原状。
• GUI 内自带实时频谱可视化（5 种样式可切换）。
• 所有快捷键均支持在「控制」设置中自定义。
• 依赖 Fabric Loader + Minecraft 26.2–26.3（NeoForge 支持开发中）； 可选依赖 PianoLib / sqlmc.PianoAPI 以获得高品质钢琴音色。
• MIDI 回放与 NBS 编辑器读取 config/disc_jockey/midi/； 曲目存放于 config/disc_jockey/songs/。

---

🔧 技术说明

• 采用 SpectrumDataSmoother（峰值保持 + 指数衰减）与 SpectrumVisualizer（统一播放/预览数据源）双层架构，频谱稳定无卡顶。
• 播放采用 SongPlayer（可配置异步播放、基于 RateLimiter 的发包限速、睡眠定时器）
  • Tuner（八度折叠后多层 fallback 查找音符盒）。
• 跨帧安全开界面：Main.openScreenOnNextTick 通过 ConcurrentLinkedQueue 把界面请求推迟到下一 tick，规避聊天框关闭带走界面的竞争。
• NBS 编辑器复用既有转换层：MIDI → NBS 走 MidiToNbsImporter， 保存走 NbsToMidiExporter.writeNbs()，音符打包走 Note.packNoteId / Note.extractNoteId，保证编辑产物与模组其余部分字节兼容。
• 混淆友好：所有 Screen 子类、MidiRecorder，以及使用反射的类 （PianoPlayer / DiscJockeyHud）均通过 ProGuard keep 规则原样保留，避免 VerifyError。

---