Disc Jockey Plus

[center][size=6][b]🎵 Disc Jockey Plus[/b][/size] [size=4][b]A professional note-block music mod for Minecraft Java 26.2 – 26.3[/b][/size] [i]Unofficial fork of the original [b]Disc Jockey[/b] — fully ported to 26.2 / 26.3[/i]

Built-in i18n · Real-time Spectrum · 88-Key Piano · In-Game NBS Editor · MIDI ↔ NBS

[color=green][b][Fabric] ✅ Stable[/b][/color] — Fabric Loader ≥ 0.19.5 [color=orange][b][NeoForge] ✅ Stable[/b][/color] — NeoForge ≥ 26.3.0.76

[color=red][b]⚠️ Do NOT use NeoForge 26.3.0.56-beta — that build is broken and will crash.[/b][/color]

💬 Want the latest updates? Search [b]SQL_Minecraft[/b] on Bilibili and subscribe![/center]

[h1]Overview[/h1]

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

Press [b]J[/b] or run [code]/discjockey[/code] to open the main GUI.

Check for updates in-game with [code]/discjockey update[/code].

[h1]Dependencies[/h1]

[h3]Fabric[/h3] [list] [_][b]Fabric Loader[/b] ≥ 0.19.5 — [color=green]Required[/color] [_][b]Fabric API[/b] ≥ 0.161.0 — [color=green]Required[/color] [_][b]Cloth Config API[/b] ≥ 26.2.155 — [color=green]Required[/color] [_][b]Mod Menu[/b] ≥ 20.0.1 — Optional [*][b]PianoLib[/b] ≥ 1.0.7+DJP2.7.7 — Optional [/list]

[h3]NeoForge[/h3] [list] [*][b]NeoForge Loader[/b] ≥ 26.3.0.52 -beta — [color=green]Required[/color] [/list]

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

[h1]Core Features[/h1]

[h2]🎹 88-Key Piano Keyboard[/h2] [list] [_]Covers all [b]88 semitones[/b], [b]A0 (−39) ~ C8 (48)[/b], zeroed at A0 — mapped one-to-one to PianoLib / NoteBlock pitches. [_][b]Physical keyboard mapping[/b] (C-major layout): [code]A S D F G H J K L ; '[/code] for white keys, [code]W E T Y U O P[/code] for black keys. Keys [b]1[/b] / [b]2[/b] / [b]3[/b] are fixed to A0 / A#0 / B0 for quick testing and recording. [_][b]Octave transposition[/b]: [code][−][/code] / [code][+][/code] buttons, or [b]0[/b] to jump back to C4. [_][b]Three-tier sound path[/b], tried in order: [list=1] [_][code]PianoAPI/code [_]PianoLib 88-note cache ([code]pianolib:key_0[/code] … [code]key_87[/code]) [_][code]NOTE_BLOCK_HARP[/code] with pitch fallback [/list] …so sound works both on the main menu and in-world. [_][b]MIDI recording[/b]: built-in [code]MidiRecorder[/code] supports sustain pedal (CC64), reverb (CC91 / CC93), ADSR envelopes and per-note release times. Recordings are auto-saved to [code]recordings/[/code]. [/list]

[h2]▶️ Piano-Screen MIDI Playback [color=green][NEW][/color][/h2]

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

[list] [_][code]● REC[/code] at [code]x=10[/code] — start / stop MIDI recording [_][b][code]▶ PLAY[/code][/b] at [code]x=74[/code] — play / stop the selected [code].mid[/code] [*][b][code]♪ filename.mid[/code][/b] at [code]x=138[/code] — cycle to the next [code].mid[/code] in the folder [/list]

[list] [_]MIDI files are read from [b][code]config/disc_jockey/midi/[/code][/b] — the same folder used by [i]Import MIDI[/i] and [i]Export MIDI[/i], so anything you export can be played back immediately. [_]Uses [code]javax.sound.midi.Sequencer[/code] with [b]no internal synthesizer attached/b, 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 [code]■ STOP[/code], keys light up, and the roll scrolls. [/list]

