本文详解如何利用 tone.js 的 transport.schedule 实现 midi 播放时音符信息的毫秒级实时显示，替代不稳定的 settimeout，确保视觉反馈与音频事件严格对齐。
本文详解如何利用 tone.js 的 transport.schedule 实现 midi 播放时音符信息的毫秒级实时显示，替代不稳定的 settimeout，确保视觉反馈与音频事件严格对齐。
在使用 Tone.js 播放 MIDI 文件时，若希望在音符实际发声的同一时刻动态显示其名称、力度、时长等信息（例如高亮钢琴键、更新 UI 谱面或控制灯光），关键在于将视觉更新逻辑与音频调度引擎深度绑定，而非依赖 JavaScript 原生定时器。
你当前代码中使用 setTimeout(() => { console.log(...) }, noteTime * 1000) 存在根本性问题：noteTime 是 Tone.js 的音乐时间（单位为小节/四分音符），而 setTimeout 接收的是毫秒值，二者单位不匹配；更重要的是，setTimeout 不受 Tone.Transport 的 tempo、pause、timeScale 等状态影响，一旦 Transport 暂停或变速，视觉提示就会严重脱节。
✅ 正确做法是统一使用 Tone.js 的调度系统 —— Transport.schedule()：
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
async function initiateMidi() {
const midi = await Midi.fromUrl('src/static/saliha-ya-khdoud-ettefeh.mid');
const synth = new Tone.Synth().toDestination();
synths.push(synth);
// 启动 Transport（确保它已启动，否则 schedule 不生效）
if (!Tone.Transport.state === 'started') {
Tone.Transport.start();
}
const now = Tone.now() + 0.5;
midi.tracks.forEach((track) => {
track.notes.forEach((note) => {
const noteTime = note.time + now;
const noteDuration = note.duration;
// ✅ 使用 Transport.schedule：传入回调和音乐时间点
Tone.Transport.schedule((time) => {
// 此处 time 是精确的调度时间点（Tone 时间），与 audio 事件完全对齐
console.log(`Note: ${note.name}, Time: ${time.toFixed(3)}, Velocity: ${note.velocity}`);
// ? 这里可安全触发 UI 更新：更新 DOM、高亮 SVG 键盘、发送 WebSocket 事件等
updateNoteDisplay(note.name, note.velocity, noteDuration);
}, noteTime);
// 音频触发保持不变
synth.triggerAttackRelease(note.name, noteDuration, noteTime, note.velocity);
});
});
}
// 示例 UI 更新函数（可根据需要扩展）
function updateNoteDisplay(name, velocity, duration) {
const displayEl = document.getElementById('current-note');
displayEl.textContent = `${name} (vel: ${velocity})`;
displayEl.style.opacity = '1';
// 可选：短暂淡出效果
setTimeout(() => {
displayEl.style.opacity = '0.6';
}, duration * 1000 * 0.8);
}⚠️ 重要注意事项：
- 必须显式调用
Tone.Transport.start()（或确保 Transport 已处于started状态），否则schedule()不会触发； - 所有
schedule()回调均在 Tone 的主音频线程上下文中执行，时间精度达亚毫秒级，远超setTimeout； - 若需响应 Transport 暂停/恢复，可监听事件：
Tone.Transport.on('pause', () => {...})； - 对于多轨 MIDI，建议为每条轨道单独处理，并注意
note.time是相对于该轨道起始的时间偏移，已适配标准 MIDI 时间线。
? 进阶提示：
如需更精细控制（如显示音符持续期间的“激活态”），可结合 Transport.scheduleRepeat() 或使用 Tone.Part 封装音符序列，实现 attack/release 的双事件调度。
通过 Transport.schedule，你获得的不仅是一次性的时间对齐，更是整个音乐时间轴的可预测性与可控制性 —— 这正是构建专业级交互式音乐应用的基石。
