webcodecs api 无法被 c++ wasm 直接调用，必须通过 js 胶水层桥接；c++ 仅负责业务逻辑，js 承担解码桥梁与时间戳对齐，硬解由浏览器底层实现。
WebCodecs API 不能直接在 C++ WASM 中调用
浏览器的 WebCodecs 是纯 JavaScript 接口，运行在 JS 主线程或 Worker 中，WASM 模块（哪怕用 C++ 编译）无法绕过 JS 环境直接访问它。你写的 C++ 代码在 WASM 里跑着，和 VideoDecoder、EncodedVideoChunk 这些对象完全不在一个内存空间、也不共享事件循环。
常见错误现象：ReferenceError: VideoDecoder is not defined 或编译通过但运行时报 TypeError: Failed to construct 'VideoDecoder': Not supported in this context —— 实际上是 WASM 没有全局 JS 对象访问权，或者没正确通过 JS 胶水层暴露。
- 必须通过 Emscripten 的
emscripten_bind或EM_JS宏把 JS 的VideoDecoder实例、解码回调、queue方法桥接到 C++ - 所有输入输出都得走 JS：C++ 把
uint8_t*视频帧数据传给 JS，JS 封装成EncodedVideoChunk再喂给VideoDecoder.decode() - 解码后的
VideoFrame也不能直接进 C++；JS 需调用copyTo()或createImageBitmap()，再把像素数据（如RGBA）以Uint8Array形式传回 WASM 内存
硬解是否生效取决于浏览器 + 设备，不是 C++ 能控制的
WebCodecs 的 VideoDecoder 构造时传 {hardwareAccelerated: true} 只是 hint，浏览器可忽略。Chrome 在 Windows/macOS/Linux 上对 H.264/VP9/AV1 的硬解支持较稳，但 Safari 目前（iOS 17 / macOS 14）仍不支持 VideoDecoder，直接抛 NotSupportedError。
使用场景中容易被忽略的一点：即使启用了硬解，如果 JS 层没及时 copyTo() 或没释放 VideoFrame，GPU 资源会被占住，后续 decode 调用会卡顿甚至失败。
- 检查是否硬解生效：监听
VideoDecoder.state，解码中为"decoding"，完成后为"closed"；更可靠的是看 Chrome 的chrome://gpu页面里 “Video Decode” 是否为Hardware accelerated - 不要在 C++ 里假设解码一定快——软解 fallback 必须存在，比如检测到
NotSupportedError或 decode 回调延迟 > 200ms 时切到 libvpx 或 dav1d 的 WASM 版本 -
VideoDecoder不支持自定义 color space 转换，YUV→RGB 必须由 JS 层用VideoFrame.copyTo()或 Canvas 2D 完成，C++ 拿到的只能是 RGBA
WASM 内存与 JS TypedArray 传递视频帧最安全的方式
直接用 EM_ASM 把整个 Uint8Array 复制进 WASM 内存效率低且易越界。正确做法是让 JS 持有 WebAssembly.Memory 的 buffer 视图，C++ 用 uint8_t* 指针写入，JS 用 new Uint8Array(wasmMemory.buffer, offset, length) 读取。
典型坑：Emscripten 默认启用 -s SINGLE_FILE=1 和 -s ALLOW_MEMORY_GROWTH=1，但 WebCodecs 解码输出的帧尺寸可能动态变化（比如分辨率切换），若 WASM 内存没预留足够空间或没处理 grow 后指针失效，就会读到脏数据或 crash。
- C++ 侧申请内存用
malloc()并导出指针（如get_frame_buffer_ptr()），JS 层通过Module.HEAPU8.subarray(ptr, ptr + size)访问，避免拷贝 - JS 解码回调中拿到
VideoFrame后，优先调frame.copyTo(HEAPU8, {offset: ptr})，而不是先转ImageBitmap再读 canvas —— 后者多一次 GPU→CPU 同步，延迟高 - 务必在 JS 中
frame.close()，否则 Chrome 会累积未释放帧，触发DOMException: Failed to execute 'decode' on 'VideoDecoder': Too many frames queued
没有“C++ 硬解”这回事，只有“C++ 配合 WebCodecs 做好胶水”
所谓“C++ WASM 视频硬解”，本质是 C++ 做业务逻辑（帧调度、PTS 同步、渲染队列管理），JS 做桥梁（创建 decoder、喂 chunk、拉帧、传像素），浏览器底层做硬解。C++ 本身不碰 GPU，也不调用任何 OS 级解码器（如 Media Foundation、VideoToolbox）。
最容易被忽略的复杂点：时间戳对齐。WASM 里拿不到高精度媒体时钟，VideoDecoder 输出的 VideoFrame.timestamp 是基于 performance.now() 的相对值，而你的播放器逻辑可能依赖 AudioContext.currentTime 或 requestVideoFrameCallback，三者不同步就会音画不同步。
这事没法靠加几行 C++ 解决，得在 JS 层建统一时钟代理，再把校准后的时间戳传给 WASM。硬解只是链路一环，真正卡住的地方永远在衔接处。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
