简介流速监控插件是一款面向自媒体人、直播主播及视频平台运维的浏览器扩展工具能在视频上传或直播过程中实时显示流速、丢包率、延迟与缓冲时长帮助用户快速判断网络状况并及时调整分辨率、比特率或更换网络线路避免上传失败或播放卡顿。压缩包共18个文件核心逻辑以9个JavaScript文件承载包含FlowRate、background、onWall等模块另有popup.html和options.html提供操作界面配以popup.css、图标图片与MP3提示音manifest.json完成扩展声明配置整体仅286KB资源划分清晰便于按模块定位。已有1380人学习/下载。这套工具展现了完整的Chrome扩展开发链路从脚本通信、事件监听、数据统计到界面与提示反馈均有覆盖适合前端开发者作为实战样例也便于自媒体运营者直接安装部署借助声音与可视化提示监控上传链路质量及时发现并解决卡顿、丢帧等隐患从而提升发布内容的质量和用户体验。1. 流速监控插件一台小心卡顿的视频播放器到底缺了什么做点播和直播的运维久了你会遇到一种特别气人的问题播放器界面上的进度条还在往前走画面却已经卡在某一帧上转圈评论区开始刷屏但服务端监控面板里出入带宽正常CDN 也没有报错整个链路上看起来“没毛病”。这时候最缺的不是日志而是一个能直接站在视频元素旁边老老实实汇报“现在这条流的流速到底是多少、缓冲水位还剩多少、解码到底掉了几帧”的仪表盘。流速监控插件干的就是这件事它给播放器补上一只眼睛实时采集网络吞吐量、码率、帧率、掉帧率和 buffer 拥堵程度然后把黑匣子一样的播放状态摊在眼前。适合正在做 H5 播放内核、维护点播/直播页面、或者想给视频业务加上主观质量监控的从业者不用改播放器源码挂在 video 元素上就能用。2. 视频流流速到底监控什么分清楚这三个指标再写代码2.1 瞬时拉流速度不是带宽是“当前这一秒能吃进多少数据”很多第一次做流速监控的人会把“拉流速度”理解成服务器带宽或者 iperf 测出来的端到端吞吐量这是第一个认知偏差。浏览器播放器里的网络传输是分片的点播场景一次拉一个 init segment 加若干 media segment直播场景每隔几秒拉一个 TS 或 fMP4 分片所以真正需要监控的是一个时间窗口内从网络进到播放器内存的字节数。常见做法有两种第一种是读 Resource Timing APIperformance.getEntriesByType(resource) 里每个分片请求都有 startTime、duration 和 transferSize用 transferSize 除以 duration 就能得到这个请求的平均传输速度。第二种是主动探测发一个 Range 请求去拉一小段分片测量从发出到读完的耗时从而估算当前链路吞吐量。这里有个工程取舍采样间隔太短会频繁打断播放器的网络调度太长则看不到突刺我习惯把探测间隔默认设为 3 秒一次并且只在播放器处于 readyState 2 时发起。参数上要关注的三个边界缓存命中时 transferSize 是 0不能用它算速度跨域播放如果没有配置 Timing-Allow-Originresource timing 会包含 TransferSize0 而 duration 仍存在速度会被算成 0分片 URL 加了 token 签名后会过期主动探测不能复用播放器正在用的 URL得单独准备一个测速资源地址。下面这张表可以帮你快速确定自己该取哪个速度值指标采集方式代表含义适合场景分片平均速度Resource Timing 的 transferSize / duration单个分片从发起到结束的平均速率点播、切片大小稳定的 HLS瞬时链路吞吐主动 Range 请求 计时当前网络能跑到的实际带宽上限直播、弱网切换清晰度实测码率估算观察 buffer 增长量与时间服务端实际下发速率合并解码消耗判断是否发生流控2.2 帧率与掉帧率网络卡是“数据不进账”掉帧是“数据进来了但来不及做账”拉流速度只是前半段视频还要经过解封装、解码、渲染最终呈现在屏幕上所以插件至少还要盯两个帧级指标。第一个是渲染帧率使用 requestAnimationFrame 统计每秒回调次数或者用 Chrome 的 requestVideoFrameCallback 拿到每一帧的 mediaTime 和 presentedFrames第二个是 droppedFrames规范上提供 video.getVideoPlaybackQuality() 返回 totalVideoFrames、droppedVideoFrames这个值在 Chrome/Edge 上可读Safari 的实现经常缺席。掉帧和卡顿并不是同一个东西网络长时间低于码率会导致播放器进入 waiting 状态缓冲耗尽画面停住而掉帧发生在解码器跟不上渲染节奏时比如后台解码能力不足、视频编码是 4K HEVC 而机器只有软解能力或者同时开了大量 WebGL 特效。监控帧率不是为了替代网络监控而是为了在“网络正常但画面依然不流畅”的场景里快速把矛头指向解码渲染链路。另一个容易忽略的点是帧率采样本身会被浏览器节流页面切到后台时 rAF 会停止回调visibilityState 为 hidden 时采集到的帧率会直接跌到 0所以插件必须维护一个 document.visibilityState 标志前台才上报帧率后台只记录时间戳。如果你是拿 MediaSource 播放的 DASH/HLS 流还要注意 getVideoPlaybackQuality 里的数据是解码器层面的累计值而 MSE 里 appendBuffer 的速度会直接影响掉帧统计这两件事不要混在一起查。2.3 缓冲水位与卡顿率把“将来会不会卡”变成可计算的数字网络速度和帧率只能描述已经发生的状态buffered 属性则是少数能让播放器“预知未来”的数据。HTMLVideoElement.buffered 返回一个 TimeRanges 对象里面是若干已经下载好的可播放时间段我们把当前播放点 currentTime 和 buffered 的 intersection 算出来得到一个“剩余可播时长”。剩余可播时长是整个插件里最值得做报警曲线的指标剩余 15 秒说明网络健康剩余 3 秒就该高度警惕一旦跌到 0 就会触发 waiting 事件。常见做法是把 bufferHealth 做成一个采样函数每秒取一次值再配合 waiting 和 playing 事件计算卡顿次数与卡顿时长最终累加得到卡顿率。但是这里有个新手的重灾区有人直接取 buffered.end(buffered.length - 1) 减去 currentTime这个算法在分片下载不连续时是错的。浏览器播放器中通常会产生多段缓冲例如用户拖动进度条后会留下旧缓冲和新缓冲两个区间直接将末尾减去当前时间会高估水位。正确做法是遍历 TimeRanges找到包含 currentTime 的那一段用该段 end 减 currentTime如果 currentTime 恰好落在某段的 start 与 end 之间就说明下载数据是连续覆盖的否则缓冲是断档的。拉流速度、帧率和缓冲水位这套组合对应到日常排查里其实就是三句话速度低于当前码率是网络层问题掉帧率异常是解码层问题bufferHealth 到 0 说明前面的能力都不匹配播放器只能停下来等数据。3. 用 TypeScript 写一个最小可用的播放器流速监控插件3.1 项目骨架不依赖播放器内核直接挂载到 video 元素上我不建议把流速监控逻辑写进播放器内核组件之间耦合越紧后续想复用给 hls.js、dash.js 或裸 video 就越来越难。常见做法是把它做成一个独立的类构造时传入 video 元素和配置项内部自己监听事件、启动采样循环、对外提供 getSnapshot 和事件回调。工程上推荐这样组织文件src/ monitor.ts // 插件主类 samplers/ speed.ts // 网络吞吐采样 frame.ts // 帧率与掉帧采样 buffer.ts // 缓冲水位采样 display.ts // Canvas 仪表盘渲染可选 index.ts // 导出入口下面是主类的骨架注意每个采样器都是独立模块这样在非浏览器环境跑单元测试时可以单独 mock。import { SpeedSampler } from ./samplers/speed; import { FrameSampler } from ./samplers/frame; import { BufferSampler } from ./samplers/buffer; export interface MonitorOptions { probeUrl: string; // 主动测速用的资源地址 samplingIntervalMs?: number; // 采样周期默认 1000ms frozenThresholdMs?: number; // 判定画面冻结的阈值默认 500ms } export class StreamFlowMonitor { private video: HTMLVideoElement; private options: RequiredMonitorOptions; private timers: number[] []; constructor(video: HTMLVideoElement, options: MonitorOptions) { this.video video; this.options { samplingIntervalMs: 1000, frozenThresholdMs: 500, ...options, }; } start() { // 三个采样器共享同一个 video 实例分别启动 const buffer new BufferSampler(this.video, this.options.frozenThresholdMs); buffer.onUpdate((snapshot) this.emit(buffer, snapshot)); // frame 采样器需要在 video 有数据时才开始否则拿不到媒体时间 } emit(_event: string, _payload: unknown) { // 事件总线外部通过 onReport 订阅 } destroy() { this.timers.forEach((t) window.clearInterval(t)); } }参数说明probeUrl 必须指向一个允许跨域的、体积在 100KB 左右的静态资源不能直接拿播放器当前播放的视频地址测速因为 Range 请求和播放器自身的下载会互相竞争。frozenThresholdMs 判断的是“video.currentTime 长时间不变且 readyState 为 3 以上”的异常冻结状态典型值是 500ms 到 1000ms设置过小会在网速慢时产生大量误报。3.2 核心埋点一瞬时拉流速度用分段 Range 探测实现Resource Timing 只能拿到“分片下载完之后的平均值”拿不到实时吞吐所以我更偏向主动探测。思路是临时创建一个 fetch 请求只请求资源尾部的一小段测量从发起到流结束的耗时从而估算当前链路真实吞吐。export interface SpeedSnapshot { bps: number; // 每秒比特数 bytes: number; // 本次探测读取的字节数 durationMs: number; // 请求耗时 } export class SpeedSampler { constructor(private probeUrl: string) {} async probe(): PromiseSpeedSnapshot { const start performance.now(); // 用尾部分段探测避免把整个文件拉进来浪费流量 const res await fetch(this.probeUrl, { headers: { Range: bytes0-1023 }, cache: no-store, }); if (!res.ok res.status ! 206) { throw new Error(probe failed: ${res.status}); } // 读取数据块确保数据真正到达本地 const blob await res.blob(); const durationMs Math.max(1, performance.now() - start); const bytes blob.size; return { bps: bytes * 8 / (durationMs / 1000), bytes, durationMs }; } }逻辑说明Range 请求只拉前 1KB是为了让探测足够轻量如果是大码率视频的拉流场景样本太小会高估速度建议把 Range 放大到 256KB。status 有 206 和 200 两种可能部分静态服务器不识别 Range 会直接返回 200 和完整文件这时 blob.size 可能变得很大成本失控所以要在代码里加一个上限判断。这个采样器必须在后台启动不能在播放器恢复播放的瞬间去抢带宽。3.3 核心埋点二帧率与掉帧统计优先用 requestVideoFrameCallback帧率采样在 Chrome/Edge 上有现成入口Safari 的落后程度比想象中大所以做了降级。requestVideoFrameCallback 的回调参数里包含媒体帧时间戳和呈现帧序号这是浏览器层面最准的帧来源。export class FrameSampler { private lastTime -1; private lastPresented -1; private dropped 0; constructor(private video: HTMLVideoElement) {} start() { if (requestVideoFrameCallback in this.video) { const loop (_now: number, meta: VideoFrameCallbackMetadata) { if (this.lastPresented 0 meta.presentedFrames this.lastPresented) { // 预期 1如果跳帧说明解码器丢帧了 const expected this.lastPresented 1; this.dropped meta.presentedFrames - expected; } this.lastPresented meta.presentedFrames; this.video.requestVideoFrameCallback(loop); }; this.video.requestVideoFrameCallback(loop); } else { // Safari 降级用 rAF 回调间隔做帧率估算 this.startRafFallback(); } } private startRafFallback() { let last performance.now(); const loop (now: number) { const frameMs now - last; last now; // 超过 120ms 视为一次明显掉帧 if (frameMs 120) this.dropped 1; requestAnimationFrame(loop); }; requestAnimationFrame(loop); } }逻辑说明requestVideoFrameCallback 是媒体帧回调只在有帧渲染时执行所以可以用 presentedFrames 的差值判断掉帧比 rAF 时间间隔准确得多。降级方案里 120ms 这个阈值有玄学成分它近似等于 8fps如果你监控的是 60fps 内容120ms 确实能捕获明显掉帧但如果内容本身是 24fps 电影120ms 不算异常需要根据 contentRate 动态调整阈值。我没有在这个版本里做动态阈值实际工程中建议把内容帧率作为参数传入。3.4 核心埋点三缓冲水位解决 TimeRanges 多段相交问题export class BufferSampler { constructor( private video: HTMLVideoElement, private frozenThresholdMs 500, ) {} getHealth(): number { const time this.video.currentTime; const ranges this.video.buffered; for (let i 0; i ranges.length; i) { const start ranges.start(i); const end ranges.end(i); if (time start time end) { return end - time; } } // 当前播放点不在任何缓冲范围说明缓冲已经断档 return 0; } watch(callback: (health: number) void) { let lastTime this.video.currentTime; this.video.addEventListener(waiting, () { // 当 buffered 为 0 时播放器必然等待记录一次卡顿开始 }); setInterval(() { const health this.getHealth(); // 额外检测画面冻结时间没走但缓冲不为 0 const now this.video.currentTime; if (Math.abs(now - lastTime) 0.01 health 0.5) { // 可能解码卡死或者视频本身静止 } lastTime now; callback(health); }, 500); } }逻辑说明这个采样器的核心价值在于遍历 buffered 找到当前播放点所在的那一段而不是简单取最大值。冻结检测里我同时判断了 health 0.5是为了排除正在播放一段静止画面的合法场景如果你监控的是监控摄像头这类几乎静止的画面这个阈值很容易误报需要改成对比媒体帧时间戳而不是 currentTime。这里的 500ms 采样精度对瞬时卡顿足够但如果你要做卡顿率上报建议把每次 waiting 开始到 playing 之间的耗时累计上报而不是只看水位曲线。3.5 把插件挂到现有播放器上的最小集成方式下面这段代码展示了如何在一个裸 video 播放器上启动监控并订阅数据对于使用 HLS.js 或 DPlayer 等情况只需在播放器的 created/ready 回调里调用 monitor.start() 即可。const video document.querySelector(video)!; const monitor new StreamFlowMonitor(video, { probeUrl: https://your-domain.com/probe.bin, samplingIntervalMs: 1000, }); monitor.onReport((report) { // 上报到监控平台或绘制到页面角落 console.log(report.bps, report.frameRate, report.bufferHealth); }); monitor.start();集成时有一个非常容易翻车的点插件一定要在用户点击播放之后再 start不要自动开始。否则页面首次加载时浏览器还没触发媒体下载主动探测会和首屏资源竞争网络把关键请求拖慢。另外 start 之前要判断 video.readyState 2避免拿到空 buffered 导致前几次采样全是 0影响报警判断。4. 流速监控插件常见翻车现场排查与避坑4.1 transferSize 全是 0速度曲线全部失真现象是 resource timing 里每个分片的 duration 都正常但 transferSize 为 0导致算出来的速度恒等于 0而且只在部分 CDN 域名上发生。原因是跨域资源没有返回 Timing-Allow-Origin 响应头。浏览器出于安全考虑默认不对跨域暴露传输字节数只有服务器明确指定Timing-Allow-Origin: *或当前站点域名时transferSize 才可以读取。解决方法是让播放器域名下的静态资源统一加上 Timing-Allow-Origin 响应头。如果是 M3U8/DASH 清单里挂载的媒体分片也要确认各分片 CDN 都带了这个头。生产环境我建议不要只依赖 Resource Timing主用主动探测Resource Timing 作为辅助校验这样即使 CDN 配置漏项插件也不会瞎。4.2 主动测速请求把播放器卡顿搞得更严重了现象是接入插件后播放开始卡顿发现插件每 3 秒就发起一次 Range 请求和视频分片请求争抢带宽尤其当 probeUrl 选择了播放器同域的大文件时一次探测能吃掉几百 KB。原因是采样器没有考虑网络竞争和频率控制也没有避免在播放器进入 low water level 时探测。解决方法是把探测间隔加到 5 秒以上并且每次探测前检查 video.buffered 当前剩余水位如果 bufferHealth 小于 5 秒就直接跳过本次探测保证播放器优先补数据。我还习惯把 probeUrl 指向一个 1MB 左右但只拉前 64KB 的文件开销可控同时把 fetch 请求标记为 low priority避免挤占主资源。4.3 掉帧率在 Safari 上一直是 0但用户反馈画面撕裂现象是 Chrome 上掉帧曲线正常Safari 上 droppedFrames 永远为 0而实际播放 4K 内容时拖动明显卡顿。原因是 Safari 没有完整实现 getVideoPlaybackQuality或者该值只针对当前解码器输出统计没有把 MSE 中丢掉的 frame 也算进来。解决方法是先检测 API 是否存在如果不存在则切换为 rAF 降级方案再配合 MediaSource 的 buffered 更新节奏来判断是否“取数不及时”。我血泪经验是不要试图在 Safari 上精确预测解码掉帧只能做区间判断比如 rAF 间隔超过 500ms 才记一次异常帧否则误报率高得没法看。4.4 bufferHealth 明明是 60 秒画面还是转圈圈现象是插件面板上显示剩余可播放时长 60 秒但播放器突然 waiting进度条停住。原因是当前播放点虽然落在 buffered 范围内但那一段缓冲内容可能只是 init segment 或加密元数据并没有包含可解码的媒体帧。HTMLVideoElement.buffered 只能表示“数据已经被放入缓冲区”不能区分能否立即解码播放。另一个常见原因是 seek 后旧缓冲区间被保留播放点落在一个孤立的、之后没有新数据的区域。解决方法是遇到 waiting 后立即拉取 video.currentTime 和 buffered 区间做重叠校验再对比 lastAppendedEnd 之间是否真的是连续媒体数据。如果你用的是 HLS.js更要直接监听 hls.js 的 stats 里的 buffered 更新因为它内部的 buffer 管理比 video.buffered 更细会区分 source buffer 里 media segment 是否完整。4.5 后台标签页把采集停摆了卡顿率被算成 100%现象是用户切到其他标签页几分钟后回来卡顿率统计暴跌所有速度曲线都冻结。原因是 rAF 和 setInterval 在后台标签页都会被浏览器强限流通常降低到每秒 1 次甚至完全挂起而我们的采样器往回调里写了当前时间戳所以后台时间跨度被算成一段超长卡顿。解决方法是所有采样器在输出前先检查 document.visibilityState为 hidden 时只记录前后时间点不计算卡顿也不上报速度回到前台后再做一次全量重采。另外 setInterval 在移动端浏览器上也会被自动暂停所以要监听 pagehide、freeze 事件主动销毁插件避免恢复时误报。监控数据不是越细越好前提是采集器自己不能成为卡顿制造者。5. 流速监控有了之后把数据变成排查与验收的工具5.1 用 Canvas 在页面角落画一张实时流速波形与其把原始数字铺在控制台上不如直接叠一个 200px 高的 Canvas 面板挂在视频右下角既能自己排查问题也能让支持同学直接截图反馈。function drawWave(canvas: HTMLCanvasElement, samples: number[], maxBps: number) { const ctx canvas.getContext(2d)!; const w canvas.width; const h canvas.height; ctx.clearRect(0, 0, w, h); ctx.beginPath(); samples.forEach((bps, i) { const y h - (bps / maxBps) * h; if (i 0) ctx.moveTo(i * (w / samples.length), y); else ctx.lineTo(i * (w / samples.length), y); }); ctx.strokeStyle #10b981; ctx.stroke(); }每来一次采样就把 bps 推入 samples 数组保持最多 60 个点超过后再整体平移。这块逻辑很简单但要注意 canvas 的 devicePixelRatio 适配否则在 2x 屏上波形会发虚。5.2 把流速数据接到清晰度切换上去你的插件不只是在看而是在帮播放器做决定当瞬时拉流速度持续 3 秒低于当前码率的 1.5 倍时播放器大概率会进入缓冲反过来持续 10 秒高于当前码率 2 倍则说明可以尝试升档。这是很多自适应流控算法的基础逻辑。你的插件不需要自己去切换清晰度但可以在 onReport 里暴露这样的建议事件让播放器上层自行决定。比如monitor.onReport((report) { if (report.bps currentBitrate * 1.5) { notify(downshift, network-pressure); } });这里有个关键点码率档位表要从播放器传入而不是插件自己去解析 m3u8。这能保持插件定位纯粹提供测量结果不干预决策。有关码率自适应的完整算法不在本文范围内但你至少应该知道流控的大部分信源来自这里。5.3 验证插件统计数据是否靠谱和 devtools 对照一次就放心了插件写完不是上线就完了至少要做一次这样的验证先用 devtools 的网络限流档比如 Slow 4G固定带宽播放一段 30 秒的视频同时让插件每秒输出一次 bps 和 bufferHealth然后打开浏览器任务管理器或 Network 面板里对应媒体请求的 transferred 字节数。做完之后对比平均值只要插件测算结果和浏览器记录的误差在正负 10% 内就说明采样逻辑没问题。我最开始做这插件时只盯着 Chrome上线后客服收到一堆真 4K 播放器反馈才发现 Safari 上所有指标都不可用——那是我第一次认识到兼容性降级比功能本身更重要。之后我定了一个习惯每个采样器至少保留两条数据通路默认走 API 精确统计不可用时降级到 rAF 计时或异常事件推断。这样插件才不会在别人浏览器上成为黑匣子。流速监控不是多高深的技术但它能把“用户说卡”变成一张波形图让后端、CDN、播放器三方拿着同一组数据对着修。希望帮到你。本文还有配套的精品资源点击获取