FFmpeg 类

FFmpeg 类是与 ffmpeg.wasm 库交互的主要接口。它提供了一个基于 Promise 的简洁 API，用于在浏览器环境中访问 FFmpeg 功能，并通过 Web Worker 系统处理与 WebAssembly FFmpeg 核心通信的所有复杂性。

概述

FFmpeg 类作为一个抽象层，使 JavaScript 应用程序能够在浏览器中利用 FFmpeg 的多媒体处理能力。该类是 @ffmpeg/ffmpeg 包的一部分，位于核心 WebAssembly 模块之上。

FFmpeg 类

类架构

FFmpeg 类使用消息传递架构与运行在独立 Web Worker 线程中的 FFmpeg 核心进行通信。这种设计可防止在进行密集型视频处理操作时阻塞主 UI 线程。

FFmpeg 类

内部结构

FFmpeg 类维护几个私有属性来管理其状态并与 Web Worker 通信：

  • #worker：Web Worker 实例的引用
  • #resolves 和 #rejects：待处理 Promise 解析的回调映射
  • #logEventCallbacks 和 #progressEventCallbacks：用于事件处理的回调函数数组
  • loaded：公共布尔标志，指示是否已成功加载 FFmpeg 核心

FFMessageType 协议

FFmpeg 类与 worker.ts 之间的通信由 FFMessageType 枚举控制。该协议确保双方都能理解消息的意图（例如 LOAD、EXEC、WRITE_FILE）。

FFmpeg 类

初始化和加载

构造函数

FFmpeg 类构造函数初始化内部状态。注意 ffmpeg.wasm 不支持 Node.js；对于 Node 环境提供了一个空实现，在实例化时会抛出错误。

加载 FFmpeg 核心

load() 方法在 Web Worker 内初始化 WebAssembly FFmpeg 核心。必须在调用任何其他方法之前调用此方法。

await ffmpeg.load({
 coreURL: 'https://cdn.jsdelivr.net/npm/@ffmpeg/core@0.12.0/dist/umd/ffmpeg-core.js'
});

load() 方法接受 FFMessageLoadConfig：

参数类型描述
coreURLstringffmpeg-core.js 文件的 URL。
wasmURLstringffmpeg-core.wasm 文件的 URL。
workerURLstringffmpeg-core.worker.js 文件的 URL（用于多线程）。
classWorkerURLstring@ffmpeg/ffmpeg 提供的 worker.js 文件的 URL。

核心功能

执行命令 (exec 和 ffprobe)

exec() 方法使用指定的参数运行 ffmpeg 二进制文件。为了避免常见的 I/O 问题，默认情况下会在核心中将 ["-nostdin", "-y"] 预添加到参数中。

ffprobe() 方法用于分析媒体文件。

参数类型描述
argsstring[]命令行参数。
timeoutnumber停止执行前的毫秒数（默认为 -1）。
signalAbortSignal允许通过 AbortController 取消操作。

虚拟文件系统 (VFS) 方法

FFmpeg 类通过消息传递向 worker.ts 暴露 Emscripten FS API。

方法Emscripten 映射用途
writeFile(path, data)FS.writeFile将数据写入 VFS
readFile(path, encoding)FS.readFile从 VFS 读取数据
deleteFile(path)FS.unlink删除文件
rename(old, new)FS.rename重命名节点
createDir(path)FS.mkdir创建目录
listDir(path)FS.readdir + FS.stat列出目录内容
deleteDir(path)FS.rmdir删除空目录

文件系统挂载

mount() 方法允许附加外部存储后端，如 WORKERFS（用于高效访问大型 File 或 Blob 对象而无需复制）。

await ffmpeg.mount(FFFSType.WORKERFS, {
 files: [fileObject]
}, '/mnt');

事件处理

该 FFmpeg 类通过 on() 和 off() 方法扩展了观察者模式，用于从 worker 流式传输日志和进度信息

  • log: 捕获来自 FFmpeg 的 stdout 和 stderr
  • progress: 提供小数形式的 progress（0 到 1）以及当前 time（以微秒为单位）

内部 Promise 跟踪

该类使用内部的 #resolves 和 #rejects 对象来管理异步操作

  1. 分发: #send() 通过 getMessageID() 生成唯一 ID，将 Promise 的 resolve/reject 存储在映射表中，并调用 postMessage()
  2. 处理: #registerHandlers() 监听 onmessage。当响应到达时，它匹配 id，从映射表中检索回调函数，并解决原始的 Promise

终止

terminate() 方法会立即终止 Web Worker，并使用 ERROR_TERMINATED 拒绝所有待处理的 Promise