音频开发 / 系统课时
理解 AudioWorklet 的执行边界
理解 AudioWorklet 的执行边界
AudioWorklet 的难点不是语法,而是执行边界:主线程、AudioWorkletNode 和 AudioWorkletProcessor 各负责什么,数据又如何跨边界。本节用结构图和最小代码明确实时处理代码真正运行的位置。
学习目标
- 区分主线程、
AudioWorkletNode和AudioWorkletProcessor的职责 - 识别音频数据路径与控制消息路径的差异
- 判断哪些工作适合放进
process(),哪些必须留在主线程
三个角色不是三个等价线程
主线程负责页面、业务状态、网络请求以及创建和连接音频节点。AudioWorkletNode 是主线程可操作的音频节点对象,它提供连接音频图、暴露 AudioParam、通过 port 与处理器通信等能力,但自定义 DSP 代码并不是在这个对象的方法里执行。
AudioWorkletProcessor 运行在音频渲染线程关联的 AudioWorkletGlobalScope 中。浏览器会周期性调用它的 process(),把输入帧交给处理器并读取输出。这里没有 DOM,也不应等待网络、定时器或其他可能阻塞实时音频的工作。

模块加载与对象创建发生在哪里
下面是片段示例,依赖两个 JavaScript 文件,并假设页面已在安全上下文中运行;主线程代码应由用户交互触发,以避免浏览器自动播放策略阻止 AudioContext 启动。
处理器模块 gain-processor.js 片段示例:
class GainProcessor extends AudioWorkletProcessor {
process(inputs, outputs, parameters) {
const input = inputs[0];
const output = outputs[0];
const gain = parameters.gain;
for (let channel = 0; channel < output.length; channel++) {
const source = input[channel];
const target = output[channel];
// 无输入时直接清零,避免在实时路径里创建临时缓冲区。
if (!source) {
target.fill(0);
continue;
}
// 参数可能是整块一个值,也可能按采样帧展开。
for (let i = 0; i < target.length; i++) {
const g = gain.length === 1 ? gain[0] : gain[i];
target[i] = source[i] * g;
}
}
return true;
}
static get parameterDescriptors() {
return [{ name: "gain", defaultValue: 1, minValue: 0, maxValue: 2 }];
}
}
registerProcessor("gain-processor", GainProcessor);主线程片段示例,依赖上面的模块文件:
const context = new AudioContext();
// 先加载模块,让处理器在 AudioWorkletGlobalScope 中完成注册。
await context.audioWorklet.addModule("./gain-processor.js");
const node = new AudioWorkletNode(context, "gain-processor");
node.parameters.get("gain").value = 0.5;
const oscillator = new OscillatorNode(context, { frequency: 440 });
// Node 在主线程连接音频图,逐帧增益计算仍由 Processor 执行。
oscillator.connect(node).connect(context.destination);
await context.resume();
oscillator.start();验证方法:创建成功后,主线程只负责持有 AudioWorkletNode 和修改参数;实际逐帧乘以增益的循环只会在 GainProcessor.process() 中执行。若模块没有先通过 addModule() 注册同名处理器,创建 AudioWorkletNode 会失败。
音频帧、消息和参数走不同通道
音频输入输出通过 process(inputs, outputs, parameters) 进入实时处理路径,适合持续、低延迟的数值计算。主线程与处理器之间的 MessagePort 更适合发送配置、状态和统计结果,但消息到达时间是异步的,不应把它当成逐采样点同步机制。
对需要随音频时间线平滑变化的控制量,优先定义 AudioParam。浏览器可以把自动化后的参数值随渲染量子传给处理器,比频繁 postMessage() 更适合增益、截止频率、混合比例等连续参数。
什么不该放进 process
process() 的首要约束是可预测、快速完成。高频创建大对象、复杂字符串处理、同步等待、网络访问和 UI 更新都不属于这里;这些工作应在主线程或其他后台线程完成,再把必要结果以参数或消息送进处理器。
处理器内部可以维护少量连续状态,例如滤波器延迟单元、包络值和环形缓冲区索引。需要把分析结果反馈给页面时,可以降低发送频率后通过 port.postMessage() 上报,避免每个处理周期都制造大量跨线程消息。
判断边界时可以用一个简单标准:**直接决定当前音频块输出且必须低延迟完成的数值运算放在 Processor;资源加载、界面、网络、日志聚合和复杂业务逻辑留在主线程或其他后台执行环境。**这样既能保持音频线程稳定,也能让控制层代码更容易调试和维护。