音频开发 / 系统课时

完成实时音频工作台并定位故障

完成实时音频工作台并定位故障

一个可用的实时音频工作台不只是“能出声”,还要能知道声音在哪一段消失。本节把文件播放、麦克风输入、滤波效果、频谱、AudioWorklet 和诊断状态接成一条可观察链路,再用固定顺序定位无声、频谱不动和 Worklet 停止等问题。

学习目标

  • 将文件与麦克风输入接入同一条效果、AudioWorklet 和频谱分析链路
  • 为 AudioContext、输入电平、Worklet 心跳与频谱数据建立诊断观察点
  • 按信号流顺序定位权限、上下文、输入、处理节点、分析器和输出端故障

先把信号链和观察点画清楚

实时音频故障最容易被误判,是因为界面按钮、媒体输入、处理节点、Worklet、分析器和扬声器同时参与。排查时不要从代码随机猜,而是沿声音实际经过的顺序检查每一个观察点。

本工作台使用两种输入:音频文件用于验证可听输出,麦克风用于验证实时采集。当前输入依次经过低通滤波器、AudioWorklet、AnalyserNode 和总输出增益。麦克风模式把最终输出静音以避免扬声器回授,但 Worklet 和频谱仍位于静音节点之前,因此可以继续诊断采集链路。

实时音频工作台数据流与诊断点

构建可运行的最小工作台

下面是一个单文件页面。AudioWorklet 处理器通过 Blob 动态注册,因此不需要额外的处理器文件;选择本地音频后可以播放文件,也可以切换到麦克风模式。页面同时显示频谱和诊断字段。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>Web Audio Diagnostic Workbench</title>
</head>
<body>
  <input id="file" type="file" accept="audio/*">
  <button id="play">播放文件</button>
  <button id="mic">启用麦克风</button>
  <button id="stop">停止输入</button>
  <label>
    截止频率
    <input id="cutoff" type="range" min="200" max="12000" value="5000">
  </label>
  <pre id="diag"></pre>
  <canvas id="spectrum" width="720" height="220"></canvas>

  <script>
    const fileInput = document.querySelector('#file');
    const playButton = document.querySelector('#play');
    const micButton = document.querySelector('#mic');
    const stopButton = document.querySelector('#stop');
    const cutoff = document.querySelector('#cutoff');
    const diag = document.querySelector('#diag');
    const canvas = document.querySelector('#spectrum');
    const draw = canvas.getContext('2d');

    let context = null;
    let filter = null;
    let worklet = null;
    let analyser = null;
    let master = null;
    let fileBuffer = null;
    let fileSource = null;
    let micSource = null;
    let micStream = null;
    let sourceMode = 'none';
    let lastPeak = 0;
    let lastWorkletMessage = 0;

    async function ensureGraph() {
      if (context && context.state !== 'closed') {
        await context.resume();
        return;
      }

      context = new AudioContext();

      const processorSource = `
        class MeterProcessor extends AudioWorkletProcessor {
          constructor() {
            super();
            this.framesUntilReport = 0;
          }
          process(inputs, outputs) {
            const input = inputs[0];
            const output = outputs[0];
            let peak = 0;

            for (let channel = 0; channel < output.length; channel++) {
              const src = input[channel] || input[0];
              const dst = output[channel];
              if (!src) continue;

              for (let i = 0; i < dst.length; i++) {
                const sample = src[i] || 0;
                dst[i] = sample;
                peak = Math.max(peak, Math.abs(sample));
              }
            }

            this.framesUntilReport -= 128;
            if (this.framesUntilReport <= 0) {
              this.port.postMessage({ peak });
              this.framesUntilReport = sampleRate / 10;
            }
            return true;
          }
        }
        registerProcessor('meter-processor', MeterProcessor);
      `;

      const moduleUrl = URL.createObjectURL(
        new Blob([processorSource], { type: 'text/javascript' })
      );

      try {
        await context.audioWorklet.addModule(moduleUrl);
      } finally {
        URL.revokeObjectURL(moduleUrl);
      }

      filter = context.createBiquadFilter();
      filter.type = 'lowpass';
      filter.frequency.value = Number(cutoff.value);

      worklet = new AudioWorkletNode(context, 'meter-processor');
      analyser = context.createAnalyser();
      analyser.fftSize = 2048;
      master = context.createGain();

      // Worklet 消息作为处理线程仍在运行的心跳。
      worklet.port.onmessage = (event) => {
        lastPeak = event.data.peak;
        lastWorkletMessage = performance.now();
      };

      filter.connect(worklet).connect(analyser).connect(master).connect(context.destination);
      await context.resume();
    }

    function stopSource() {
      if (fileSource) {
        try {
          fileSource.stop();
        } catch {}
        fileSource.disconnect();
        fileSource = null;
      }

      if (micSource) {
        micSource.disconnect();
        micSource = null;
      }

      if (micStream) {
        for (const track of micStream.getTracks()) {
          track.stop();
        }
        micStream = null;
      }

      sourceMode = 'none';
    }

    fileInput.addEventListener('change', async () => {
      const file = fileInput.files[0];
      if (!file) return;

      await ensureGraph();
      fileBuffer = await context.decodeAudioData(await file.arrayBuffer());
    });

    playButton.addEventListener('click', async () => {
      await ensureGraph();
      if (!fileBuffer) {
        diag.textContent = '先选择一个可解码的音频文件';
        return;
      }

      stopSource();
      fileSource = context.createBufferSource();
      fileSource.buffer = fileBuffer;
      fileSource.connect(filter);
      master.gain.value = 1;
      sourceMode = 'file';
      fileSource.start();
      fileSource.onended = () => {
        if (sourceMode === 'file') sourceMode = 'none';
      };
    });

    micButton.addEventListener('click', async () => {
      await ensureGraph();
      stopSource();

      micStream = await navigator.mediaDevices.getUserMedia({ audio: true });
      micSource = context.createMediaStreamSource(micStream);
      micSource.connect(filter);
      // 麦克风仍经过 Worklet 和 Analyser,但不直接从扬声器回放。
      master.gain.value = 0;
      sourceMode = 'mic';
    });

    stopButton.addEventListener('click', stopSource);

    cutoff.addEventListener('input', () => {
      if (filter && context) {
        filter.frequency.setValueAtTime(Number(cutoff.value), context.currentTime);
      }
    });

    function render() {
      requestAnimationFrame(render);
      if (!analyser || !context) return;

      const bins = new Uint8Array(analyser.frequencyBinCount);
      analyser.getByteFrequencyData(bins);
      const activeBins = bins.reduce((count, value) => count + (value > 8 ? 1 : 0), 0);
      const heartbeatAge = lastWorkletMessage
        ? Math.round(performance.now() - lastWorkletMessage)
        : -1;

      diag.textContent = [
        `context=${context.state}`,
        `source=${sourceMode}`,
        `peak=${lastPeak.toFixed(4)}`,
        `activeBins=${activeBins}`,
        `workletAgeMs=${heartbeatAge}`,
        `masterGain=${master.gain.value}`
      ].join('\n');

      draw.clearRect(0, 0, canvas.width, canvas.height);
      const barWidth = canvas.width / bins.length;
      for (let i = 0; i < bins.length; i++) {
        const height = (bins[i] / 255) * canvas.height;
        draw.fillRect(i * barWidth, canvas.height - height, Math.max(1, barWidth), height);
      }
    }

    render();

    window.addEventListener('pagehide', () => {
      stopSource();
      if (context && context.state !== 'closed') {
        void context.close();
      }
    }, { once: true });
  </script>
