如何用jQuery封装Web MIDI API打造可实时交互的网页音乐合成器？

Web MIDI API 在主流浏览器中的支持度逐渐成熟，它允许网页直接与 MIDI 兼容设备通信，无论是专业的电子琴、打击垫还是旋钮控制器。然而原生 API 仅提供基础的 Promise 和事件接口，想要在复杂应用里管理多个设备和消息流，代码很容易陷入回调地狱。jQuery 的 $.Deferred 可以很好地组织异步初始化流程，而 $.Callbacks 则能替代原生事件监听，实现更灵活的消息分发。通过封装，我们可以将 MIDI 输入输出抽象成一个 MidiManager 对象，开发者只需关注业务层面的音符事件，无需重复编写设备检测和端口选择代码。

Web MIDI API 基础与 jQuery 封装设计

请求 MIDI 访问的入口是 navigator.requestMIDIAccess()，它返回一个 Promise，成功时会获得 MIDIAccess 对象，其中包含输入和输出端口的 Map 集合。每个端口通过 onmidimessage 事件传递原始 MIDI 消息，消息的 data 属性是一个 Uint8Array，需要自行解析状态字节和数据字节。为了让这一过程更符合 jQuery 的编程习惯，我们可以创建一个 MidiManager 构造函数，内部使用 $.Deferred 处理初始化流程。

function MidiManager() {
  this.inputs = [];         // 存储已连接的输入设备
  this.outputs = [];        // 存储输出设备
  this.onMessage = $.Callbacks();
  this.onReady = $.Deferred();
  this.init();
}

MidiManager.prototype.init = function() {
  var self = this;
  if (!navigator.requestMIDIAccess) {
    self.onReady.reject('Web MIDI API 不受支持');
    return;
  }
  navigator.requestMIDIAccess().then(function(midiAccess) {
    var inputIterator = midiAccess.inputs.values();
    for (var input = inputIterator.next(); !input.done; input = inputIterator.next()) {
      self.inputs.push(input.value);
      input.value.onmidimessage = function(event) {
        self.onMessage.fire(event.data);
      };
    }
    var outputIterator = midiAccess.outputs.values();
    for (var output = outputIterator.next(); !output.done; output = outputIterator.next()) {
      self.outputs.push(output.value);
    }
    self.onReady.resolve();
  }, function(err) {
    self.onReady.reject(err);
  });
};

上面的代码利用 $.Deferred 封装了异步获取过程，外部通过 manager.onReady.done(callback) 即可在设备就绪后执行操作，而 onMessage 回调列表则允许同时绑定多个消息处理函数，解耦了后续的合成器和控制器逻辑。这种设计比直接使用原生 Promise.then 和 addEventListener 更具可维护性，因为 $.Callbacks 支持动态添加、移除和一次性调用，非常适合处理多变的 MIDI 数据流。

解析 MIDI 消息与 Web Audio 合成器引擎

标准的 MIDI 消息通常由三个字节组成：状态字节告诉我们是音符开（0x90）、音符关（0x80）还是控制变化（0xB0），其后跟随音符编号和力度值。解析时需要根据状态字节的高四位判断消息类型，并且注意 MIDI 有一种运行状态优化，即同一状态下后续消息可以省略状态字节，但在浏览器端接收的每条消息都会补齐三个字节，所以可以放心处理。为了降低耦合，我们创建一个 SynthEngine 对象，负责将解析好的音符事件转换为实际的音频输出。

function SynthEngine() {
  this.audioCtx = new (window.AudioContext || window.webkitAudioContext)();
  this.activeNotes = {};   // 当前按下的音符及其振荡器节点
}

SynthEngine.prototype.noteOn = function(note, velocity) {
  if (this.activeNotes[note]) return; // 防止连击产生多层振荡器
  var ctx = this.audioCtx;
  var oscillator = ctx.createOscillator();
  var gainNode = ctx.createGain();
  oscillator.type = 'sawtooth';
  oscillator.frequency.value = 440 * Math.pow(2, (note - 69) / 12);
  var vol = velocity / 127;
  gainNode.gain.value = vol * 0.3; // 主音量衰减
  oscillator.connect(gainNode);
  gainNode.connect(ctx.destination);
  oscillator.start();
  this.activeNotes[note] = { osc: oscillator, gain: gainNode };
};

