功能与能力

本文档记录了 ffmpeg.wasm 的技术特性和能力，详细说明了媒体格式、编解码器库、线程模型以及浏览器特定的限制。

概述

ffmpeg.wasm 是 FFmpeg（版本 n5.1.4）的纯 WebAssembly/JavaScript 移植版，可直接在浏览器中实现多媒体录制、转换和流式传输。通过利用 Emscripten（版本 3.1.40），该项目将 FFmpeg 源代码和众多第三方库转译为 WebAssembly。

核心架构概念

该系统围绕“可交换核心”的概念构建，该核心充当多媒体引擎。

功能与能力

编解码器库与支持格式

ffmpeg.wasm 编译了一套全面的外部库以支持现代 Web 媒体标准。构建过程使用基于 Docker 的流水线将这些依赖项编译为静态库，然后链接到 FFmpeg 核心。

包含的库

库版本角色 / 能力源码标志
x2640.164.xH.264 视频编码--enable-libx264
x2653.4H.265/HEVC 视频编码--enable-libx265
libvpxv1.13.1VP8/VP9 视频编码/解码--enable-libvpx
lame3.100MP3 音频编码--enable-libmp3lame
opusv1.3.1低延迟音频编解码器--enable-libopus
theorav1.1.1基于 Ogg 的视频压缩--enable-libtheora
vorbisv1.3.3基于 Ogg 的音频压缩--enable-libvorbis
libwebpv1.3.2WebP 图像编码/解码--enable-libwebp
libass0.15.0字幕渲染--enable-libass
freetype2v2.10.4文本叠加的字形渲染--enable-libfreetype
zimg3.0.5缩放和色彩空间转换--enable-libzimg

格式能力

该二进制文件支持这些库的标准 FFmpeg 复用器和解复用器，包括 mp4、webm、ogg、mp3 和 wav。然而，由于 WebAssembly 的限制，需要原生套接字的特性（如 RTSP）目前尚不支持。

线程模型

ffmpeg.wasm 提供两种不同的核心，以在性能与浏览器安全要求之间取得平衡。

1. 单线程模式 (@ffmpeg/core)

  • 实现方式：使用 --disable-pthreads 编译。
  • 优势：在所有现代浏览器中无需特殊标头即可工作；内存开销较低。
  • 限制：执行速度较慢，因为所有处理都在单个线程上进行。

2. 多线程模式 (@ffmpeg/core-mt)

  • 实现方式：使用 WebAssembly Threads 支持进行编译。
  • 性能：通常比单线程模式快 ~2 倍。
  • 安全要求：需要 SharedArrayBuffer，这强制要求以下 HTTP 响应标头：
    • Cross-Origin-Embedder-Policy: require-corp
    • Cross-Origin-Opener-Policy: same-origin
  • 基础设施：在 WorkerGlobalScope 内通过 ffmpeg.worker 启动多个 Web Worker。

数据流与 VFS 能力

与 ffmpeg.wasm 的交互遵循特定的数据生命周期，涉及 JavaScript API 和 Emscripten 虚拟文件系统 (VFS)。

功能与能力

关键工具函数

  • fetchFile(): 将各种输入类型（URL、Base64、File、Blob）标准化为适合 VFS 的 Uint8Array
  • toBlobURL(): 获取数据并返回 Blob URL，有助于绕过 CORS 或加载核心资源
  • downloadWithProgress(): 提供下载进度回调的流式获取包装器

仅限浏览器的限制

虽然功能强大，但 ffmpeg.wasm 具有 WebAssembly 环境固有的特定限制：

  1. 2GB 文件大小限制：由于 WebAssembly 的 32 位内存寻址，虚拟文件系统中任何单个文件都有 2 GB 的硬性上限
  2. 性能：WebAssembly 的执行速度慢于原生执行。虽然多线程有所帮助，但它会消耗更多的 CPU 和内存
  3. 不支持 Node.js：从版本 0.12.0 开始，Node.js 支持已停止，转而采用 fluent-ffmpeg 等原生替代方案
  4. 环境隔离：用户数据完全保留在浏览器内，提供高安全性，并消除了将大文件上传到服务器的网络延迟