音频开发 / 系统课时
完成实时音频工作台并定位故障
完成实时音频工作台并定位故障
一个可用的实时音频工作台不只是“能出声”,还要能知道声音在哪一段消失。本节把文件播放、麦克风输入、滤波效果、频谱、AudioWorklet 和诊断状态接成一条可观察链路,再用固定顺序定位无声、频谱不动和 Worklet 停止等问题。
学习目标
- 将文件与麦克风输入接入同一条效果、AudioWorklet 和频谱分析链路
- 为 AudioContext、输入电平、Worklet 心跳与频谱数据建立诊断观察点
- 按信号流顺序定位权限、上下文、输入、处理节点、分析器和输出端故障
先把信号链和观察点画清楚
实时音频故障最容易被误判,是因为界面按钮、媒体输入、处理节点、Worklet、分析器和扬声器同时参与。排查时不要从代码随机猜,而是沿声音实际经过的顺序检查每一个观察点。
本工作台使用两种输入:音频文件用于验证可听输出,麦克风用于验证实时采集。当前输入依次经过低通滤波器、AudioWorklet、AnalyserNode 和总输出增益。麦克风模式把最终输出静音以避免扬声器回授,但 Worklet 和频谱仍位于静音节点之前,因此可以继续诊断采集链路。

构建可运行的最小工作台
下面是一个单文件页面。AudioWorklet 处理器通过 Blob 动态注册,因此不需要额外的处理器文件;选择本地音频后可以播放文件,也可以切换到麦克风模式。页面同时显示频谱和诊断字段。
<!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>预期结果
播放文件时:context=running,source=file,peak 与 activeBins 随声音变化,masterGain=1,可以听到处理后的音频。
启用麦克风时:source=mic,peak 与 activeBins 随麦克风输入变化,masterGain=0,因此不会把麦克风直接回放到扬声器。
处理链持续运行时:workletAgeMs 通常持续回到较小值,而不是不断增大。页面需要通过 HTTPS 或 localhost 打开才能可靠使用麦克风。浏览器首次采集时还会请求用户授权;拒绝权限属于输入阶段失败,不是 Web Audio 节点故障。
按信号流定位故障
定位时先确认 AudioContext,再确认输入,随后检查 Worklet 与分析器,最后检查输出。这个顺序能避免在扬声器没有声音时,直接怀疑滤波器或 Worklet。

如果 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 |
本例为防止啸叫而主动静音,属于预期行为 |
真正可诊断的音频应用应把观察点放在信号链上,而不是只记录按钮是否点击成功。只要能够回答“上下文是否运行、输入是否有样本、处理线程是否活着、分析器是否拿到频谱、输出是否被静音”这五个问题,大多数浏览器音频故障都能被快速缩小到单个阶段。