[h2]✏️ In-Game NBS Editor [color=green][NEW][/color][/h2]

A full [b]piano-roll NBS editor/b — write and edit [code].nbs[/code] songs without leaving the game.

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

[list] [_][b]Left-click empty cell[/b] — place a note (previews immediately) [_][b]Left-click existing note[/b] — delete it [_][b]Space[/b] — play / stop [_][b]←[/b] [b]→[/b] — scroll the timeline [_][b]↑[/b] [b]↓[/b] — scroll the pitch axis [_][code]+[/code] / [code]−[/code] — zoom (row height 5–13, column width 4–16) [_][b]Instrument[/b] button — cycle through the 16 NBS instruments [_][code]t−[/code] / [code]t+[/code] — tempo ±50 (range 100–4000) [_][code]SAVE[/code] — save to [code]config/disc_jockey/songs/<name>.nbs[/code] [_][code]AS[/code] — save as [code]<name>_edit.nbs[/code] [*][code]MIDI[/code] — load the next [code].mid[/code] from [code]config/disc_jockey/midi/[/code] [/list]

[spoiler=Implementation details] [list] [_][b]Pitch range[/b] −33 … 54 (88 rows), matching [code]MidiToNbsImporter[/code] ([code]signedNoteId = midi − 54[/code]). [_]The keyboard column highlights the [b]playable note-block range[/b] ([code]noteId 0–24[/code]) 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 [code]Note.packNoteId(packed, noteId)[/code], where [code]packed = tick | layer<<16 | instrument<<32[/code]; [code]uniqueNotes[/code] is rebuilt on save. [_]Playback timing follows [code]NbsToWavExporter[/code]: [code]tickMs = 100000 / tempo[/code]. [*][b]Preview audio uses note-block timbres[/b] (NBS is a note-block format), octave-folded into 0–24 and pitched with [code]2^((n−12)/12)[/code]. [/list] [/spoiler]

[h2]📊 Real-Time Spectrum[/h2] [list] [_][b]16-band[/b] spectrum with peak-hold and exponential decay — smooth, no ghosting. [_][b]Five render styles[/b], switchable with one click in the GUI: [code]BAR[/code] · [code]WAVE[/code] · [code]RING[/code] · [code]MIRROR[/code] · [code]PARTICLE[/code] [*]Shown on the main menu and as an in-world HUD (controlled by the [code]spectrumAlwaysVisible[/code] config). Both playback and preview drive the spectrum. [/list]

[h2]🎵 NBS Playback & Repair[/h2] [list] [_]Loads [code].nbs[/code] songs with [b]play / pause / stop / resume / loop / shuffle / autoplay[/b]. [_][b]Clamp / Fold (non-destructive)[/b]: 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 [code]foldedNotes[/code] cache is generated. [list] [_][code]fold auto[/code] — enable automatic repair [_][code]fold scan[/code] — scan every song [_][code]fold info <song>[/code] — pitch-range report for one song [/list] [_][b]Transpose[/b]: runtime octave-fold transposition that keeps [code]#F24[/code] from being clipped. [/list]

[h2]🎼 MIDI Import & Export[/h2] [list] [_][b]NBS → MIDI export/b: writes a standard [code].mid[/code] containing tempo, 4/4 time signature and bar markers; output goes to the [code]midi/[/code] folder and is opened automatically. [_][b]MIDI → NBS import/b: reads [code].mid[/code] / [code].midi[/code] through a built-in file chooser, parses note events, builds a [code]Song[/code], and falls back safely on empty files or parse failures. [/list]

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

[h2]📝 Lyrics Output[/h2] [list] [_]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. [/list]

[h2]🎷 Instrument Management[/h2] [list] [_][code]instrument <name>[/code] counts nearby note blocks of the specified instrument. [_][code]remapInstruments[/code] manages instrument mapping — [code]map[/code] / [code]unmap[/code] / [code]show[/code] / [code]clear[/code] — resolving server-side instrument detection differences. [/list]

