From cbd8dfa767bd48f081dfa2ed6e2c9a816c278b7e Mon Sep 17 00:00:00 2001 From: class04m02 Date: Thu, 24 Sep 2026 03:44:11 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20README=EF=BC=88?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E8=AF=B4=E6=98=8E=E3=80=81MIDI=20=E6=A0=BC?= =?UTF-8?q?=E5=BC=8F=E8=A6=81=E7=82=B9=E3=80=81=E5=BF=AB=E6=8D=B7=E9=94=AE?= =?UTF-8?q?=E3=80=81=E8=87=AA=E6=A3=80=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 243 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 241 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0e81202..811e766 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,242 @@ -# midi-player +# 🎹 MIDI Player —— 纯浏览器 MIDI 播放器 -🎹 纯浏览器 MIDI 播放器:自研 SMF 解析器 + Web Audio 合成器,零依赖 \ No newline at end of file +一个**零依赖**的网页版 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