Files
midi-player/README.md
T

10 KiB
Raw Blame History

🎹 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