用 Mediabunny 在浏览器中预检视频解码能力：OpenMontage Remotion 合成链路的 canDecode 实战

在把一段视频（尤其是来自各家生成式视频服务的远程素材）交给浏览器或 Remotion 渲染器播放之前，先验证"这段视频能否被当前浏览器解码"，是避免黑屏、绿屏、卡死或渲染失败的最廉价防线。OpenMontage 的 remotion-best-practices Agent 技能库中以 can-decode 规则 沉淀了一套基于 Mediabunny 的可直接复制的 canDecode() 实现。阅读本文后，你将掌握该函数从容器解析到音视频轨道逐层解码探测的完整原理，并能在远程 URL、Blob 上传、本地文件三种场景中即取即用，把它无缝接入 OpenMontage 的 Remotion 合成与渲染验证链路。

为什么要在"播放之前"检查解码能力

浏览器能"下载"视频不代表能"播放"视频。视频文件是容器格式（封装轨道）与编码格式（轨道内部压缩算法）两层结构的复合体：一个 MP4 容器里既可能有 H.264 视频轨道 + AAC 音频轨道的"安全组合"，也可能封装了浏览器不支持的编码。解码失败不会发生在网络层，而是发生在播放器尝试初始化解码器的瞬间——这在面向 Remotion 的程序化渲染场景中尤其致命：

• OpenMontage 中 Remotion 是所有最终渲染的默认合成引擎（详见 核心技能 remotion），大量来自外部素材的视频片段会以 <Video> / 远程 URL 形式嵌入 composition，一旦其中某条轨道浏览器（Chromium 渲染器）解不了码，整个渲染或预览就会异常。
• 资产路径层面的问题可以在渲染前由 composition_validator 拦截（缺失文件、音频比画面长等，见 composition_validator.py），但**"文件存在"与"可解码"是两个维度**，后者需要在真实浏览器能力边界内探测。

canDecode() 正是为此设计：在真正发起播放前，用当前运行环境的解码能力去验证素材，返回一个明确的布尔结论。

Mediabunny 在 OpenMontage Remotion 生态中的位置

Mediabunny 是负责媒体容器解析与轨道探测的底层库，canDecode 规则只是该技能库中 Mediabunny 系列能力之一。同目录下还有一批围绕同一 Input + Source 抽象的工具型规则：

• get-video-duration 规则 — 计算视频时长（秒）
• get-audio-duration 规则 — 计算音频时长
• get-video-dimensions 规则 — 读取画面宽高
• extract-frames 规则 — 按时间戳抽帧

