音频开发 / 系统课时

通过 MessagePort 传递控制参数

通过 MessagePort 传递控制参数

本节在主线程与 AudioWorkletProcessor 之间建立双向控制通道:主线程发送增益更新和状态查询,处理器应用最新值并返回确认消息,从而把实时音频计算与界面控制逻辑解耦。

学习目标

  • 使用 AudioWorkletNode.port.postMessage() 向处理器发送控制消息。
  • 在处理器的 port.onmessage 中校验并应用参数,再把状态回传主线程。
  • 设计带 type 字段的简单消息协议,并理解 MessagePort 与 AudioParam 的适用边界。

主线程和处理器之间的消息通道

每个 AudioWorkletNode 都有一个与其处理器对应的 MessagePort。主线程从 node.port 发送消息,处理器从自身的 this.port 接收;反方向同理。消息传递是异步的,因此适合模式切换、参数配置、状态查询等控制数据,而不是逐采样点驱动 DSP。

MessagePort 双向控制时序

这里传输的是结构化数据副本,而不是让主线程直接访问处理器对象。协议越简单,越容易做校验、兼容和调试。

先定义小而稳定的协议

本例只需要四种消息。所有消息都带 type,处理器不依赖对象字段是否“碰巧存在”来猜测意图。

type 方向 关键字段 用途
set-gain 主线程 → 处理器 value 设置增益
get-state 主线程 → 处理器 无 请求当前状态
gain-updated 处理器 → 主线程 value 确认新增益已采用
state 处理器 → 主线程 gain 返回当前状态

增益在本例中限定为 0 到 2。越界值不会进入音频计算,而是由处理器回传 error 消息。这样可以把“消息收到”和“参数有效”区分开。

实现双向控制

新建 message-gain-processor.js。处理器在构造阶段安装消息监听器;process() 只读取已经校验过的 this.gain,避免把协议解析工作放进每次音频块处理路径。

片段示例:以下处理器文件依赖 AudioWorkletGlobalScope,必须由主线程通过 audioWorklet.addModule() 加载。

js
class MessageGainProcessor extends AudioWorkletProcessor {
  constructor() {
    super();
    this.gain = 1;

    this.port.onmessage = (event) => {
      const message = event.data;

      if (!message || typeof message !== "object") {
        this.port.postMessage({ type: "error", message: "invalid message" });
        return;
      }

      if (message.type === "set-gain") {
        const nextGain = Number(message.value);

        if (Number.isFinite(nextGain) && nextGain >= 0 && nextGain <= 2) {
          this.gain = nextGain;
          this.port.postMessage({ type: "gain-updated", value: this.gain });
        } else {
          this.port.postMessage({
            type: "error",
            message: "gain must be between 0 and 2"
          });
        }
        return;
      }

      if (message.type === "get-state") {
        this.port.postMessage({ type: "state", gain: this.gain });
        return;
      }

      this.port.postMessage({ type: "error", message: "unknown message type" });
    };
  }

  process(inputs, outputs) {
    const input = inputs[0];
    const output = outputs[0];

    for (let channelIndex = 0; channelIndex < output.length; channelIndex += 1) {
      const inputChannel = input[channelIndex];
      const outputChannel = output[channelIndex];

      if (!inputChannel) {
        outputChannel.fill(0);
        continue;
      }

      for (let sampleIndex = 0; sampleIndex < outputChannel.length; sampleIndex += 1) {
        outputChannel[sampleIndex] = inputChannel[sampleIndex] * this.gain;
      }
    }

    return true;
  }
}

registerProcessor("message-gain-processor", MessageGainProcessor);

通过 localhost 或 HTTPS 提供目录后,主线程加载模块并创建节点,再在同一个 port 上监听处理器回传的数据。为了让结果稳定可核对,日志使用 JSON.stringify() 输出。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>AudioWorklet MessagePort Demo</title>
</head>
<body>
  <button id="start">启动并设置增益</button>
  <script type="module">
    const button = document.querySelector("#start");

    button.addEventListener("click", async () => {
      button.disabled = true;

      const audioContext = new AudioContext();
      await audioContext.audioWorklet.addModule("./message-gain-processor.js");

      const oscillator = new OscillatorNode(audioContext, { frequency: 220 });
      const workletNode = new AudioWorkletNode(
        audioContext,
        "message-gain-processor"
      );

      workletNode.port.onmessage = (event) => {
        console.log(`worklet -> main ${JSON.stringify(event.data)}`);
      };

      oscillator.connect(workletNode).connect(audioContext.destination);
      await audioContext.resume();
      oscillator.start();

      workletNode.port.postMessage({ type: "set-gain", value: 0.2 });
      workletNode.port.postMessage({ type: "get-state" });
    });
  </script>
</body>
</html>

预期输出

text
worklet -> main {"type":"gain-updated","value":0.2}
worklet -> main {"type":"state","gain":0.2}

同时会听到经过 0.2 增益处理的持续音调。把发送值改成 3 时,应收到错误消息而不是更新确认,这可以验证协议校验确实发生在处理器侧。

MessagePort 不替代 AudioParam

MessagePort 适合低频、离散的控制事件,但消息何时到达处理器不是逐采样可安排的。若参数需要与音频时间轴精确对齐,例如做平滑淡入、包络或高频自动化,应通过处理器的 parameterDescriptors 暴露 AudioParam,再使用 Web Audio 的自动化方法调度。

对于 MessagePort,优先传递小型控制对象,避免在每个音频块都发送大对象。只要主线程能收到处理器的确认与状态回传,并且声音随有效控制值变化,这条双向参数通道就已经建立完成。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

通过 MessagePort 传递控制参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通