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]