一次 RTC 摄像头镜像推流色差问题的排查与修复

更新: 7/28/2026 字数: 0 字 时长: 0 分钟

从"本地预览红得发艳、远端回显却发灰"这一直观现象出发,一路挖到媒体链路的色彩空间不一致与浏览器对 canvas 帧的强制归一。本文记录完整的排查、取舍与落地。

一、问题背景

在前端实时文生流的体验页中,摄像头采集画面会同时出现在两个地方:

• 本地 PiP:前端左下角的本地摄像头预览,用户直接看到的画面。
• 远端主画面:经过 RTC 推流、服务端处理后返回的远端回显流。

直观表现是:左下角本地预览里的红色明显更鲜艳,而主画面远端回显里的红色没那么饱和。两者本应展示同一个输入源,这种色差会让用户误以为服务端生成或 RTC 回传画面"变灰""失真",干扰对生成效果的判断。

二、关键线索:首帧色彩空间不一致

从日志看,原始摄像头首帧和远端回显首帧的色彩空间根本不是一回事:

摄像头首帧信息:
format: NV12
colorSpace: { primaries: "bt709", transfer: "bt709", matrix: "bt709", fullRange: false }

回显流首帧信息:
format: NV12
colorSpace: { primaries: "smpte170m", transfer: "bt709", matrix: "smpte170m", fullRange: false }

这说明问题不是 CSS 样式或 video 标签显示差异,而是本地摄像头链路和远端回显链路用了不同的色彩矩阵:摄像头输入是 BT.709,远端回显流是 BT.601(smpte170m)。BT.709 与 BT.601 使用不同的 YUV↔RGB 转换矩阵,同一份 YUV 数据用不同矩阵解码,红/绿的饱和度就会出现肉眼可见的差异。

同时有一条硬性业务约束:本地预览必须镜像,RTC 推出去的流也必须镜像。不能只在本地 video 上用 CSS scaleX(-1) 糊弄——推流轨道本身就得是镜像后的画面。

三、排查与思考:根因分两层

当前的摄像头镜像推流路径是:

getUserMedia 原始摄像头轨道
  → MediaStreamTrackProcessor 读取 VideoFrame
  → canvas 做水平镜像
  → VideoFrame / MediaStreamTrackGenerator 生成新视频轨道
  → 同一条轨道同时用于本地 PiP 和 RTC setExternalVideoTrack

这个设计本身是对的:本地展示和 RTC 推流共用同一条处理后的镜像轨道,能保证"本地看到什么,推流就是什么"。

但日志暴露了更深的问题。我们尝试给 VideoFrame(canvas, { colorSpace }) 传入 smpte170m 元数据后,镜像后推流首帧仍然是:

镜像后推流首帧信息:
format: BGRA
colorSpace: { primaries: "bt709", transfer: "iec61966-2-1", matrix: "rgb", fullRange: true }

Chrome 对 canvas 源创建出来的 VideoFrame 会强制归一成 BGRA / RGB / fullRange=true。即使传了 colorSpace,也无法把它变成 NV12 / smpte170m / fullRange=false。

于是根因拆成两层:

• 第一层 · 视觉问题:本地镜像轨道没有按远端回显的 BT.601 观感做转换,所以红色更鲜艳。
• 第二层 · 元数据问题:用 canvas 直接创建 VideoFrame 时,浏览器不保留想要的 NV12 / smpte170m 格式和色彩空间元数据。

只修第一层,视觉可能接近了,但首帧日志仍是 BGRA / rgb,无法证明链路和远端回显对齐。要同时解决两层,就不能再依赖 VideoFrame(canvas),而要显式构造 NV12 buffer,再用 VideoFrame(buffer, init) 创建帧。

四、解决思路:把色彩转换放进镜像帧生成处

最终 WebCodecs 主路径改成:

原始摄像头 VideoFrame
  → canvas 只负责水平镜像
  → 从 canvas 读取 RGBA 像素
  → 按 BT.709 → BT.601 的观感转换
  → 直接打包成 BT.601 limited-range NV12 buffer
  → new VideoFrame(nv12, {
       format: "NV12", codedWidth, codedHeight,
       colorSpace: { primaries:"smpte170m", transfer:"bt709", matrix:"smpte170m", fullRange:false }
     })
  → MediaStreamTrackGenerator
  → 本地 PiP + RTC 推流共用该轨道

这样处理后主路径的特点:

• 本地展示与 RTC 推流仍共用同一条镜像轨道,不会出现本地和推流内容不一致。
• 色彩观感在生成镜像轨道时就转换到 BT.601,贴近远端回显流。
• 输出帧不再是浏览器默认的 BGRA/rgb,而是显式创建的 NV12/smpte170m,首帧探测更容易和远端回显对齐。
• 对不支持 WebCodecs buffer-source VideoFrame 的浏览器,保留 canvas fallback。fallback 无法保证首帧元数据变成 NV12/smpte170m(受浏览器限制),但会继续做像素层面的 BT.709 → BT.601 转换,保证视觉尽量一致。

五、方案取舍

评估过几个更激进的方案,最终都没采用:

方案	优点	未采用原因
WebAssembly	优化逐帧像素转换性能	额外构建/加载/初始化链路,对一个集中在单文件采集管线的修复引入成本偏高,增加排查与发布风险
WebGL shader	更快做矩阵转换	最终仍需 CPU 侧 NV12 buffer,要做 GPU readback;GPU→CPU 同步读回本身可能成瓶颈,还引入纹理/FBO/上下文恢复/资源释放等复杂度
只改 SDK 编码端元数据	理论最轻	当前没有已验证的 Volc RTC Web SDK 接口能对外部视频轨道设置 matrix/primaries/fullRange;依赖不可观测、不可验证的 SDK 契约风险更高

