Disc Jockey Plus

---

📑 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.

---

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 变调发声。

---

核心功能

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

---