在依赖层面，仓库的 remotion-composer/package-lock.json 中可以确认 mediabunny@1.47.0 及 @mediabunny/* 系列子包已随 Remotion 媒体生态（@remotion/media 等要求 mediabunny ^1.0.0）被解析安装；而在 remotion-composer/package.json 中，@remotion/media、@remotion/captions、@remotion/transitions、remotion 均为 ^4.0.484。也就是说，凡是使用 Remotion 媒体能力的工程，Mediabunny 通常已经在依赖树中就绪，规则中的函数可以直接 copy-paste 使用；若独立工程需要显式引入，将其加入 dependencies 即可。

canDecode() 核心实现逐行拆解

规则文件给出的完整实现可以原样复制进任意项目，其核心逻辑是"逐层探测、逐轨验证、任一失败即返回 false"：

import { Input, ALL_FORMATS, UrlSource } from "mediabunny";

export const canDecode = async (src: string) => {
  const input = new Input({
    formats: ALL_FORMATS,
    source: new UrlSource(src, {
      getRetryDelay: () => null,
    }),
  });

  try {
    await input.getFormat();
  } catch {
    return false;
  }

  const videoTrack = await input.getPrimaryVideoTrack();
  if (videoTrack && !(await videoTrack.canDecode())) {
    return false;
  }

  const audioTrack = await input.getPrimaryAudioTrack();
  if (audioTrack && !(await audioTrack.canDecode())) {
    return false;
  }

  return true;
};

逐段理解其设计意图：

1. new Input({ formats, source })：Mediabunny 的统一入口，把"要探测的媒体格式范围"与"媒体数据从哪来"解耦。ALL_FORMATS 表示接受所有受支持的容器类型，不做预筛选。

2. UrlSource(src, { getRetryDelay: () => null })：声明数据源是一个远程 URL。getRetryDelay 返回 null 表示不做重试——这是探测场景的正确选择：解码检查失败就是失败，没必要让探测逻辑因网络抖动反复挂起。若你确实希望保留有限重试，可改成返回固定毫秒数。

3. await input.getFormat()（第一道防线：容器级校验）：解析文件容器结构（如 MP4 的 box 布局、轨道元数据）。这一步如果抛错，说明该 URL 根本不是可解析的媒体文件（如 404 页面、损坏文件、非媒体内容），直接返回 false。这里用 try/catch 将"解析异常"语义归一为"不可解码"。

4. getPrimaryVideoTrack() + videoTrack.canDecode()（第二道防线：视频编码校验）：取出主视频轨道，询问浏览器解码器是否支持其编码参数（编码格式、分辨率、色彩信息等）。注意 videoTrack 可能不存在（纯音频文件），因此先用 if (videoTrack && ...) 做空值保护。

5. getPrimaryAudioTrack() + audioTrack.canDecode()（第三道防线：音频编码校验）：同理验证音频轨道。由于 getFormat() 成功只能证明"容器能解析"，真正决定能否流畅播放的是音视频轨道各自能否被解码器接受，因此这两次 canDecode() 调用才是函数的核心。

6. 返回 true 的条件：容器可解析 且（无视频轨道 或 视频可解码）且（无音频轨道 或 音频可解码）。这一布尔逻辑天然覆盖了纯视频、纯音频、无声视频、完整音视频等混合形态。

在 React / TSX 工程中的基本用法

该函数是纯异步的，可以直接嵌入任意组件、hook 或流程编排代码。规则文件给出了最朴素的使用示例：

const src = "https://remotion.media/video.mp4";
const isDecodable = await canDecode(src);

if (isDecodable) {
  console.log("Video can be decoded");
} else {
  console.log("Video cannot be decoded by this browser");
}

两点实战建议：

• 放到渲染/播放决策之前。在 OpenMontage 场景中，最合理的接入点是把远程视频素材塞进 Remotion composition 之前——只有 canDecode 返回 true 的素材才值得进入 @remotion/media 的 <Video>（其用法见 videos 规则）或被引用为 composition 资源。
• 它会真实消耗网络与解码器资源，属于"按需探测"而非"后台常驻"能力，一般只在素材首次进入流程或渲染前验证阶段调用一次即可，无需对同一 URL 反复探测。

处理 Blob：本地上传与拖拽场景

当素材来自本地（文件上传、拖拽、临时生成）而非网络 URL 时，UrlSource 不再适用，需要换成 BlobSource。规则文件给出了对应的骨架：

import { Input, ALL_FORMATS, BlobSource } from "mediabunny";

export const canDecodeBlob = async (blob: Blob) => {
  const input = new Input({
    formats: ALL_FORMATS,
    source: new BlobSource(blob),
  });

  // Same validation logic as above
};

把 canDecode() 中"容器解析 → 视频轨探测 → 音频轨探测"的完整三段式逻辑照搬到 // Same validation logic as above 注释处即可获得等价的 Blob 版本。三个 Source 类型的选择逻辑很清晰：

Source 类型	适用数据源	典型场景
UrlSource	远程 HTTP(S) 地址	加载外部平台生成的视频 URL
BlobSource	Blob 对象	文件上传、拖拽到浏览器
FileSource	Node.js / Bun 的 File 对象	服务端或 Bun 环境下的本地文件探测

其中 FileSource 与 UrlSource/BlobSource 的区别（跨环境的本地文件探测）在姊妹规则 get-video-duration 规则 中有对应示例：服务端场景构造 Input 时改用 new FileSource(file)，其余探测流程保持一致。这也是 Mediabunny "一次编写、浏览器 / Node.js / Bun 通用"的抽象收益。

把 canDecode 接入 OpenMontage 的渲染验证流程

OpenMontage 对"渲染产物"有严格的验证纪律。从 核心技能 remotion 可以梳理出完整的前置与后置校验骨架，canDecode 恰好能补上其中"运行时解码"这一环：

• 渲染前资产校验：CompositionValidator 会检查 composition 引用的图片/音频文件是否真实存在、旁白是否超过视频长度、音乐是否短于视频、cut 时间是否非法（out ≤ in）——它解决的是"文件有没有、时间轴对不对"。
• 渲染前解码校验（canDecode 的位置）：解决"文件能不能被浏览器解码"。当外部素材以远程 URL 或上传 Blob 形式进入时，先用 canDecode / canDecodeBlob 过滤不可解码素材，能显著减少后续渲染阶段的异常面。
• 渲染后产物校验：OpenMontage 所有 pipeline 的 post-render 验证协议要求用 ffprobe -v quiet -print_format json -show_format -show_streams rendered_video.mp4 检查输出文件的视频流（分辨率、帧率）、音频流是否存在、时长误差是否在 ±5% 内，并配合逐场抽帧目检与 WhisperX 转写核对音频内容。

三者构成"入口素材可解码 → 时间线资产合法 → 出口文件结构正确"的闭环，canDecode 负责的正是第一环中最容易被忽略的浏览器解码兼容性。

边界与工程提醒

把规则落到生产代码前，有几点值得明确：

• 探测不等同于逐帧解码。canDecode() 验证的是解码器对格式与参数的接受度，不保证任意设备上都能达到满帧率流畅播放——后者还受 CPU/GPU 性能与内存约束。它是"能不能播"的必要条件检查，不是"播得顺不顺"的性能评估。
• 结果是环境相关的。函数名与文档反复强调 "by this browser"：同样一段视频，在支持某编码的桌面 Chromium 上可能返回 true，在移动端或精简版浏览器上可能返回 false。因此探测应始终在目标运行环境内执行，不要假定一次结果跨环境通用。
• 远程 URL 需要可访问。UrlSource 的探测需要实际拉取媒体数据，素材源必须允许跨域访问，且网络状态会影响调用耗时——这也是规则将 getRetryDelay 设为 null 的原因之一，避免重试逻辑掩盖真实的可达性/可解码性结论。
• 函数可自由落进任意项目。规则文件明确说明 canDecode 可以 copy-paste 到任何项目，它不依赖 Remotion 组件树，只依赖 mediabunny 包本身，因此既可用于 composition 侧校验，也可用于纯前端上传校验、管理后台素材审片等独立场景。

如果你想继续深入本技能包的其他探测与合成能力，可通读 remotion-best-practices 技能主页 及其下的 extract-frames 规则、assets 规则 等规则文件，它们与 can-decode 一起构成了 OpenMontage 面向 Remotion 的完整媒体处理工具箱。