最终采用更可控的 JS 优化方案:用 8-bit 查表减少每帧浮点乘法。模块初始化时预计算颜色转换表,运行时主要做数组读取、加法和写 Uint8Array。不引入新依赖、不改构建链路,同时满足对色彩空间和首帧信息的验证要求。

六、方案执行

改动集中在 src/pages/liuguang/hooks/VolcEngineRTC.ts。

定义目标色彩空间:

const BT601_VIDEO_COLOR_SPACE = {
  primaries: 'smpte170m',
  transfer: 'bt709',
  matrix: 'smpte170m',
  fullRange: false,
}

主路径:每帧先进 canvas 做水平镜像:

ctx.translate(canvas.width, 0)
ctx.scale(-1, 1)
ctx.drawImage(frame, 0, 0, canvas.width, canvas.height)

随后不再 new VideoFrame(canvas),改调 createBt601Nv12Frame:

mirroredFrame = this.createBt601Nv12Frame(
  ctx,
  canvas.width,
  canvas.height,
  frame.timestamp,
  frame.duration,
)

createBt601Nv12Frame 做两件事:

1. 第一遍写 Y 平面:把 RGBA 像素转为 BT.601 limited-range luma。
2. 第二遍写 UV 平面:按 NV12 的 2×2 采样规则,对块内 RGB 求平均,再写交错的 U/V 数据。

最后从显式 buffer 创建 VideoFrame:

new VideoFrame(nv12, {
  format: 'NV12',
  codedWidth,
  codedHeight,
  colorSpace: BT601_VIDEO_COLOR_SPACE,
  timestamp,
})

生成的镜像帧写入 MediaStreamTrackGenerator,本地 PiP 和 RTC 推流共用这条 track。

保留 fallback:如果 VideoFrame(nv12, init) 在某浏览器版本不可用,退回 VideoFrame(canvas),避免因色彩空间增强导致摄像头推流直接不可用。

七、验证结果

修复后,首帧日志应从:

镜像后推流首帧信息:
format: "BGRA"
colorSpace: { primaries: "bt709", matrix: "rgb", fullRange: true }

变成接近:

镜像后推流首帧信息:
format: "NV12"
colorSpace: { primaries: "smpte170m", transfer: "bt709", matrix: "smpte170m", fullRange: false }

这才说明镜像后推流轨道不只是视觉上做了转换,而是在帧格式和色彩空间元数据上也向远端回显流对齐。

八、实战踩坑清单

1. canvas 会"吃掉"你的 YUV 色彩空间 只要画面过一遍 canvas,再 new VideoFrame(canvas),输出就被强制归一成 BGRA/rgb/fullRange=true。传 colorSpace 参数也拦不住。要保留 NV12/smpte170m,必须自己构造 buffer 走 VideoFrame(buffer, init)。

2. BT.709 vs BT.601 不是玄学,是矩阵差异 两者 YUV↔RGB 系数不同,同一份数据解码出来饱和度就不同。排查色差先看 matrix/primaries,别一上来怀疑亮度或 gamma。

3. fullRange 也是色差来源fullRange=true(0–255)与 false(limited,16–235)的映射范围不同,忽略它会导致对比度/黑白电平偏差。本方案统一按 limited-range 打包 NV12。

4. NV12 的 UV 是 2×2 下采样 + 交错存储 写 UV 平面时要对 2×2 块的 RGB 求平均,再交错写 U/V。采样规则写错会出现偏色或棋盘格瑕疵。

5. 时间戳 / duration 要透传 构造帧时继承原始 frame.timestamp 和 frame.duration,否则输出轨道时序错乱。

6. 务必做特性检测 + fallback buffer-source VideoFrame(NV12) 兼容性有限,不能默认可用。fallback 保证"色彩空间增强失败也不至于推流直接挂掉"。

7. 本地预览别再叠 CSS 镜像 推流轨道已是镜像的,本地 PiP 渲染这条轨道即已镜像,再加 scaleX(-1) 会翻转两次。

九、总结

这次问题表面是"本地摄像头太鲜艳、远端回显没那么鲜艳",真正的根因在媒体链路:摄像头输入是 BT.709,远端回显是 BT.601;而本地镜像推流路径经过 canvas 后,又被浏览器归一成了 BGRA/rgb/fullRange。只在 UI 层调样式,或只给 VideoFrame(canvas) 传 colorSpace,都无法真正让本地展示、推流内容和远端回显对齐。

最终修复策略是把色彩转换放在镜像轨道生成处,并显式输出 NV12/smpte170m 的 WebCodecs 帧。本地 PiP 和 RTC 推流继续共享同一条镜像轨道,同时在视觉观感和首帧元数据上都更接近远端回显流。

经验沉淀:视频链路里的色差不要只看最终画面,要看每一段 track 的 format、matrix、primaries、fullRange。尤其 canvas 参与媒体处理时,它很容易把原始 YUV 色彩空间转换成浏览器自己的 RGB 表达。业务若要求本地预览、推流和远端回显严格一致,就必须在帧生成阶段显式控制格式和色彩空间,而不是依赖浏览器默认行为。