音频开发 / 系统课时
编写第一个 AudioWorkletProcessor
编写第一个 AudioWorkletProcessor
本节把一个最小自定义处理器接入浏览器音频图:在 AudioWorklet 渲染线程侧注册处理器,在主线程加载模块并创建 AudioWorkletNode,最后用振荡器送入信号,确认自定义代码确实参与音频渲染。
学习目标
- 编写继承
AudioWorkletProcessor的处理器并通过registerProcessor()注册。 - 按正确顺序完成模块加载、节点创建和音频图连接。
- 用可听结果和控制台输出验证处理器已经运行,并识别常见加载失败原因。
处理器如何进入渲染链路
AudioWorkletProcessor 的类定义运行在 AudioWorklet 的全局作用域中,主线程并不直接调用它。主线程先用 audioContext.audioWorklet.addModule() 加载模块;模块执行 registerProcessor() 后,才能用相同名称创建 AudioWorkletNode。之后音频块会通过节点交给处理器的 process()。

process(inputs, outputs) 会被浏览器反复调用。处理代码应按实际通道数组长度循环,不要假设每次块大小固定,也不要在实时处理路径中做 DOM 操作、网络请求或等待异步任务。
编写并注册处理器
新建 quarter-gain-processor.js。这个处理器把每个输入采样乘以 0.25,因此输出振幅约为输入的四分之一。输入未连接某个通道时显式写入静音,避免读取不存在的通道。
片段示例:以下文件依赖 AudioWorkletGlobalScope,必须由 audioWorklet.addModule() 加载,不能作为普通主线程脚本单独运行。
class QuarterGainProcessor extends AudioWorkletProcessor {
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] * 0.25;
}
}
return true;
}
}
registerProcessor("quarter-gain-processor", QuarterGainProcessor);这里的注册名 quarter-gain-processor 是主线程创建节点时使用的唯一关联键。示例返回 true,让演示期间处理器持续参与渲染;真实处理器还应结合是否持续产出音频来设计生命周期。
加载并连接节点
通过 localhost 或 HTTPS 提供目录后,再创建 index.html。为了符合浏览器的自动播放限制,把 AudioContext 的创建和启动放在按钮点击事件中。示例使用 OscillatorNode 作为稳定输入,便于直接听出处理器是否生效。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>AudioWorklet Processor 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("./quarter-gain-processor.js");
const oscillator = new OscillatorNode(audioContext, { frequency: 220 });
const workletNode = new AudioWorkletNode(
audioContext,
"quarter-gain-processor"
);
workletNode.addEventListener("processorerror", () => {
console.error("AudioWorklet 处理器发生未捕获异常");
});
oscillator.connect(workletNode).connect(audioContext.destination);
await audioContext.resume();
oscillator.start();
console.log(`AudioWorklet 已连接: ${workletNode.context === audioContext}`);
});
</script>
</body>
</html>预期输出
AudioWorklet 已连接: true同时应听到约 220 Hz 的持续音调。若把处理器中的乘数从 0.25 改为 1 后重新加载页面,音量会明显增大,这说明音频确实经过了自定义处理器,而不是绕过节点直达输出。
验证与常见失败
如果 addModule() 报错,先检查模块路径和响应是否成功,再检查处理器文件是否存在语法错误。若创建 AudioWorkletNode 时提示处理器名称不可用,应核对 registerProcessor() 与构造函数中的字符串是否逐字一致。
如果节点创建成功却没有声音,按“输入源是否启动 → 是否连接到 worklet → worklet 是否连接到 destination → process() 是否抛错”的顺序检查。只要控制台得到连接成功结果,并且能通过修改处理系数听到差异,第一个自定义 AudioWorkletProcessor 就已经真正进入音频渲染链路。