@wordpress/upload-media 使用的客户端视频转换包。它目前会在媒体上传期间将动画 GIF 转换为 MP4/WebM。

该包不会被直接使用。上传动画 GIF 时，其帧会使用浏览器原生的 ImageDecoder API 解码；作为内部实现细节，随后会通过 WebCodecs（VideoEncoder）并使用 mediabunny 库重新编码。所有处理都在 Web Worker 中运行，以保持主线程响应。

安装

安装该模块：

npm install @wordpress/video-conversion --save

要求

  • WebCodecs 支持：浏览器必须提供 ImageDecoder 和 VideoEncoder（在基于 Chromium 的浏览器和 Safari 16.4+ 中可用）。
  • Web Workers 支持：浏览器必须支持 Web Workers。
  • TypeScript 支持：TypeScript 使用者需要 TypeScript 5 或更高版本。

API 参考

cancelOperations

取消给定条目 ID 的所有正在进行的操作。

取消操作会在异步边界处生效（等待锁、编码器支持检查、解码器完成、帧与帧之间）。

参数

  • id ItemId：条目 ID。

返回值

  • Promise< boolean >：操作是否已被取消。

convertGifToVideo

将动画 GIF 转换为视频文件（MP4 或 WebM）。

通过浏览器的 ImageDecoder 解码 GIF 帧（遵循每帧延迟），并使用 mediabunny / WebCodecs 重新编码。

接受 Blob 形式的 GIF，这样字节只会在此 worker 中读取一次，而不需要在主线程中生成并传输。直接调用者和测试仍可使用 ArrayBuffer。

参数

  • id ItemId：条目 ID。
  • gifSource ArrayBuffer | Blob：以 Blob/File 或 ArrayBuffer 表示的 GIF 文件。
  • outputMimeType string：输出 MIME 类型（‘video/mp4’ 或 ‘video/webm’）。
  • maxDimensions number：用于降尺度处理的可选最大尺寸。
  • maxTotalPixels number：可选的总解码像素数预算（宽度 × 高度 × 帧数），超出该预算时会以 SIZE_LIMIT_ERROR_PREFIX 拒绝转换。默认值为 DEFAULT_MAX_TOTAL_PIXELS；0 表示禁用。

返回值

  • Promise< ArrayBuffer >：已编码的视频缓冲区。

DEFAULT_MAX_TOTAL_PIXELS

总解码像素数（宽度 × 高度 × 帧数）的默认预算，超出该预算时将不会尝试转换。

转换成本大致与总解码像素数成正比。300 兆像素约等于中端机器在调用方愿意等待的约 30 秒内能够转换的量（例如 1920×1080、约 145 帧的 GIF）；更大的内容很可能也会被放弃，因此不开始转换的成本更低。传入 0 可禁用该检查。

SIZE_LIMIT_ERROR_PREFIX

用于因超出总像素预算而被跳过的 GIF 的消息前缀。

该前缀以 UNSUPPORTED_ERROR_PREFIX 开头，因此现有使用者会将该跳过视为优雅回退（保留已上传的 GIF，不生成配套视频）；更长的前缀可让使用者区分该情况，例如记录警告。与 UNSUPPORTED_ERROR_PREFIX 一样，约定是消息前缀，因为只有消息字符串能跨越 worker 边界保留。

UNSUPPORTED_ERROR_PREFIX

用于“不支持但优雅”的结果（缺少 WebCodecs、编解码器不受支持）的消息前缀。使用者检测到该前缀后，会回退到上传原始 GIF，而不是显示硬性错误。

约定是消息前缀，而不是 Error 类型：worker RPC 层（comctx）只会将抛出的错误序列化为其 message 字符串 —— Error 子类、name 和 stack 无法跨越 worker 边界保留。