怎么在HTML中利用Insertable Streams对WebRTC媒体流进行实时帧级处理

必须开启 encodedInsertableStreams: true，否则 createEncodedStreams() 报错或返回 undefined；该选项是 RTCPeerConnection 初始化时的硬性开关，影响新 sender/receiver，不兼容 Safari，需 HTTPS 环境。

必须开启 encodedInsertableStreams: true，否则 createEncodedStreams() 会直接报错或返回 undefined —— 这是绝大多数人卡住的第一步。

RTCPeerConnection 初始化时必须显式启用 encodedInsertableStreams

Chrome 从 M82 开始支持该特性，但默认关闭。哪怕你后续调用 createEncodedStreams()，只要初始化时没声明，整个链路就不可用。

• encodedInsertableStreams: true 是硬性开关，不是可选优化项
• 它只影响新创建的 RTCRtpSender 和 RTCRtpReceiver，已存在的 sender/receiver 不会自动获得能力
• 不兼容 Safari（截至 2026 年 5 月仍无实现），Firefox 仅部分支持（需手动开启 media.webrtc.internals.insertable-streams.enabled）
• 若在非安全上下文（http://）中使用，API 会静默失效，控制台无提示 —— 务必用 https:// 或 localhost

sender.createEncodedStreams() 返回的是 ReadableStream 和 WritableStream

不是 MediaStream，也不是普通的 TransformStream；它是专为编码帧设计的二进制流对，每个 chunk 是一个 RTCEncodedVideoFrame 或 RTCEncodedAudioFrame 实例，含 data、timestamp、type（key/frame）、codec 等字段。

• chunk.data 是 ArrayBuffer，不能直接当 Uint8Array 用，需显式构造：new Uint8Array(chunk.data)
• H.264 关键帧以 00 00 00 01（BE）开头，AV1 帧有 obu_type 字段，处理前务必先 switch(chunk.codec) 分支
• 修改 chunk.data 后必须重新赋值给 chunk.data，仅改写 ArrayBuffer 内容无效
• 不要在主线程做耗时操作（如 AES 加密/解密），应移交 Worker + RTCRtpScriptTransform，否则导致帧堆积、卡顿

receiver.createEncodedStreams() 的坑：RTP payload 解包需手动处理

接收端拿到的 chunk.data 是原始 RTP 负载（payload），不含 RTP header。但 WebRTC 在打包时可能启用了 FEC、NACK 或分片（如 VP8 partitioning），这意味着单个 chunk 可能只是完整帧的一部分。

立即学习“前端免费学习笔记（深入）”；

• 无法假设每个 chunk 对应一帧 —— 尤其在丢包重传场景下，同一帧可能被多次送达
• 需依赖 chunk.timestamp 和 chunk.dependency（若存在）做帧重组，不能只靠序号
• Chrome 当前对 RTCEncodedVideoFrame.dependency 支持不稳定，建议用 chunk.type === 'key' + 时间戳窗口做粗略帧边界判断
• 若启用 Simulcast，不同 spatial layer 的帧会走不同 RTCRtpReceiver，createEncodedStreams() 需分别调用

TransformStream 的 transform 函数里不能 await 异步操作

TransformStream 的 transform 是同步函数，返回 Promise 会导致流挂起或崩溃。所有异步逻辑（如调用 SubtleCrypto.encrypt()）必须提前在 Worker 中完成，并通过 postMessage 同步传递结果。

• 错误写法：async transform(chunk, controller) { const encrypted = await crypto.subtle.encrypt(...); controller.enqueue({...chunk, data: encrypted}); }
• 正确路径：主线程创建 RTCRtpScriptTransform，Worker 中用 onmessage 接收 chunk，执行加密后 postMessage({id: chunk.id, data: encrypted})，主线程用 Map 缓存响应并同步填充
• 注意 chunk.id 不是稳定标识，Chrome 中实际为内部指针地址，应改用 chunk.timestamp + chunk.type 组合做关联
• 频繁创建 TransformStream 实例会导致内存泄漏，建议复用单个实例，或在 sender.replaceTrack() 后显式 controller.terminate()

最易被忽略的一点：Insertable Streams 处理的是编码后帧，不是原始像素。任何想在帧上画文字、加滤镜、裁剪画面的操作，都必须退回到 canvas.captureStream() + MediaStreamTrack 方案 —— Insertable Streams 不提供原始图像访问能力。