[h2]⚡ Speed & Transpose[/h2] [list] [_][code]speed <value>[/code] adjusts playback / preview speed (default [code]1.0[/code], shared with preview stepping). [_][code]transpose[/code] transposes the current song (octave folding, preserving [code]#F24[/code]). [/list]

[h2]🛡️ Anti-Anti-Cheating[/h2] Reinforced anti-anti-cheat handling compared with the original Disc Jockey.

[h1]📜 Command Reference[/h1]

[spoiler=Basic Playback] [list] [_][code]/discjockey[/code] — Open the Disc Jockey GUI [_][code]/discjockey play <song>[/code] — Play the specified song [_][code]/discjockey pause[/code] — Pause playback [_][code]/discjockey stop[/code] — Stop playback [_][code]/discjockey resume[/code] — Resume playback [_][code]/discjockey now[/code] — Show the song currently playing [_][code]/discjockey info[/code] — Show current song info and playback speed [_][code]/discjockey progress[/code] — Show playback progress [/list] [/spoiler]

[spoiler=Playback Modes] [list] [_][code]/discjockey loop yes|no[/code] — Enable / disable single-song loop [_][code]/discjockey shuffle[/code] — Toggle shuffle mode [_][code]/discjockey autoplay[/code] — Toggle auto-play (queue continuation) [_][code]/discjockey random[/code] — Play a random song from the GUI list [/list] [/spoiler]

[spoiler=Preview] [list] [_][code]/discjockey preview <song>[/code] — Preview a song, or show preview status [_][b]M[/b] — Mute / unmute preview [*][b]P[/b] — Enable / disable preview looping [/list] Keybindings are customizable in [b]Controls[/b]. [/spoiler]

[spoiler=Speed & Transpose] [list] [_][code]/discjockey speed <value>[/code] — Adjust playback speed [_][code]/discjockey transpose[/code] — Transpose the current song [/list] [/spoiler]

[spoiler=NBS Repair (Clamp / Fold)]

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

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

[spoiler=Instrument Management] [list] [_][code]/discjockey instrument <name>[/code] — Count nearby note blocks of an instrument [_][code]/discjockey remapInstruments map <src> <dst>[/code] — Create an instrument mapping [_][code]/discjockey remapInstruments unmap <src> <dst>[/code] — Remove a mapping [_][code]/discjockey remapInstruments show[/code] — Show current mappings [*][code]/discjockey remapInstruments clear[/code] — Clear all mappings [/list] [/spoiler]

[spoiler=Utilities] [list] [_][code]/discjockey reload[/code] — Reload all songs (includes hot-reload watching) [_][code]/discjockey spectrum[/code] — Toggle the in-GUI spectrum display [_][code]/discjockey sleep <seconds>[/code] — Stop playback after a timer / cancel it [_][code]/discjockey update[/code] — Check for updates in-game [*][code]/discjockey help[/code] — Show help [/list] [/spoiler]

[h1]🖥️ GUI Cheat Sheet[/h1]

[h3]Disc Jockey main screen[/h3] [list] [_][code]✏ 编辑[/code] — [b]Top-left[/b] — Open the NBS editor for the selected song [_][code]⚙[/code] — Bottom-left — Open the config screen [_][code]🎹 🎶→[/code] — Bottom bar — Open the piano screen [_]Search box — Top — Filter songs [*]Right-click a song — List — Show song details [/list]

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

[h3]NBS editor[/h3] See the [b]In-Game NBS Editor[/b] section above.

[h1]📌 Notes[/h1] [list] [_]Only [b]legal [code].nbs[/code] files[/b] are supported. [_][b]Clamp / Fold[/b] 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 [b]Controls[/b]. [_]Requires [b]Fabric Loader[/b] + Minecraft 26.2–26.3 (NeoForge support is in development); optionally depends on [b]PianoLib[/b] / [code]sqlmc.PianoAPI[/code] for high-quality piano sound. [_]MIDI playback and the NBS editor read from [code]config/disc_jockey/midi/[/code]; songs live in [code]config/disc_jockey/songs/[/code]. [/list]

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

[hr][hr]

[center][size=6][b]🎵 Disc Jockey Plus[/b][/size] [size=4][b]为 Minecraft Java 版 26.2 – 26.3 打造的专业级音符盒音乐模组[/b][/size] [i]原版 [b]Disc Jockey[/b] 的非官方分支 · 完整适配 26.2 / 26.3[/i]

内置多语言 · 实时频谱 · 88 键钢琴 · 游戏内 NBS 编辑器 · MIDI ↔ NBS 互转

[color=green][b][Fabric] ✅ 稳定主分支[/b][/color] — Fabric Loader ≥ 0.19.5 [color=orange][b][NeoForge] ✅ 稳定分支[/b][/color] — NeoForge ≥ 26.3.0.76

[color=red][b]⚠️ 切勿使用 NeoForge 26.3.0.56-beta —— 该版本本身有问题，会崩溃。[/b][/color]

💬 想要获取最新更新？在 B 站搜索 [b]SQL_Minecraft[/b] 并关注我！[/center]

[h1]简介[/h1]

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

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

游戏内检查更新：[code]/discjockey update[/code]

[h1]依赖项目[/h1]

[h3]Fabric[/h3] [list] [_][b]Fabric Loader[/b] ≥ 0.19.5 — [color=green]必需[/color] [_][b]Fabric API[/b] ≥ 0.161.0 — [color=green]必需[/color] [_][b]Cloth Config API[/b] ≥ 26.2.155 — [color=green]必需[/color] [_][b]Mod Menu[/b] ≥ 20.0.1 — 可选 [*][b]PianoLib[/b] ≥ 1.0.7+DJP2.7.7 — 可选 [/list]

[h3]NeoForge[/h3] [list] [*][b]NeoForge Loader[/b] ≥ 26.3.0.52 — [color=green]必需[/color] [/list]

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

[h1]核心功能[/h1]

[h2]🎹 88 键钢琴键盘[/h2] [list] [_]完整覆盖 [b]88 个半音[/b]，[b]A0（−39）~ C8（48）[/b]，零点为 A0，与 PianoLib / NoteBlock 音高一一对应。 [_][b]物理键盘映射[/b]（C 大调布局）：白键 [code]A S D F G H J K L ; '[/code]，黑键 [code]W E T Y U O P[/code]；[b]1[/b] / [b]2[/b] / [b]3[/b] 固定映射 A0 / A#0 / B0，便于试音与录制。 [_][b]八度移调[/b]：[code][−][/code] / [code][+][/code] 按钮，或 [b]0[/b] 键一键回到 C4。 [_][b]三级发声路径[/b]，依次择优： [list=1] [_][code]PianoAPI[/code]（[code]sqlmc.api.PianoAPI[/code]） [_]PianoLib 88 音缓存（[code]pianolib:key_0[/code] … [code]key_87[/code]） [_][code]NOTE_BLOCK_HARP[/code] 变调兜底 [/list] 因此主菜单与世界内均可发声。 [_][b]MIDI 录制[/b]：内置 [code]MidiRecorder[/code]，支持延音踏板（CC64）、混响（CC91 / CC93）、ADSR 包络与按音区分段的释放时间；录音自动保存至 [code]recordings/[/code] 目录。 [/list]

[h2]▶️ 钢琴界面 MIDI 回放 [color=green][新增][/color][/h2]

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

[list] [_][code]● REC[/code] 位于 [code]x=10[/code] — 开始 / 停止 MIDI 录制 [_][b][code]▶ PLAY[/code][/b] 位于 [code]x=74[/code] — 播放 / 停止当前 [code].mid[/code] [*][b][code]♪ 文件名.mid[/code][/b] 位于 [code]x=138[/code] — 切换到下一首 [code].mid[/code] [/list]

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

[h2]✏️ 游戏内 NBS 编辑器 [color=green][新增][/color][/h2]

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

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

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

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

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

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

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

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

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

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

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

[h2]🛡️ 防反作弊[/h2] 增强了原版 Disc Jockey 的防反作弊处理。

[h1]📜 指令大全[/h1]

[spoiler=基础播放控制] [list] [_][code]/discjockey[/code] — 打开 Disc Jockey GUI [_][code]/discjockey play <曲目>[/code] — 播放指定曲目 [_][code]/discjockey pause[/code] — 暂停播放 [_][code]/discjockey stop[/code] — 停止播放 [_][code]/discjockey resume[/code] — 恢复播放 [_][code]/discjockey now[/code] — 查看当前正在播放的曲目 [_][code]/discjockey info[/code] — 查看当前曲目信息与播放速度 [_][code]/discjockey progress[/code] — 查看播放进度 [/list] [/spoiler]

[spoiler=播放模式] [list] [_][code]/discjockey loop yes|no[/code] — 开启 / 关闭单曲循环 [_][code]/discjockey shuffle[/code] — 切换随机播放模式 [_][code]/discjockey autoplay[/code] — 开启 / 关闭自动连播 [_][code]/discjockey random[/code] — 随机播放 GUI 列表中的一首曲目 [/list] [/spoiler]

[spoiler=预览系统] [list] [_][code]/discjockey preview <曲目>[/code] — 预览指定曲目或查看预览状态 [_][b]M[/b] — 预览静音 / 取消静音 [*][b]P[/b] — 开启 / 关闭预览循环 [/list] 按键绑定可在「控制」设置中修改。 [/spoiler]

[spoiler=速度与移调] [list] [_][code]/discjockey speed <数值>[/code] — 调整播放速度 [_][code]/discjockey transpose[/code] — 对当前曲目进行移调 [/list] [/spoiler]

[spoiler=NBS 修复]

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

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

[spoiler=乐器管理] [list] [_][code]/discjockey instrument <名称>[/code] — 统计周围指定乐器的音符盒数量 [_][code]/discjockey remapInstruments map <源> <目标>[/code] — 建立音色映射 [_][code]/discjockey remapInstruments unmap <源> <目标>[/code] — 移除指定映射 [_][code]/discjockey remapInstruments show[/code] — 查看当前映射状态 [*][code]/discjockey remapInstruments clear[/code] — 清空所有音色映射 [/list] [/spoiler]

[spoiler=实用工具] [list] [_][code]/discjockey reload[/code] — 重新加载所有曲目（含热重载监听） [_][code]/discjockey spectrum[/code] — 开启 / 关闭 GUI 内频谱显示 [_][code]/discjockey sleep <秒数>[/code] — 定时停止播放 / 取消定时 [_][code]/discjockey update[/code] — 游戏内检查更新 [*][code]/discjockey help[/code] — 查看帮助信息 [/list] [/spoiler]

[h1]🖥️ 界面速查[/h1]

[h3]Disc Jockey 主界面[/h3] [list] [_][code]✏ 编辑[/code] — [b]左上角[/b] — 为选中曲目打开 NBS 编辑器 [_][code]⚙[/code] — 左下角 — 打开配置界面 [_][code]🎹 🎶→[/code] — 底部栏 — 打开钢琴界面 [_]搜索框 — 顶部 — 过滤曲目 [*]右键曲目 — 列表 — 查看曲目详情 [/list]

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

[h3]NBS 编辑器[/h3] 详见上方 [b]游戏内 NBS 编辑器[/b] 一节。

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

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

[hr]

[center]© Disc Jockey Plus — 基于原版 [i]Disc Jockey[/i] 的非官方分支[/center]

---

📑 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.4. 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.20.1	✅
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-beta	✅

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.

---

New Features

🎶 Custom In Game Sounds

• You Can Use Game Sounds In The Note Block Editor Screen,And Save it.
• Previewer Now Can Preview The Custom Sounds.
• You Can Use The Button "Tone" or "音色" to toggle it.

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.4。在原版基础上追加了 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 变调发声。

---

新功能

🎶 自定义游戏音效

• 你可以在音符方块编辑器界面使用游戏内音效并保存它。
• 预览器现在可以预览自定义音效。
• 你可以使用“Tone”或“音色”按钮使用自定义音色。

核心功能

🎹 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。

---