feat: 新增自研 SMF(MIDI) 解析器,支持 tempo map 与音符配对

This commit is contained in:
2026-09-24 03:37:48 +00:00
parent 163b8f89bf
commit 98b2423717
+372
View File
@@ -0,0 +1,372 @@
/*
* midi-parser.js —— 纯 JavaScript 的 Standard MIDI File (SMF) 解析器
* ------------------------------------------------------------------
* 零依赖,浏览器 / Node.js 双端可用。
*
* 负责把 .mid 二进制文件还原成"可播放的音乐数据":
* - 块结构解析(MThd / MTrk)
* - 变长数量(VLQ)解码
* - 运行状态(running status)还原
* - 通道事件 / 系统独占事件 / 元事件
* - 速度映射表(Tempo Map):把"tick 时间轴"换算成"秒时间轴"
* - 音符配对:note-on / note-off 合成带时长的音符对象
*
* 对外接口:
* MidiParser.parse(arrayBuffer) -> Song
* MidiParser.noteName(midiNumber) -> "C4"
*/
(function (root, factory) {
if (typeof module === 'object' && module.exports) module.exports = factory();
else root.MidiParser = factory();
})(typeof self !== 'undefined' ? self : this, function () {
'use strict';
var NOTE_NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
var DEFAULT_TEMPO = 500000; // 微秒 / 四分音符 == 120 BPM
/* ------------------------------------------------------------------ */
/* 工具函数 */
/* ------------------------------------------------------------------ */
function noteName(midi) {
var i = ((midi % 12) + 12) % 12;
return NOTE_NAMES[i] + (Math.floor(midi / 12) - 1);
}
function readString(bytes, offset, len) {
var s = '';
for (var i = 0; i < len; i++) s += String.fromCharCode(bytes[offset + i]);
return s;
}
function decodeText(bytes) {
if (typeof TextDecoder !== 'undefined') {
try { return new TextDecoder('utf-8').decode(bytes); } catch (e) { /* 退化处理 */ }
}
var s = '';
for (var i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
return s;
}
/* 变长数量解码:每字节 7 位有效位,最高位表示"还有后续字节" */
function readVlq(view, offset) {
var value = 0, byte, guard = 0;
do {
byte = view.getUint8(offset++);
value = value * 128 + (byte & 0x7f);
guard++;
} while ((byte & 0x80) && guard < 5);
return { value: value, next: offset };
}
/* ------------------------------------------------------------------ */
/* 单个 MTrk 块的解析 */
/* ------------------------------------------------------------------ */
function parseTrack(view, start, end, index) {
var events = [];
var p = start;
var tick = 0; // 累计的绝对 tick
var running = 0; // 运行状态(上一个通道状态字节)
var name = '';
while (p < end) {
// 1) 读取 delta time
var d = readVlq(view, p);
tick += d.value;
p = d.next;
if (p >= end) break;
// 2) 读取状态字节(可能省略,沿用运行状态)
var status = view.getUint8(p);
if (status & 0x80) { p++; running = status; }
else { status = running; }
if (!status) break; // 数据异常,安全退出
if (status === 0xff) {
/* ---- 元事件 ---- */
var metaType = view.getUint8(p++);
var ml = readVlq(view, p); p = ml.next;
var mdata = new Uint8Array(view.buffer, view.byteOffset + p, ml.value);
p += ml.value;
var me = { tick: tick, type: 'meta', metaType: metaType, data: mdata, track: index };
if (metaType === 0x51 && ml.value >= 3) {
me.tempo = (mdata[0] << 16) | (mdata[1] << 8) | mdata[2];
} else if (metaType >= 0x01 && metaType <= 0x09) {
me.text = decodeText(mdata);
if (metaType === 0x03 || metaType === 0x04) name = me.text;
}
events.push(me);
} else if (status === 0xf0 || status === 0xf7) {
/* ---- 系统独占事件:读取后跳过 ---- */
var sl = readVlq(view, p); p = sl.next;
events.push({
tick: tick, type: 'sysex', track: index,
data: new Uint8Array(view.buffer, view.byteOffset + p, sl.value)
});
p += sl.value;
} else if (status >= 0x80 && status <= 0xef) {
/* ---- 通道事件 ---- */
var type = status & 0xf0;
var channel = status & 0x0f;
var d1 = view.getUint8(p++);
var d2 = 0;
if (type !== 0xc0 && type !== 0xd0) d2 = view.getUint8(p++);
events.push({
tick: tick, type: type, channel: channel,
data1: d1, data2: d2, track: index
});
} else {
break; // 无法识别的状态字节,终止本轨解析
}
}
return { index: index, name: name, events: events, endTick: tick };
}
/* ------------------------------------------------------------------ */
/* 主解析流程 */
/* ------------------------------------------------------------------ */
function parse(arrayBuffer) {
if (!arrayBuffer || typeof arrayBuffer.byteLength !== 'number') {
throw new Error('需要传入 ArrayBuffer');
}
if (arrayBuffer.byteLength < 14) throw new Error('文件过短,不是合法的 MIDI 文件');
var view = new DataView(arrayBuffer);
var bytes = new Uint8Array(arrayBuffer);
if (readString(bytes, 0, 4) !== 'MThd') {
throw new Error('缺少 MThd 头块,不是标准 MIDI 文件');
}
var headerLen = view.getUint32(4);
var format = view.getUint16(8);
var declaredTracks = view.getUint16(10);
var division = view.getUint16(12);
/* --- 时间分辨率 --- */
var ticksPerBeat = 480;
var smpte = null;
if (division & 0x8000) {
// SMPTE 时间码:高字节为负的帧率,低字节为每帧 tick 数
var fps = 256 - ((division >> 8) & 0xff);
smpte = { fps: fps, ticksPerFrame: division & 0xff };
} else {
ticksPerBeat = division || 480;
}
/* --- 遍历所有 MTrk 块 --- */
var p = 8 + headerLen;
var tracks = [];
var ti = 0;
while (p + 8 <= arrayBuffer.byteLength) {
var id = readString(bytes, p, 4);
var len = view.getUint32(p + 4);
p += 8;
if (id === 'MTrk') {
var end = Math.min(p + len, arrayBuffer.byteLength);
tracks.push(parseTrack(view, p, end, ti++));
}
p += len;
}
if (!tracks.length) throw new Error('没有找到任何 MTrk 轨道');
/* ---------------- 构建 Tempo Map ---------------- */
var rawTempos = [{ tick: 0, usPerQuarter: DEFAULT_TEMPO }];
tracks.forEach(function (t) {
t.events.forEach(function (e) {
if (e.type === 'meta' && e.metaType === 0x51 && e.tempo) {
rawTempos.push({ tick: e.tick, usPerQuarter: e.tempo });
}
});
});
rawTempos.sort(function (a, b) { return a.tick - b.tick; });
var segments = []; // { tick, time, usPerQuarter }
var curTick = 0, curTime = 0, curUs = DEFAULT_TEMPO;
segments.push({ tick: 0, time: 0, usPerQuarter: curUs });
for (var i = 0; i < rawTempos.length; i++) {
var tm = rawTempos[i];
if (tm.tick <= curTick) {
// 同一 tick 上重复出现,后者覆盖前者
segments[segments.length - 1].usPerQuarter = tm.usPerQuarter;
curUs = tm.usPerQuarter;
continue;
}
curTime += (tm.tick - curTick) * (curUs / 1e6 / ticksPerBeat);
curTick = tm.tick;
curUs = tm.usPerQuarter;
segments.push({ tick: curTick, time: curTime, usPerQuarter: curUs });
}
/* tick -> 秒 的换算(分段线性,二分查找) */
function tickToTime(tick) {
if (smpte) return tick / (smpte.fps * smpte.ticksPerFrame);
var lo = 0, hi = segments.length - 1, idx = 0;
while (lo <= hi) {
var mid = (lo + hi) >> 1;
if (segments[mid].tick <= tick) { idx = mid; lo = mid + 1; }
else hi = mid - 1;
}
var s = segments[idx];
return s.time + (tick - s.tick) * (s.usPerQuarter / 1e6 / ticksPerBeat);
}
/* ---------------- 事件 -> 音符 ---------------- */
var notes = [];
var controllers = [];
var pitchBends = [];
var markers = [];
var totalTicks = 0;
tracks.forEach(function (track, tIdx) {
var active = {}; // "ch*128+key" -> 未闭合的音符
var programs = {}; // channel -> 当前 GM 音色号
var count = 0;
function closeNote(n, endTick) {
if (endTick < n.startTick) endTick = n.startTick;
var start = tickToTime(n.startTick);
var stop = tickToTime(endTick);
notes.push({
midi: n.midi,
name: noteName(n.midi),
velocity: n.velocity,
channel: n.channel,
program: n.program,
track: tIdx,
startTick: n.startTick,
endTick: endTick,
start: start,
duration: Math.max(stop - start, 0.02)
});
count++;
}
track.events.forEach(function (e) {
if (e.type === 0x90 && e.data2 > 0) {
var k = e.channel * 128 + e.data1;
if (active[k]) closeNote(active[k], e.tick); // 同音重叠,先收尾前一个
active[k] = {
midi: e.data1, velocity: e.data2, channel: e.channel,
startTick: e.tick, program: programs[e.channel] || 0
};
} else if (e.type === 0x80 || (e.type === 0x90 && e.data2 === 0)) {
var k2 = e.channel * 128 + e.data1;
if (active[k2]) { closeNote(active[k2], e.tick); delete active[k2]; }
} else if (e.type === 0xc0) {
programs[e.channel] = e.data1;
track.programs = programs;
} else if (e.type === 0xb0) {
controllers.push({
tick: e.tick, channel: e.channel, number: e.data1,
value: e.data2, track: tIdx, time: 0
});
} else if (e.type === 0xe0) {
pitchBends.push({
tick: e.tick, channel: e.channel,
value: ((e.data2 << 7) | e.data1) - 8192, track: tIdx, time: 0
});
} else if (e.type === 'meta' && e.text !== undefined) {
markers.push({
tick: e.tick, text: e.text, metaType: e.metaType, track: tIdx, time: 0
});
}
});
// 轨道结束时仍未收到 note-off 的音符,用轨道末尾时间收尾
Object.keys(active).forEach(function (k) {
closeNote(active[k], track.endTick);
delete active[k];
});
track.noteCount = count;
if (track.endTick > totalTicks) totalTicks = track.endTick;
});
// 补齐秒时间
controllers.forEach(function (c) { c.time = tickToTime(c.tick); });
pitchBends.forEach(function (b) { b.time = tickToTime(b.tick); });
markers.forEach(function (m) { m.time = tickToTime(m.tick); });
// 音符按起始时间排序(后续调度依赖有序性)
notes.sort(function (a, b) { return a.start - b.start; });
/* ---------------- 统计信息 ---------------- */
var duration = 0;
var minNote = 127, maxNote = 0;
var channelSet = {};
notes.forEach(function (n) {
var e = n.start + n.duration;
if (e > duration) duration = e;
if (n.midi < minNote) minNote = n.midi;
if (n.midi > maxNote) maxNote = n.midi;
channelSet[n.channel] = true;
});
var tempoList = segments.map(function (s) {
return {
tick: s.tick,
time: s.time,
usPerQuarter: s.usPerQuarter,
bpm: Math.round(60000000 / s.usPerQuarter * 100) / 100
};
});
return {
format: format,
declaredTracks: declaredTracks,
division: division,
ticksPerBeat: ticksPerBeat,
smpte: smpte,
duration: duration,
totalTicks: totalTicks,
notes: notes,
controllers: controllers,
pitchBends: pitchBends,
markers: markers,
tempos: tempoList,
bpm: tempoList.length ? tempoList[0].bpm : 120,
minNote: notes.length ? minNote : 60,
maxNote: notes.length ? maxNote : 72,
channels: Object.keys(channelSet).map(Number).sort(function (a, b) { return a - b; }),
tracks: tracks.map(function (t) {
return {
index: t.index,
name: t.name || '',
noteCount: t.noteCount || 0,
eventCount: t.events.length,
endTick: t.endTick,
programs: t.programs || {}
};
})
};
}
/* ---- 供外部使用:根据歌曲信息生成一个可读的标题 ---- */
function guessTitle(song) {
var m = (song.markers || []).filter(function (x) {
return x.metaType === 0x03 || x.metaType === 0x01;
});
if (m.length && m[0].text) return m[0].text;
for (var i = 0; i < song.tracks.length; i++) {
if (song.tracks[i].name) return song.tracks[i].name;
}
return '';
}
return {
parse: parse,
noteName: noteName,
guessTitle: guessTitle,
NOTE_NAMES: NOTE_NAMES
};
});