10 KiB
🎹 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 组断言)
快速开始
方式一:直接打开
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 对象长这样:
{
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 ─────────►
换算时对这张表二分查找,落在哪一段就按那一段的斜率线性插值:
time = seg.time + (tick - seg.tick) * (seg.usPerQuarter / 1e6 / ticksPerBeat)
3. 调度层:预读窗口(look-ahead scheduler)
这是 Web 音频播放最关键的工程技巧。
setInterval 的抖动动辄几毫秒到几十毫秒,绝不能用它来直接触发声音。正确做法是把
"决定何时发声"和"实际发声"解耦:
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