docs: 完善 README(架构说明、MIDI 格式要点、快捷键、自检)
This commit is contained in:
@@ -1,3 +1,242 @@
|
|||||||
# midi-player
|
# 🎹 MIDI Player —— 纯浏览器 MIDI 播放器
|
||||||
|
|
||||||
🎹 纯浏览器 MIDI 播放器:自研 SMF 解析器 + Web Audio 合成器,零依赖
|
一个**零依赖**的网页版 MIDI 播放器:从二进制文件解析,到发声合成,再到钢琴卷帘可视化,
|
||||||
|
全部由自己实现,只用浏览器原生的 `DataView` 和 `Web Audio API`。
|
||||||
|
|
||||||
|
打开 `index.html` 就能用——不需要安装、不需要构建、不需要联网(内置示例曲目是运行时生成的)。
|
||||||
|
|
||||||
|
```
|
||||||
|
midi-player/
|
||||||
|
├── index.html 播放器主界面
|
||||||
|
├── css/style.css 深色主题样式
|
||||||
|
├── js/
|
||||||
|
│ ├── midi-parser.js ★ 标准 MIDI 文件(SMF)解析器
|
||||||
|
│ ├── synth.js ★ Web Audio 复音合成器 + 鼓机 + 混响
|
||||||
|
│ ├── player.js ★ 预读窗口调度器(走带控制)
|
||||||
|
│ ├── visualizer.js ★ 钢琴卷帘 + 电平表
|
||||||
|
│ ├── demo.js 内置示例曲目(运行时生成 SMF 字节流)
|
||||||
|
│ └── app.js 界面逻辑
|
||||||
|
└── test/parser-test.html 解析器自检页面(12 组断言)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
**方式一:直接打开**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <this-repo>
|
||||||
|
cd midi-player
|
||||||
|
# 用任意静态服务器打开(推荐,避免个别浏览器对 file:// 的限制)
|
||||||
|
python3 -m http.server 8080
|
||||||
|
# 浏览器访问 http://localhost:8080
|
||||||
|
```
|
||||||
|
|
||||||
|
**方式二:先听为快**
|
||||||
|
|
||||||
|
打开页面后点击右上角 **「载入示例」**。示例曲目是《欢乐颂》主题的 8 小节编曲,
|
||||||
|
包含旋律、和弦、贝斯、鼓组四条轨道,并在第 5 小节做了变速——用来验证 tempo map 是否正确。
|
||||||
|
|
||||||
|
**方式三:放自己的曲子**
|
||||||
|
|
||||||
|
把任意 `.mid` / `.midi` 文件拖到页面任意位置即可。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 功能特性
|
||||||
|
|
||||||
|
| 分类 | 能力 |
|
||||||
|
| --- | --- |
|
||||||
|
| 解析 | `MThd` / `MTrk` 块结构、VLQ 变长数量、运行状态(running status)、SMPTE 时间码、SysEx 跳过 |
|
||||||
|
| 事件 | Note On/Off、Program Change、Control Change、Pitch Bend、全部元事件与文本事件 |
|
||||||
|
| 时间 | 完整 **Tempo Map**:支持任意多次变速,把 tick 时间轴分段线性换算成秒 |
|
||||||
|
| 播放 | 播放 / 暂停 / 停止 / 拖动跳转 / 0.25×–2× 变速 / 总音量 |
|
||||||
|
| 轨道 | 每轨独立静音(M)与独奏(S) |
|
||||||
|
| 合成 | 16 个 GM 乐器族的差异化音色、通道 9 打击乐鼓机、生成式卷积混响、复音数上限与偷声 |
|
||||||
|
| 控制器 | CC7 通道音量、CC10 声像、CC11 表情、CC120/123 全部音符关闭 |
|
||||||
|
| 可视化 | 钢琴卷帘(自动适配音域、力度映射透明度、按轨道配色、实时高亮)、输出电平表 |
|
||||||
|
| 交互 | 拖拽载入、快捷键、曲目信息面板、轨道列表 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 工作原理
|
||||||
|
|
||||||
|
整条链路是 **解析 → 换算 → 调度 → 发声 → 可视化** 五层,层与层之间只通过纯数据对象通信。
|
||||||
|
|
||||||
|
```
|
||||||
|
.mid 文件
|
||||||
|
│ ArrayBuffer
|
||||||
|
▼
|
||||||
|
┌──────────────┐ 把二进制还原成"事件流",并把 tick 时间轴
|
||||||
|
│ midi-parser │ 按 Tempo Map 换算成「秒」
|
||||||
|
└──────────────┘
|
||||||
|
│ Song { notes[], controllers[], tempos[], duration }
|
||||||
|
▼
|
||||||
|
┌──────────────┐ 把音符拆成 on/off 事件,按时间排序;
|
||||||
|
│ player │ 每 25ms 唤醒一次,安排未来 200ms 内的所有事件
|
||||||
|
└──────────────┘
|
||||||
|
│ synth.noteOn(channel, midi, velocity, when, program)
|
||||||
|
▼
|
||||||
|
┌──────────────┐ 在 AudioContext 的精确时钟上创建振荡器与包络
|
||||||
|
│ synth │ Web Audio 采样级精度,不受 JS 定时器抖动影响
|
||||||
|
└──────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌──────────────┐ 每帧读取播放位置,把音符画成向左滚动的方块
|
||||||
|
│ visualizer │
|
||||||
|
└──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1. 解析层:读懂 SMF 格式
|
||||||
|
|
||||||
|
标准 MIDI 文件是一棵"块(chunk)树":
|
||||||
|
|
||||||
|
```
|
||||||
|
MThd ── 头块:格式(0/1/2)、轨道数、时间分辨率 division
|
||||||
|
MTrk ── 轨道块 × N
|
||||||
|
MTrk
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
每个轨道块内部是一串 **「delta-time + 事件」**:
|
||||||
|
|
||||||
|
| 字段 | 说明 |
|
||||||
|
| --- | --- |
|
||||||
|
| delta-time | 与上一个事件的**相对** tick 差,用 **VLQ** 变长数量编码(每字节 7 位有效位) |
|
||||||
|
| 事件 | 通道事件(`0x8n`~`0xEn`)、元事件(`0xFF`)、SysEx(`0xF0`/`0xF7`) |
|
||||||
|
|
||||||
|
两个容易被忽略但必须处理的细节:
|
||||||
|
|
||||||
|
- **运行状态**:连续的同类型通道事件会省略状态字节,解析器必须"记住"上一个状态字节,
|
||||||
|
并且不能把数据字节误判成状态字节。`midi-parser.js` 用一个 `running` 变量解决。
|
||||||
|
- **note-on 力度为 0** 等价于 note-off(很多音序器用它来压缩文件体积)。
|
||||||
|
|
||||||
|
解析器最终输出的 `Song` 对象长这样:
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
format: 1, ticksPerBeat: 480, duration: 19.27,
|
||||||
|
notes: [{ midi: 64, name: 'E4', velocity: 104, start: 0.0, duration: 0.479,
|
||||||
|
channel: 0, program: 0, track: 1, startTick: 0, endTick: 460 }, ...],
|
||||||
|
controllers: [...], tempos: [{ tick, time, usPerQuarter, bpm }], ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
音符是**配对**出来的:解析时维护一张 `通道 × 音高` 的活动表,遇到 note-off 时反查并计算时长。
|
||||||
|
轨道结束仍未收到 note-off 的音符,用轨道末尾时间收尾,避免"卡死的音"。
|
||||||
|
|
||||||
|
### 2. 时间换算:tick → 秒
|
||||||
|
|
||||||
|
MIDI 里的时间单位是 **tick**,而 tick 的真实时长取决于当前速度。做法是先把所有 tempo 事件
|
||||||
|
(`0xFF 0x51`,单位是"微秒/四分音符")收集起来排序,构建一张**分段线性映射表**:
|
||||||
|
|
||||||
|
```
|
||||||
|
tick 0 ──────────────── tick 7680 ────────── tick 15360 ──────►
|
||||||
|
500000 µs/♩ 454545 µs/♩ 500000 µs/♩
|
||||||
|
(120 BPM) (≈132 BPM) (120 BPM)
|
||||||
|
秒 0 ──────────────── 8.00s ────────────── 15.27s ─────────►
|
||||||
|
```
|
||||||
|
|
||||||
|
换算时对这张表二分查找,落在哪一段就按那一段的斜率线性插值:
|
||||||
|
|
||||||
|
```js
|
||||||
|
time = seg.time + (tick - seg.tick) * (seg.usPerQuarter / 1e6 / ticksPerBeat)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 调度层:预读窗口(look-ahead scheduler)
|
||||||
|
|
||||||
|
这是 Web 音频播放最关键的工程技巧。
|
||||||
|
|
||||||
|
`setInterval` 的抖动动辄几毫秒到几十毫秒,**绝不能**用它来直接触发声音。正确做法是把
|
||||||
|
"决定何时发声"和"实际发声"解耦:
|
||||||
|
|
||||||
|
```js
|
||||||
|
setInterval(tick, 25); // 每 25ms 唤醒,主线程卡顿无所谓
|
||||||
|
// tick() 里:把未来 200ms 内会发生的所有事件
|
||||||
|
// 用 AudioContext 时间戳提前安排好
|
||||||
|
voice.start(ctx.currentTime + 0.137); // 采样级精度
|
||||||
|
```
|
||||||
|
|
||||||
|
因为提前量(200ms)远大于定时器抖动,即使主线程偶尔卡顿 100ms,声音也不会走音。
|
||||||
|
代价是"播放位置"必须同时维护两套时间轴:`baseSongTime`(歌曲时间)与 `startedAt`(音频时钟时间),
|
||||||
|
任何一次暂停 / 跳转 / 变速都要重新对齐,并掐掉残留音(`synth.panic()`)。
|
||||||
|
|
||||||
|
### 4. 合成层:Web Audio 音频图
|
||||||
|
|
||||||
|
```
|
||||||
|
┌── StereoPanner ──┐
|
||||||
|
Oscillator ──┐ │ │
|
||||||
|
Oscillator ──┼─► 低通滤波 ──► ADSR 包络 ──► 通道音量 ──────────────────► 主增益
|
||||||
|
Oscillator ──┘ │ │
|
||||||
|
└── 混响发送 ──► Convolver ──► 湿声 ──┘
|
||||||
|
│
|
||||||
|
Compressor ──► Analyser ──► 扬声器
|
||||||
|
```
|
||||||
|
|
||||||
|
- **音色**:按 GM 音色族(`program / 8`)分 16 组,每组用振荡器组合、ADSR、滤波截止
|
||||||
|
三组参数描述。比如钢琴是 `triangle + sine` 加快速衰减;弦乐是两个失谐 7 音分的锯齿波加长起音。
|
||||||
|
- **鼓组**:通道 9 走另一套逻辑。底鼓是频率从 165Hz 指数下滑到 45Hz 的正弦;军鼓是带通噪声
|
||||||
|
加一个 190Hz 的鼓皮基音;踩镲/吊镲是不同截止频率的高通噪声。
|
||||||
|
- **混响**:没有外部音频资源,所以运行时生成一段指数衰减的噪声当作**脉冲响应**,喂给
|
||||||
|
`ConvolverNode`。
|
||||||
|
- **偷声**:同时发声数超过上限时,掐掉最早的一个未释放音,防止复音数爆炸导致的爆音与卡顿。
|
||||||
|
- **包络释放**用 `cancelAndHoldAtTime`(不支持时降级为"读取当前值 + 重新排程"),
|
||||||
|
保证在包络中途收到 note-off 也不会出现跳变爆音。
|
||||||
|
|
||||||
|
### 5. 可视化层
|
||||||
|
|
||||||
|
每帧(`requestAnimationFrame`)读取 `player.position`,把音符矩形画在
|
||||||
|
`x = 播放头X + (音符时间 - 当前时间) × 每秒像素` 的位置,就得到了向左滚动的钢琴卷帘。
|
||||||
|
纵向自动适配曲目实际音域,左侧画出钢琴键盘,正在发声的音高实时高亮。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 快捷键
|
||||||
|
|
||||||
|
| 按键 | 动作 |
|
||||||
|
| --- | --- |
|
||||||
|
| `空格` | 播放 / 暂停 |
|
||||||
|
| `←` `→` | 后退 / 前进 5 秒 |
|
||||||
|
| `↑` `↓` | 音量增减 |
|
||||||
|
| `Home` | 停止并回到开头 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 解析器自检
|
||||||
|
|
||||||
|
打开 `test/parser-test.html`,页面会跑 12 组交叉验证:
|
||||||
|
|
||||||
|
- 手工拼出的**最小 format 0 文件**(字段、音符配对、tick→秒)
|
||||||
|
- 手工拼出的**变速文件**(验证 tempo map 的分段换算)
|
||||||
|
- 手工拼出的**运行状态文件**(验证省略状态字节与"力度 0 = note-off")
|
||||||
|
- **内置示例曲目**(5 轨结构、175 个音符的逐轨统计、通道 9 归属、音色跟随 program change)
|
||||||
|
|
||||||
|
页面底部还有一个探针:选任意 `.mid` 文件,会打印出完整的解析摘要,方便排查兼容性问题。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 兼容性与限制
|
||||||
|
|
||||||
|
- 需要支持 `Web Audio API` 的现代浏览器(Chrome / Edge / Firefox / Safari 14+)。
|
||||||
|
**首次播放必须由用户手势触发**(浏览器自动播放策略),点一下 ▶ 即可。
|
||||||
|
- SMPTE 时间码(`division` 高位为 1)可以解析并正确换算时间,但时间刻度显示会退化为秒。
|
||||||
|
- format 2(多首独立曲目)会按 format 1 的方式合并播放。
|
||||||
|
- 未实现:RPN/NRPN(弯音轮灵敏度)、Sustain Pedal(CC64)已解析但未作用于合成器、
|
||||||
|
Lyrics/Karaoke 文本同步显示。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 开发路线图
|
||||||
|
|
||||||
|
- [ ] 采样器模式:用真实音源采样替换纯合成音色
|
||||||
|
- [ ] 支持 MIDI 输入设备(Web MIDI API),把本播放器当合成器弹
|
||||||
|
- [ ] 导出:把当前曲目渲染成 WAV(`OfflineAudioContext`)
|
||||||
|
- [ ] 轨道级音量推子与声像旋钮
|
||||||
|
- [ ] 卷帘上叠加节拍/小节网格(利用已有的 tempo map)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 许可
|
||||||
|
|
||||||
|
MIT
|
||||||
|
|||||||
Reference in New Issue
Block a user