</body>
</html>

预期结果

text
播放文件时:context=running,source=file,peak 与 activeBins 随声音变化,masterGain=1,可以听到处理后的音频。
启用麦克风时:source=mic,peak 与 activeBins 随麦克风输入变化,masterGain=0,因此不会把麦克风直接回放到扬声器。
处理链持续运行时:workletAgeMs 通常持续回到较小值,而不是不断增大。

页面需要通过 HTTPS 或 localhost 打开才能可靠使用麦克风。浏览器首次采集时还会请求用户授权;拒绝权限属于输入阶段失败,不是 Web Audio 节点故障。

按信号流定位故障

定位时先确认 AudioContext,再确认输入,随后检查 Worklet 与分析器,最后检查输出。这个顺序能避免在扬声器没有声音时,直接怀疑滤波器或 Worklet。

Web Audio 故障定位流程

如果 context=suspended,先检查 resume() 是否由用户点击等交互触发;现代浏览器通常不会允许页面在没有用户手势时自行开始可听音频。若上下文已经 running,但 source=none,问题仍在输入创建阶段。

当 source 正常而 peak 长期为 0.0000 时,优先检查音频文件是否真的开始播放,或者麦克风轨道是否已经 ended、被系统静音或没有有效信号。若 peak 持续变化,说明声音至少已经进入 AudioWorklet。

当 peak 有变化但 workletAgeMs 持续增长到数秒,说明诊断消息已经停止更新,应检查处理节点是否仍位于活动链路中以及上下文状态。若 Worklet 心跳正常而 activeBins=0,则重点检查 AnalyserNode 的连接位置和分析数据读取逻辑。

用症状快速缩小范围

现象 先看什么 常见原因
点击后完全没有启动 context、异常信息 自动播放限制、初始化异常
麦克风按钮立即报错 浏览器权限与安全上下文 NotAllowedError、非 HTTPS 或非 localhost
context=running 但 peak=0 source、媒体轨道 输入未启动、轨道结束、麦克风无信号
peak>0 但频谱不动 activeBins、AnalyserNode 接线 分析器未处于有效链路、渲染循环异常
Worklet 数据停止更新 workletAgeMs 节点脱离活动图、上下文暂停或处理链异常
文件频谱正常但没有声音 masterGain、系统输出 增益为零、系统静音或输出设备问题
麦克风有频谱但没有回放 source=mic、masterGain=0 本例为防止啸叫而主动静音,属于预期行为

真正可诊断的音频应用应把观察点放在信号链上,而不是只记录按钮是否点击成功。只要能够回答“上下文是否运行、输入是否有样本、处理线程是否活着、分析器是否拿到频谱、输出是否被静音”这五个问题,大多数浏览器音频故障都能被快速缩小到单个阶段。

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

目录与阅读设置

阅读设置

17

记录一个想法

完成实时音频工作台并定位故障

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

登录哪都通