Описание
# 🎵 Disc Jockey Plus
**A professional note-block music mod for Minecraft Java 26.2 – 26.3**
*Unofficial fork of the original **Disc Jockey** — fully ported to 26.2 / 26.3*
`Built-in i18n` · `Real-time Spectrum` · `88-Key Piano` · `In-Game NBS Editor` · `MIDI ↔ NBS`
| Loader | Status | Requirement |
|:---|:---|:---|
| **Fabric** | ✅ Stable | Fabric Loader ≥ 0.19.5 |
| **NeoForge** | ✅ Stable | NeoForge ≥ 26.3.0.52-beta|
> ⚠️ **Do NOT use NeoForge 26.3.0.56-beta** — that build is broken and will crash.
> 💬 Want the latest updates? Search **SQL_Minecraft** on Bilibili and subscribe!
---
## 📑 Table of Contents
- [Overview](#overview)
- [Dependencies](#dependencies)
- [Core Features](#core-features)
- [88-Key Piano Keyboard](#-88-key-piano-keyboard)
- [Piano-Screen MIDI Playback](#-piano-screen-midi-playback-new)
- [In-Game NBS Editor](#-in-game-nbs-editor-new)
- [Real-Time Spectrum](#-real-time-spectrum)
- [NBS Playback & Repair](#-nbs-playback--repair)
- [MIDI Import & Export](#-midi-import--export)
- [Preview System](#-preview-system)
- [Lyrics Output](#-lyrics-output)
- [Instrument Management](#-instrument-management)
- [Speed & Transpose](#-speed--transpose)
- [Command Reference](#-command-reference)
- [GUI Cheat Sheet](#-gui-cheat-sheet)
- [Notes](#-notes)
- [Technical](#-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/.nbs` |
| `AS` | Save as `_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 💬 想要获取最新更新？在 B 站搜索 **SQL_Minecraft** 并关注我！
---
## 📑 目录
- [简介](#简介)
- [依赖项目](#依赖项目)
- [核心功能](#核心功能)
- [88 键钢琴键盘](#-88-键钢琴键盘)
- [钢琴界面 MIDI 回放](#-钢琴界面-midi-回放-new)
- [游戏内 NBS 编辑器](#-游戏内-nbs-编辑器-new)
- [实时频谱可视化](#-实时频谱可视化)
- [NBS 播放与修复](#-nbs-播放与修复)
- [MIDI 双向转换](#-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.52 | ✅ |
> 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