API 参考

本文档提供了 ffmpeg.wasm JavaScript API 的全面参考，该 API 允许在 Web 浏览器和 Node.js 环境中使用 WebAssembly 运行 FFmpeg 命令。有关安装和基本使用的信息，请参阅 使用指南。

核心架构

ffmpeg.wasm API 由几个关键组件组成，它们协同工作以在浏览器环境中提供 FFmpeg 功能。

API 参考

FFmpeg 类

FFmpeg 类是与 FFmpeg WebAssembly 模块交互的主要入口点。它管理运行 WebAssembly 代码的 web worker 之间的通信。有关详细的方法文档，请参阅 FFmpeg 类。

构造函数

const ffmpeg = new FFmpeg();

创建一个新的 FFmpeg 实例。直到调用 load() 之前不会立即进行初始化。

核心方法

load(config?, options?)

在 web worker 中加载 ffmpeg-core。必须首先调用此方法，然后才能执行其他操作。

参数：

  • config: 包含 coreURL、wasmURL、workerURL 和 classWorkerURL 的 FFMessageLoadConfig 对象。
  • options: 包含 AbortSignal 的 FFMessageOptions。

返回：

  • Promise<IsFirst>: 如果首次加载 ffmpeg core，则解析为 true。

exec(args, timeout?, options?)

执行带有指定参数的 FFmpeg 命令。

参数：

  • args: 命令行参数数组。
  • timeout: 停止执行前等待的毫秒数（默认值：-1）。
  • options: 包含 AbortSignal 的 FFMessageOptions。

返回：

  • Promise<number>: 如果成功则解析为 0，出错或超时则解析为非零值。

ffprobe(args, timeout?, options?)

执行 FFprobe 命令以提取元数据。

返回：

  • Promise<number>: ffprobe 进程的退出码。

terminate()

终止所有正在进行的 API 调用和 web worker。

事件处理

FFmpeg 类实现了自定义的事件发射器，用于日志和进度跟踪。

  • on(event, callback): 监听 "log" 或 "progress" 事件。
  • off(event, callback): 取消订阅事件。

文件系统操作

FFmpeg 类提供了与 Emscripten 提供的虚拟文件系统 (VFS) 交互的方法。有关 WORKERFS 等后端类型的详细信息，请参阅 配置选项。

API 参考

文件管理

  • writeFile(path, data): 将 Uint8Array 或 string 写入 VFS。
  • readFile(path, encoding?): 从 VFS 读取数据。支持 "binary"（默认）或 "utf8"。
  • deleteFile(path): 删除文件。
  • rename(oldPath, newPath): 重命名文件或目录。

目录操作

  • createDir(path): 创建目录。
  • listDir(path): 返回 FSNode 对象数组（名称和 isDir 标志）。
  • deleteDir(path): 删除空目录。

文件系统挂载

  • mount(fsType, options, mountPoint): 挂载专用文件系统（如 WORKERFS），以便在不复制的情况下访问大文件。
  • unmount(mountPoint): 卸载文件系统。

工具函数

@ffmpeg/util 包提供辅助函数以简化数据处理。有关详细信息，请参阅 工具函数。

  • fetchFile(input): 将各种输入（URL、File、Blob）转换为 Uint8Array。
  • toBlobURL(url, mimeType): 解决 CORS 和脚本加载问题的变通方法。
  • downloadWithProgress(url, cb): 下载资源并提供进度更新。

数据类型

该 API 依赖于 @ffmpeg/types 中定义的类型和内部接口。完整列表请参阅 配置选项。

类型描述
FFMessageLoadConfig用于加载 WASM 和 Worker 资产的配置。
FFFSType支持的文件系统枚举（MEMFS、NODEFS、WORKERFS 等）。
LogEvent包含 type（stdout/stderr）和 message 的对象。
ProgressEvent包含 progress（0-1）和 time（毫秒）的对象。
FileDataUint8Array 或 string。

多线程与性能

ffmpeg.wasm 通过 @ffmpeg/core-mt 包支持多线程。

  • 线程支持：需要 SharedArrayBuffer 以及特定的 COOP/COEP 响应头。
  • Worker 配置：对于多线程构建版本，必须在 load() 配置中提供 workerURL。
  • 资产加载：在多线程环境中，worker.ts 使用 mainScriptUrlOrBlob 的哈希技巧来定位 WASM 和 Worker 文件。