实用工具函数

@ffmpeg/util 包提供必要的实用工具函数，以辅助使用 ffmpeg.wasm 库。这些工具处理常见任务，如从各种来源获取媒体文件、管理带有进度跟踪的流式下载，以及处理跨域资源以绕过浏览器安全限制。

概述

实用工具函数作为辅助方法，支持 ffmpeg.wasm 的核心功能。它们主要解决基于浏览器的媒体处理中的三个关键挑战：

  1. 加载外部资源，同时通过 Blob URL 避免 CORS（跨域资源共享）问题。
  2. 获取并规范化二进制媒体文件（来自 URL、Base64、File 或 Blob），用于虚拟文件系统。
  3. 跟踪大型资产（如 WebAssembly 核心文件）的下载进度。

代码实体映射

下图将资产加载的自然语言需求映射到 @ffmpeg/util 中的具体代码实体。

实用工具函数

核心实用工具函数

fetchFile(file)

fetchFile 是一个多态函数，它将各种数据源规范化为与 FFmpeg 虚拟文件系统兼容的 Uint8Array

支持的输入类型：

  • URL 字符串：通过 fetch API 获取数据
  • Base64 字符串：检测 data:_data/...;base64 模式并使用 atob 解码
  • URL 对象：标准 Web API URL 对象
  • File / Blob：使用 FileReader.readAsArrayBuffer 读取本地浏览器文件

实现细节：内部 readFromBlobOrFile 辅助函数将异步 FileReader 封装在 Promise 中，以提供现代的 awaitable 接口

downloadWithProgress(url, cb)

此函数使用来自 fetch 响应体的 ReadableStream 执行流式下载

  • 进度跟踪：它读取 Content-Length 标头以确定总大小
  • 块处理：它遍历流读取器，将块累积到数组中并计算 received 字节数
  • 错误恢复：如果流读取器失败或 CORS 阻止访问标头，则回退到标准的 response.arrayBuffer() 调用

toBlobURL(url, mimeType, progress, cb)

一个包装器，获取资源并通过 URL.createObjectURL 将其转换为对象 URL。这通常用于从 CDN 加载 @ffmpeg/core 资产，因为它允许浏览器将脚本/wasm 视为本地起源的 blob，从而绕过某些跨域执行限制。

参数：

  • progress：如果为 true，则使用 downloadWithProgress 代替简单的 fetch

importScript(url)

动态向文档 <head> 注入 <script> 标签。这用于在不需要 ESM 导入的环境中加载 FFmpeg 核心的 UMD 版本。

数据流：资产加载

以下序列图说明了当应用程序使用这些工具初始化 FFmpeg 并处理文件时的内部数据流。

实用工具函数

错误处理

该包定义了特定的错误常量，以处理下载和转换过程中的边缘情况：

错误常量描述文件
ERROR_RESPONSE_BODY_READER当 resp.body.getReader() 返回 null 时抛出（例如，在某些旧版浏览器或严格的安全上下文中）。
ERROR_INCOMPLETED_DOWNLOAD当接收到的块的总和与 Content-Length 标头不匹配时抛出。

在 downloadWithProgress 中，如果在流式阶段发生错误，该函数会捕获错误并尝试使用标准的 arrayBuffer() 方法作为后备来下载文件

包集成

@ffmpeg/util 包是一个独立的依赖项，由主 @ffmpeg/ffmpeg 包和最终用户应用程序使用。

包角色版本
@ffmpeg/util工具提供者0.12.2
@ffmpeg/ffmpeg主 API 消费者0.12.15

迁移说明

在 0.12 之前的版本中，fetchFile 直接从 @ffmpeg/ffmpeg 导出。在 0.12+ 版本中，它被移至 @ffmpeg/util，以减少核心包的大小并允许在非 FFmpeg 上下文中重用工具