# 🎹 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 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