音频开发 / 系统课时

编写第一个 AudioWorkletProcessor

编写第一个 AudioWorkletProcessor

本节把一个最小自定义处理器接入浏览器音频图:在 AudioWorklet 渲染线程侧注册处理器,在主线程加载模块并创建 AudioWorkletNode,最后用振荡器送入信号,确认自定义代码确实参与音频渲染。

学习目标

  • 编写继承 AudioWorkletProcessor 的处理器并通过 registerProcessor() 注册。
  • 按正确顺序完成模块加载、节点创建和音频图连接。
  • 用可听结果和控制台输出验证处理器已经运行,并识别常见加载失败原因。

处理器如何进入渲染链路

AudioWorkletProcessor 的类定义运行在 AudioWorklet 的全局作用域中,主线程并不直接调用它。主线程先用 audioContext.audioWorklet.addModule() 加载模块;模块执行 registerProcessor() 后,才能用相同名称创建 AudioWorkletNode。之后音频块会通过节点交给处理器的 process()。

AudioWorklet 处理器接入音频图

process(inputs, outputs) 会被浏览器反复调用。处理代码应按实际通道数组长度循环,不要假设每次块大小固定,也不要在实时处理路径中做 DOM 操作、网络请求或等待异步任务。

编写并注册处理器

新建 quarter-gain-processor.js。这个处理器把每个输入采样乘以 0.25,因此输出振幅约为输入的四分之一。输入未连接某个通道时显式写入静音,避免读取不存在的通道。

片段示例:以下文件依赖 AudioWorkletGlobalScope,必须由 audioWorklet.addModule() 加载,不能作为普通主线程脚本单独运行。

js
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 作为稳定输入,便于直接听出处理器是否生效。

html
<!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>

预期输出

text
AudioWorklet 已连接: true

同时应听到约 220 Hz 的持续音调。若把处理器中的乘数从 0.25 改为 1 后重新加载页面,音量会明显增大,这说明音频确实经过了自定义处理器,而不是绕过节点直达输出。

验证与常见失败

如果 addModule() 报错,先检查模块路径和响应是否成功,再检查处理器文件是否存在语法错误。若创建 AudioWorkletNode 时提示处理器名称不可用,应核对 registerProcessor() 与构造函数中的字符串是否逐字一致。

如果节点创建成功却没有声音,按“输入源是否启动 → 是否连接到 worklet → worklet 是否连接到 destination → process() 是否抛错”的顺序检查。只要控制台得到连接成功结果,并且能通过修改处理系数听到差异,第一个自定义 AudioWorkletProcessor 就已经真正进入音频渲染链路。

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

目录与阅读设置

阅读设置

17

记录一个想法

编写第一个 AudioWorkletProcessor

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

登录哪都通