力度值通常会映射到音量或滤波器的截止频率，这里简单地线性映射到增益。为了让合成器支持多复音，我们用 activeNotes 对象管理正在发音的音符，当收到 noteOff 事件时，可以优雅地释放音频资源并执行简单的淡出处理，避免产生爆音。借助 Web Audio API 的 AudioContext.currentTime 进行精确调度，可以实现低延迟响应，这一点对实时演奏至关重要。

jQuery 的 $.Callbacks 在消息分发环节再次发挥优势。MIDI 管理器接收原始数据后，解析出命令类型和参数，然后触发不同的自定义事件，例如 noteOn(note, velocity)、noteOff(note) 等。合成器引擎只需订阅这些事件即可，无需关心底层数据格式。这种事件总线模式使得后续添加可视化反馈、录制功能或 MIDI 输出都变得简单直接。

打造交互式打击垫界面与视觉反馈

仅仅用硬件键盘演奏不够直观，一个自带视觉反馈的网页打击垫能大大提升体验。我们可以用 jQuery 快速生成一组 4x4 的格子，每个格子绑定鼠标或触摸事件，点击时调用合成器的 noteOn，松开时调用 noteOff。同时格子背景色会根据力度变化，产生压感效果。

var padRow = 4, padCol = 4;
var padNotes = [60, 62, 64, 65, 67, 69, 71, 72, 60, 62, 64, 65, 67, 69, 71, 72];
var $padContainer = $('#pad-grid');
for (var i = 0; i < padRow * padCol; i++) {
  var $cell = $('<div class="pad-cell"></div>');
  $cell.data('note', padNotes[i]);
  $padContainer.append($cell);
}
$('.pad-cell').on('mousedown touchstart', function(e) {
  e.preventDefault();
  var note = $(this).data('note');
  var velocity = 100; // 点击固定力度，或根据位置计算
  synth.noteOn(note, velocity);
  $(this).css('background-color', 'rgba(255, 200, 0, 0.8)');
}).on('mouseup mouseleave touchend', function() {
  var note = $(this).data('note');
  synth.noteOff(note);
  $(this).css('background-color', '#444');
});

对于连接了 MIDI 设备的用户，打击垫还需要能同步显示外部的音符触发。我们在 MIDI 消息回调中加入视觉更新逻辑：遍历所有格子，如果其绑定的音符处于活跃状态，则高亮对应格子，否则恢复默认样式。同时可以使用 jQuery 的 .animate() 或 CSS 过渡来实现平滑的颜色变化，模拟出专业打击垫的灯光响应。这种软硬件双向联动正是网页音乐应用的核心魅力。

为了适应不同屏幕尺寸，可以使用 flex 布局并设置百分比宽度，同时利用 jQuery 动态计算每个格子的高度，确保在移动端也能正常触碰。触摸事件需要调用 e.preventDefault() 阻止页面滚动，并且合理处理多指触控带来的并发问题。通过 touchend 事件对象遍历所有离开的触摸点，确保每个打下的音符都能在手指抬起时正确松开。

兼容性处理与性能调优

虽然 Chrome 和 Edge 已经稳定支持 Web MIDI API，但在 Firefox 中需要用户手动启用 dom.webmidi.enabled，而 Safari 目前仍未内置支持。为了保证应用的可访问性，我们应在初始化阶段检测 API 可用性，并给出明确的降级方案，例如仅展示打击垫界面并禁用 MIDI 连接按钮。此外，Web Audio API 的 AudioContext 在 iOS 上需要用户手势才能解锁，可以借助 jQuery 在首次用户交互时调用 audioCtx.resume()。

$(document).one('touchstart mousedown', function() {
  if (synth.audioCtx.state === 'suspended') {
    synth.audioCtx.resume();
  }
});

性能方面，长时间大量创建振荡器节点可能导致内存压力。建议限制最大同时发音数（例如 32），当超过限制时，优先释放最旧的音符或力度最小的音符。同时，对于控制变化消息（如弯音、调制轮），更新频率很高，需要做节流处理，避免每毫秒级的消息都引发音频参数重设。jQuery 的 $.throttle 插件或简单的定时器配合缓存值都能达到目的。

在资源释放环节，当用户离开页面时，应断开所有活跃的振荡器并关闭 AudioContext。MIDI 管理器也需要注销所有监听器，防止内存泄漏。可以在 window 的 beforeunload 事件中用 jQuery 的 $(window).on() 完成清理工作。良好的封装意味着这些善后工作可以集中在一个 destroy() 方法中，被页面生命周期调用，增强了代码的健壮性。

Web_MIDI_APIjQuery封装网页音乐合成器修改时间：2026-08-12 09:51:51