structuredClone() 无法拷贝 VideoFrame，因其是绑定 GPU 内存的非纯数据对象，不支持结构化克隆；需提取可转移数据（如 ArrayBuffer 或 ImageBitmap）及元信息，在目标上下文重建。
structuredClone() 无法直接拷贝 VideoFrame 对象，因为它不属于 structured clone algorithm 支持的类型列表。尝试直接克隆会抛出 DataCloneError。要处理含 VideoFrame 的多媒体对象，需手动分离、传输与重建。
为什么 VideoFrame 不能被 structuredClone() 拷贝
VideoFrame 是一个底层媒体资源句柄，内部绑定 GPU 内存或共享缓冲区，具有生命周期管理、所有权语义和跨线程限制。它不是纯数据对象，也不实现 Transferable 接口（如 ArrayBuffer 或 MessagePort 那样），因此无法被结构化克隆机制序列化/反序列化。
常见错误示例：
Uncaught DataCloneError: Failed to execute 'structuredClone' on 'Window': TypeError: VideoFrame is not a supported type for cloning.替代方案：用 transferable 数据 + 元信息重建 VideoFrame
核心思路是：不拷贝 VideoFrame 本身，而是提取其可转移的原始数据（如 copyTo() 到 ArrayBuffer 或使用 transferToImageBitmap()），连同关键元信息（时间戳、分辨率、色彩空间、旋转角度等）一并传输，再在目标上下文重建新 VideoFrame。
- 若需像素级精确拷贝（如图像处理）：调用
frame.copyTo(buffer)将 YUV/RGBA 数据写入预分配的ArrayBuffer，该 buffer 可通过structuredClone()（配合transfer选项）安全传递 - 若用于渲染（如 Canvas/WebGL）：优先用
frame.transferToImageBitmap()→ 得到ImageBitmap（支持 transfer），再传给 Worker 或其他上下文 - 务必同步传递元信息：
frame.timestamp、frame.codedWidth/frame.codedHeight、frame.displayWidth/frame.displayHeight、frame.orientation、frame.format（如"I420"、"RGBA"）
在 Worker 中重建 VideoFrame 的典型流程
假设主线程捕获了一个 VideoFrame，需在 Worker 中复现：
- 主线程：提取数据 + 元信息 → 封装为可转移对象
const buffer = new ArrayBuffer(frame.allocationSize); // 根据 format 和尺寸预估
frame.copyTo(new Uint8Array(buffer)); // 同步拷贝
const frameData = {
timestamp: frame.timestamp,
codedWidth: frame.codedWidth,
codedHeight: frame.codedHeight,
displayWidth: frame.displayWidth,
displayHeight: frame.displayHeight,
format: frame.format,
// 其他必要字段...
};
// 使用 transfer 选项传递 buffer，避免拷贝
worker.postMessage({ type: 'video-frame', data: frameData, buffer }, [buffer]);
- Worker 端：用接收到的数据新建
VideoFrame
onmessage = async (e) => {
const { data, buffer } = e.data;
const videoFrame = new VideoFrame(buffer, {
timestamp: data.timestamp,
codedWidth: data.codedWidth,
codedHeight: data.codedHeight,
displayWidth: data.displayWidth,
displayHeight: data.displayHeight,
format: data.format,
});
// ✅ 成功重建，可进一步处理或渲染
};
注意事项与性能提示
直接操作 VideoFrame 原始数据对性能敏感，需注意：
-
copyTo()是同步且可能阻塞的操作，建议在 Worker 中执行，避免卡住主线程 - 不同
format（如"I420"vs"RGBA"）影响 buffer 大小计算方式，务必参考 WebCodecs 规范中 allocationSize 定义 - 若仅需“引用传递”而非“深拷贝”，考虑使用
postMessage(..., [frame])——VideoFrame自身支持 transfer（Chrome 117+），但传输后原帧自动关闭，不可再用 - 暂不支持跨
Document或跨Origin传输VideoFrame；需确保同源且兼容环境（目前主要支持 Chrome / Edge，Firefox 尚未实现 WebCodecs 完整版）
