流媒体与实时通信 / 系统课时

接入语音状态与质量面板

接入语音状态与质量面板

实时语音出现“听不到、断续、延迟高”时,仅看通话是否 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 换成你的实际对象。

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

预期结果

text
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 打开,麦克风权限才能按浏览器安全策略正常申请。最简单的本地启动方式如下。

bash
python3 -m http.server 8000 --bind 127.0.0.1

预期输出

text
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,它只能说明远端轨道暂时没有可用媒体,不能单独当作丢包计。若轨道正常而丢包、抖动或缓冲明显抬升,再把问题归到传输质量层。这样面板才是诊断入口,而不是一排没有结论的数字。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入语音状态与质量面板

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

登录哪都通