企业官网建设流程全解析

livekit-client 是 LiveKit 官方的浏览器端 JavaScript SDK，其中的 Frame Metadata（帧元数据）功能允许你为发出的每一帧视频附加用户时间戳、帧编号和自定义数据，并随 WebRTC 视频流低延迟送达所有订阅端——这为「AI 推理结果逐帧同步到观众端」提供了最直接的通道。下面这份实战指南带你从原理到代码，快速跑通这条链路。

一、Frame Metadata 是什么：给每一帧视频"贴上标签"

传统的实时视频应用里，如果你想把「这一帧检测到了人脸」「这一帧的球速是 180km/h」这类信息发给观众，通常会走 DataChannel。但 DataChannel 和视频帧是两条独立通道，无法保证"这条消息对应的是哪一帧"。

Frame Metadata 的思路是：把元数据直接"粘"在编码后的视频帧尾部，让它像行李牌一样跟着帧走。SDK 会在编码帧末尾追加一段带魔数LKTS的 Packet Trailer（包尾数据），接收端在解码前把这段 Trailer 剥离出来，得到结构化元数据：

字段定义见 types.ts，LKTS魔数与 TLV 标签定义在 frameMetadata.ts。

二、工作原理：AI 推理结果如何随视频帧低延迟传输

整个特性由一个Web Worker 流水线驱动，主线程几乎零开销：

1. 发布端（encode 路径）：Worker 接管 RTCRtpSender 的编码流，在每一帧入队前调用appendPacketTrailerToEncodedFrame()把时间戳/帧编号追加到帧尾部，帧编号在 Worker 内自动递增（见 frameMetadata.worker.ts）；
2. 订阅端（decode 路径）：Worker 接管接收端编码流，对每一帧执行processPacketTrailer()，剥离 Trailer 并按 RTP 时间戳把元数据存入缓存；
3. 查询：视频真正显示时，你再用lookupFrameMetadata()按 RTP 时间戳取出"正在播放的这一帧"的元数据。

剥离与追加的核心算法分别在 frameMetadata.ts 中，接收端缓存逻辑（含 Simulcast 切流时的缓存清理、300 帧容量上限）在 FrameMetadataExtractor.ts。

💡 开启 E2EE 加密时，Trailer 的剥离由 E2EE 的 FrameCryptor Worker 在解密前完成，无需额外配置。

三、发布端实战：3 步为视频帧附加时间戳与帧编号

第 1 步：创建并传入 frameMetadata 专用 Worker。SDK 的构建脚本 rollup.config.fm-worker.js 会产出独立的fm.worker脚本（.fm.worker.js/.fm.worker.mjs），用它创建 Worker 实例即可。

第 2 步：初始化房间时挂载frameMetadata扩展：

const worker = new Worker(new URL('livekit-client.fm.worker.js', import.meta.url)); const room = createRoom( { frameMetadata: { worker } }, [frameMetadata({ worker })], ); await room.connect(url, token);

扩展定义见 extension.ts，createRoom工厂在 createRoom.ts。

第 3 步：发布视频时声明要附加哪些元数据：

await room.localParticipant.publishTrack(videoTrack, { frameMetadata: { timestamp: true, frameId: true }, });

该选项声明在 options.ts：开启timestamp后 SDK 写入Date.now()毫秒时间戳；开启frameId后写入自动递增的帧编号。发布侧不需要注册扩展，它属于核心发布链路的一部分。

四、订阅端实战：逐帧查询 AI 推理结果

订阅端同样需要传入 Worker（与发布端可复用同一份脚本）。当远端轨道订阅后，FrameMetadataManager 会自动识别带有 frameMetadata 能力的轨道，把它的编码流交给 Worker 处理。

你只需要两件事：监听TrackEvent.TimeSyncUpdate拿到当前显示帧的 RTP 时间戳，再调用lookupFrameMetadata()取元数据：

videoTrack.on(TrackEvent.TimeSyncUpdate, ({ rtpTimestamp }) => { const meta = videoTrack.lookupFrameMetadata({ rtpTimestamp }); // meta.userTimestamp / meta.frameId —— 正在屏幕上显示的这一帧的元数据 });

• TimeSyncUpdate由 RemoteTrack.ts 通过requestAnimationFrame逐帧驱动，事件定义见 events.ts；
• lookupFrameMetadata()实现在 RemoteVideoTrack.ts。

这样你拿到的元数据与画面上显示的画面是严格逐帧对齐的——这是 DataChannel 方案难以做到的。

五、典型 AI 应用场景 🎯

• AI 目标检测叠加：推理端对摄像头画面做逐帧检测，把"检测到了人/车/商品"的结果通过帧元数据同步给观众端做实时标注；
• AI 字幕与说话人识别：把 ASR 结果的时间戳挂在对应帧上，实现口型与字幕的逐帧对齐；
• 体育赛事数据：把球速、比分等 AI 计算结果随视频帧下发，天然抗乱序、抗丢包重传错位；
• 端到端延迟测量：利用userTimestamp与接收端本地时钟对比，精确测量单帧传输延迟。

六、环境要求与注意事项 ⚠️

1. 浏览器能力：需要 Insertable Streams（createEncodedStreams）或RTCRtpScriptTransform支持，SDK 通过 utils.ts 自动检测；不支持时接收端会跳过剥离并在日志中告警。
2. 实验性 API：Frame Metadata 在源码中整体标注@experimental（见 extension.ts），生产使用前建议关注版本更新；旧版packetTrailer命名已废弃，SDK 仍兼容。
3. Trailer 写入失败不丢帧：Worker 中的编码/解码转换均做了容错——任何单帧处理失败都会直接透传，保证视频流永不中断（frameMetadata.worker.ts）。
4. 仅作用于视频轨道：接收端只对kind === 'video'的轨道安装剥离流水线（FrameMetadataManager.ts）。

七、源码导航：Frame Metadata 相关文件一览 📂

小结

Frame Metadata 是 livekit-client 中一个"小而精"的机制：发布端两行配置，订阅端一个事件监听，就能让AI 推理结果、时间戳、帧编号与视频画面逐帧对齐地流转。它的核心价值在于——元数据不再是"视频旁边的一条消息"，而是"长在视频帧上的行李牌"，从传输层就保证了画面与数据的同步。对于任何需要"每帧都有数据"的 AI 实时视频应用，这都是一条值得优先评估的技术路线。