音频开发 / 系统课时
通过 MessagePort 传递控制参数
通过 MessagePort 传递控制参数
本节在主线程与 AudioWorkletProcessor 之间建立双向控制通道:主线程发送增益更新和状态查询,处理器应用最新值并返回确认消息,从而把实时音频计算与界面控制逻辑解耦。
学习目标
- 使用
AudioWorkletNode.port.postMessage()向处理器发送控制消息。 - 在处理器的
port.onmessage中校验并应用参数,再把状态回传主线程。 - 设计带
type字段的简单消息协议,并理解 MessagePort 与AudioParam的适用边界。
主线程和处理器之间的消息通道
每个 AudioWorkletNode 都有一个与其处理器对应的 MessagePort。主线程从 node.port 发送消息,处理器从自身的 this.port 接收;反方向同理。消息传递是异步的,因此适合模式切换、参数配置、状态查询等控制数据,而不是逐采样点驱动 DSP。

这里传输的是结构化数据副本,而不是让主线程直接访问处理器对象。协议越简单,越容易做校验、兼容和调试。
先定义小而稳定的协议
本例只需要四种消息。所有消息都带 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() 加载。
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() 输出。
<!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>预期输出
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,优先传递小型控制对象,避免在每个音频块都发送大对象。只要主线程能收到处理器的确认与状态回传,并且声音随有效控制值变化,这条双向参数通道就已经建立完成。