流媒体与实时通信 / 系统课时
接入语音状态与质量面板
接入语音状态与质量面板
实时语音出现“听不到、断续、延迟高”时,仅看通话是否 connected 不够。这个面板把连接、音轨和 WebRTC Stats 放在同一处,让你先判断问题属于信令/ICE、媒体轨道,还是已经进入传输质量层。
学习目标
- 区分连接状态、音轨状态和传输质量三层信号
- 用
RTCPeerConnection.getStats()提取丢包、抖动、抖动缓冲和 RTT - 搭出一个可直接运行的本地诊断面板,并知道如何读取异常
面板先回答三个问题
诊断入口不需要一开始塞进几十个指标。第一层看 connectionState 与 iceConnectionState,确认 PeerConnection 是否真正建立;第二层看远端 MediaStreamTrack 的 readyState 和 muted,判断轨道是否存在且正在收到媒体;第三层才进入 Stats,解释“已经连上但为什么听感差”。
| 层次 | 建议展示 | 主要回答 |
|---|---|---|
| 连接 | connectionState、iceConnectionState |
通路是否建立、是否断开 |
| 轨道 | readyState、muted |
音频轨道是否存活、是否暂时无媒体 |
| 质量 | packetsLost、jitter、平均抖动缓冲、currentRoundTripTime |
丢包、到达节奏和往返时延是否恶化 |
jitter 和 currentRoundTripTime 在 Stats 中以秒为单位,面板通常换算成毫秒。jitterBufferDelay 是累计值,应除以 jitterBufferEmittedCount 才能得到平均缓冲等待时间,否则数字会持续增长而失去直观意义。

做一个可运行的诊断面板
下面用两个本地 RTCPeerConnection 构造回环通话:麦克风发给 pc1,pc2 接收并播放。这样不依赖信令服务器,就能验证状态采集逻辑;接入真实项目时,只需要把 pc2 和 remoteTrack 换成你的实际对象。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>WebRTC Audio Diagnostics</title>
</head>
<body>
<button id="start">开始回环通话</button>
<audio id="remoteAudio" autoplay controls></audio>
<pre id="panel">not started</pre>
<script>
const start = document.querySelector("#start");
const remoteAudio = document.querySelector("#remoteAudio");
const panel = document.querySelector("#panel");
function formatMs(seconds) {
return Number.isFinite(seconds) ? `${(seconds * 1000).toFixed(1)} ms` : "n/a";
}
async function renderStats(pc, remoteTrack) {
const reports = await pc.getStats();
let inbound;
let pair;
reports.forEach((report) => {
if (report.type === "inbound-rtp" && report.kind === "audio" && !report.isRemote) {
inbound = report;
}
if (report.type === "candidate-pair" && report.state === "succeeded" && report.nominated) {
pair = report;
}
});
const avgJitterBufferSeconds =
inbound?.jitterBufferEmittedCount > 0
? inbound.jitterBufferDelay / inbound.jitterBufferEmittedCount
: NaN;
panel.textContent = [
`connection: ${pc.connectionState}`,
`ice: ${pc.iceConnectionState}`,
`track: ${remoteTrack?.readyState ?? "n/a"} / muted=${remoteTrack?.muted ?? "n/a"}`,
`packetsLost: ${inbound?.packetsLost ?? "n/a"}`,
`jitter: ${formatMs(inbound?.jitter)}`,
`avg jitterBuffer: ${formatMs(avgJitterBufferSeconds)}`,
`rtt: ${formatMs(pair?.currentRoundTripTime)}`
].join("\n");
}
function waitForIceGatheringComplete(pc) {
if (pc.iceGatheringState === "complete") return Promise.resolve();
return new Promise((resolve) => {
const handleChange = () => {
if (pc.iceGatheringState === "complete") {
pc.removeEventListener("icegatheringstatechange", handleChange);
resolve();
}
};
pc.addEventListener("icegatheringstatechange", handleChange);
});
}
start.addEventListener("click", async () => {
start.disabled = true;
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const pc1 = new RTCPeerConnection();
const pc2 = new RTCPeerConnection();
let remoteTrack;
pc2.ontrack = (event) => {
remoteTrack = event.track;
remoteAudio.srcObject = event.streams[0];
};
stream.getTracks().forEach((track) => pc1.addTrack(track, stream));
await pc1.setLocalDescription(await pc1.createOffer());
await waitForIceGatheringComplete(pc1);
await pc2.setRemoteDescription(pc1.localDescription);
await pc2.setLocalDescription(await pc2.createAnswer());
await waitForIceGatheringComplete(pc2);
await pc1.setRemoteDescription(pc2.localDescription);
setInterval(() => renderStats(pc2, remoteTrack), 1000);
});
</script>
</body>
</html>预期结果
connection: <CONNECTION_STATE>
ice: <ICE_STATE>
track: <TRACK_STATE> / muted=<BOOLEAN>
packetsLost: <COUNT>
jitter: <MS> ms
avg jitterBuffer: <MS> ms
rtt: <MS> ms正常建立后,<CONNECTION_STATE> 通常为 connected,<ICE_STATE> 常见为 connected 或 completed,<TRACK_STATE> 应为 live。<COUNT>、<MS> 与 <BOOLEAN> 会随设备和网络变化。首次连接时部分字段短暂显示 n/a 是正常的,因为对应 Stats 报告可能尚未产生。
把文件保存为 index.html 后,从 localhost 或 HTTPS 打开,麦克风权限才能按浏览器安全策略正常申请。最简单的本地启动方式如下。
python3 -m http.server 8000 --bind 127.0.0.1预期输出
Serving HTTP on 127.0.0.1 port 8000 (http://127.0.0.1:8000/) ...随后访问 http://127.0.0.1:8000,点击“开始回环通话”并允许麦克风权限。不同 Python 版本的启动提示文本可能略有差异。
把指标变成可排障信号
不要用单次采样直接判故障。packetsLost 是累计计数,真正有意义的是一段时间内的增量;jitter 会随到达节奏变化而波动;平均抖动缓冲上升说明接收端正在用更多等待换取连续播放;RTT 持续变高则说明路径时延或排队可能在恶化。
实际项目中建议每 1 秒采样一次、只保留最近几十秒趋势,并同时显示状态变化时间点。若连接断开,先处理 ICE 或网络问题;若连接正常但轨道 muted=true,它只能说明远端轨道暂时没有可用媒体,不能单独当作丢包计。若轨道正常而丢包、抖动或缓冲明显抬升,再把问题归到传输质量层。这样面板才是诊断入口,而不是一排没有结论的数字。