使用指南

本综合指南涵盖了在 Web 应用程序中使用 ffmpeg.wasm 的实用方面。它提供了从基本设置到高级模式的常见操作的高级概述。

基本设置

ffmpeg.wasm 操作的生命周期通常遵循 实例化 → 加载 → 写入 → 执行 → 读取 模式。

加载 FFmpeg

首先，您必须加载 WebAssembly 核心。load() 方法接受核心脚本和 WASM 二进制文件的 URL。使用 toBlobURL 是避免从 jsdelivr 等 CDN 获取资源时出现 CORS 问题的标准模式。

有关特定环境导入和 CDN 限制的细节，请参阅 安装。

文件操作与虚拟文件系统

ffmpeg.wasm 基于 虚拟文件系统 (VFS) 运行。在 FFmpeg 处理文件之前，必须将该文件从浏览器的内存/磁盘移动到 WASM 模块的内部文件系统中。

有关转码模式的逐步指南，请参阅 基本用法。

执行命令

通过 exec() 方法执行命令，该方法接收一个字符串数组，其结构与标准 FFmpeg CLI 参数类似。

// 示例：将 webm 转码为 mp4
await ffmpeg.exec(['-i', 'input.webm', 'output.mp4']);

执行控制

• 超时：您可以作为第二个参数传递毫秒数给 exec()，以在任务运行时间过长时强制终止。
• 终止：使用 ffmpeg.terminate() 来终止 worker 并释放内存。

有关优化技术和元数据提取（ffprobe），请参阅 高级用法。

线程模型

ffmpeg.wasm 提供两个主要核心：@ffmpeg/core（单线程）和 @ffmpeg/core-mt（多线程）。

多线程要求

多线程版本需要 SharedArrayBuffer，该功能仅在具有特定标头的 安全上下文（HTTPS）中可用：

1. Cross-Origin-Opener-Policy: same-origin
2. Cross-Origin-Embedder-Policy: require-corp

有关性能权衡和 PTHREAD_POOL_SIZE 的配置，请参阅 多线程。

框架集成

该库与框架无关，但需要仔细处理 FFmpeg 实例以避免冗余的重初始化。

• React：使用 useRef 在渲染之间持久化 FFmpeg 实例。
• Next.js：使用 NoSSRWrapper 模式，因为该库仅在浏览器中运行。
• Vue/Angular/Svelte：在组件生命周期钩子或专用服务中管理实例。

有关这些框架的实现代码，请参阅 框架示例。