基本用法

本文档提供了使用 ffmpeg.wasm 在 Web 应用程序中执行常见多媒体处理操作的逐步指南。它侧重于核心生命周期：实例化、加载、文件管理和执行。

核心概念

ffmpeg.wasm 的工作流程遵循特定的生命周期来管理 WebAssembly 环境及其关联的虚拟文件系统 (VFS)。

生命周期流程

安装

通过您首选的包管理器安装核心库和工具包：

# npm
npm install @ffmpeg/ffmpeg @ffmpeg/util
 
# yarn
yarn add @ffmpeg/ffmpeg @ffmpeg/util

• @ffmpeg/ffmpeg: 主要的 JavaScript 包装器和 API。
• @ffmpeg/util: 包含 fetchFile 和 toBlobURL 等必要辅助函数。

1. 实例化与加载

首先，创建 FFmpeg 类的实例。在执行任何命令之前，必须调用 .load() 来获取并初始化 WebAssembly 二进制文件。

基础 URL 选择

当从 JSDelivr 等 CDN 加载时，URL 格式取决于您的构建工具。对于 Vite 或其他基于 ESM 的打包器，请使用 /esm 分发版。对于其他情况，请使用 /umd。

加载实现

import { FFmpeg } from '@ffmpeg/ffmpeg';
import { toBlobURL } from '@ffmpeg/util';
 
const ffmpeg = new FFmpeg();
 
const load = async () => {
 const baseURL = 'https://cdn.jsdelivr.net/npm/@ffmpeg/core@0.12.10/dist/esm';
 await ffmpeg.load({
 coreURL: await toBlobURL(`${baseURL}/ffmpeg-core.js`, 'text/javascript'),
 wasmURL: await toBlobURL(`${baseURL}/ffmpeg-core.wasm`, 'application/wasm'),
 // workerURL 仅在多线程 (@ffmpeg/core-mt) 时需要
 workerURL: await toBlobURL(`${baseURL}/ffmpeg-core.worker.js`, 'text/javascript'),
 });
};

2. 事件监听器

FFmpeg 操作是异步的，可能需要较长时间。请使用事件监听器来跟踪内部状态和日志。

• log: 捕获来自 FFmpeg 进程的标准输出/错误。
• progress: (实验性) 提供 0 到 1 之间的完成比例。

ffmpeg.on('log', ({ message }) => {
 console.log(message);
});
 
ffmpeg.on('progress', ({ progress, time }) => {
 console.log(`完成度：${progress * 100}%, 时间：${time}`);
});

3. 转码模式

最常见的用例是将文件从一种格式转换为另一种格式。这涉及将数据移动到 WebAssembly 内存空间 (VFS)，运行命令，然后将结果拉取出来。

数据流图

实现示例

import { fetchFile } from '@ffmpeg/util';
 
const transcode = async () => {
 // 1. 写入文件到 VFS
 await ffmpeg.writeFile('input.webm', await fetchFile('https://.../video.webm'));
 
 // 2. 执行命令
 // 语法：.exec(args[], timeoutMS?)
 await ffmpeg.exec(['-i', 'input.webm', 'output.mp4']);
 
 // 3. 从 VFS 读取结果
 const data = await ffmpeg.readFile('output.mp4');
 
 // 4. 使用结果（例如，为 <video> 标签创建 Blob URL）
 const url = URL.createObjectURL(new Blob([data.buffer], { type: 'video/mp4' }));
};

框架集成

FFmpeg 实例通常应在渲染之间持久化，以避免昂贵的 WASM 核心重新加载。

React

使用 useRef 维护 FFmpeg 实例，并使用 useState 跟踪加载状态。

Vue

在 setup() 函数中使用 ref 或 shallowRef。

Angular

在组件中将 FFmpeg 实例定义为类属性。

Svelte

在 <script> 块内声明实例。

核心方法摘要