Files
midi-player/README.md
T

243 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🎹 MIDI Player —— 纯浏览器 MIDI 播放器
一个**零依赖**的网页版 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