术语表

本术语表定义了 ffmpeg.wasm 代码库中使用的技术术语、架构组件和领域专用行话。它作为工程师理解 JavaScript API 与 WebAssembly 核心之间实现细节和数据流的参考。

核心架构实体

FFmpeg Class

库的主要入口点。它充当高级包装器，管理 Web Worker 的生命周期并与底层 WebAssembly 核心通信。

  • Implementation: 定义在
  • Key Methods:
    • load(): 启动 worker 并初始化 Wasm 模块
    • exec(): 发送命令供 FFmpeg 二进制文件执行
    • writeFile()/readFile(): 与虚拟文件系统交互的接口

FFmpegCoreModule

Emscripten 工厂返回的对象。它包含导出的 C 函数和 Emscripten 文件系统 (FS) 对象。

  • Definition:
  • Key Properties: FS, exec, ffprobe, ret (退出码)。

FFMessageType

定义主线程与 Web Worker 之间通信协议的枚举。

  • Definition:
  • Examples: LOAD, EXEC, WRITE_FILE, LOG, PROGRESS。

Message Lifecycle Diagram

下图说明了命令从主线程流向 WebAssembly 执行环境的过程。

"Main Thread to Code Entity Mapping"

主线程到代码实体映射图

文件系统术语

VFS (Virtual File System)

由 Emscripten 提供的一层，用于在浏览器中模拟类 POSIX 文件系统。

  • Implementation: 通过 worker 中的 ffmpeg.FS 访问

MEMFS

默认的内存文件系统。所有文件都存储在堆中，并在页面重新加载时丢失。

WORKERFS

一种特殊的文件系统，提供对 File 和 Blob 对象的只读访问，而无需将它们复制到 Emscripten 堆中。这对于处理大文件 (>2GB) 至关重要。

  • Implementation: 通过 mount 配置为 FFFSType.WORKERFS
  • Configuration:

构建与环境术语

Emscripten (emcc)

用于将 FFmpeg 的 C 源代码转换为 WebAssembly 和 JavaScript 胶水代码的编译器工具链。

  • Build Script:
  • Flags:
    • -sMODULARIZE: 将输出包装在工厂函数 createFFmpegCore 中
    • -sPTHREAD_POOL_SIZE=32: 设置可用于多线程的 web workers 数量

SharedArrayBuffer

用于在主线程和 worker 之间共享内存的 JavaScript 对象。对于多线程版本 (@ffmpeg/core-mt) 是必需的。

  • Requirement: 在文档中注明

mainScriptUrlOrBlob "Hash Hack"

worker 中的一个特定实现细节，用于在使用 ESM 或自定义 URL 时解析 .wasm 和 .worker.js 文件的路径。配置被 base64 编码并附加到 URL 哈希中。

  • Code Pointer:

组件关系图

"Natural Language to Code Entity Mapping"

TermCode Entity / SymbolResponsibility
Main APIFFmpeg class管理 worker，暴露用户可见的方法如 exec 和 load。
Worker Scriptworker.ts监听消息，调用 Wasm 函数，并将日志/进度回传。
Wasm FactorycreateFFmpegCore由 Emscripten 生成的初始化函数。
Message ProtocolFFMessageType定义通信模式的枚举。
FS Handlerffmpeg.FS用于文件操作的 Emscripten FS 对象。

"System Component Hierarchy"

系统组件层次结构图

工具和辅助术语

fetchFile

一个实用工具，用于将各种输入类型（URL、Blob、File、Base64）转换为适合 writeFile 的 Uint8Array。

  • Usage:

toBlobURL

一个辅助工具，用于将脚本或 Wasm 文件转换为 Blob URL，以绕过 CORS 限制或从 CDN 加载资源。

  • Usage:

Log and Progress Events

在执行期间由 Wasm 核心发出的流式数据。

  • 日志: 捕获 FFmpeg 的 stdout 和 stderr
  • 进度: 基于媒体时长估算完成度
  • Worker Hook: 日志和进度通过 worker 中的 ffmpeg.setLogger 和 ffmpeg.setProgress 进行管道传输