JavaScript API 层

ffmpeg.wasm中的 JavaScript API 层为 FFmpeg WebAssembly 核心模块提供了高层抽象。它使 Web 应用程序能够通过简单的基于 Promise 的 API 与 FFmpeg 进行交互，处理了 Web Worker、消息传递和虚拟文件系统操作的复杂性。有关 WebAssembly 核心本身的详细信息，请参阅第 2.1 节。

架构概览

JavaScript API 层围绕消息传递架构构建，利用 Web Worker 在 intensive FFmpeg 操作期间防止阻塞主线程。

JavaScript API 层

FFmpeg 类

FFmpeg类是应用程序的主要接口。它维护对 Worker 的引用，并通过内部回调映射跟踪待处理请求。

JavaScript API 层

初始化过程

要使用 ffmpeg.wasm，应用程序必须首先调用 load()。此方法实例化 Worker（默认为 worker.js）并发送 FFMessageType.LOAD 消息。

JavaScript API 层

消息生命周期

发送到 Worker 的每个请求都遵循涉及唯一 ID 生成和 Promise 跟踪的严格生命周期。

ID 生成：#send方法调用 getMessageID() 生成唯一的数字标识符
Promise 存储：特定请求的 resolve 和 reject函数存储在 #resolves[id] 和 #rejects[id]中
分发：消息通过 postMessage 发送。如果数据包含 Uint8Array，其缓冲区将添加到 transferables 数组以避免内存克隆
解析：当 Worker 完成时，它会发布带有相同 id 的消息。#registerHandlers方法识别匹配的 Promise 并执行存储的回调

FFMessageType 协议

通信协议依赖于 FFMessageType枚举在 Worker 的 onmessage 处理器中路由命令。

类型	源方法	Worker 操作
`LOAD`	`load()`	导入核心并调用 `createFFmpegCore`
`EXEC`	`exec()`	调用 `ffmpeg.exec(...args)`
`WRITE_FILE`	`writeFile()`	调用 `ffmpeg.FS.writeFile(path, data)`
`READ_FILE`	`readFile()`	调用 `ffmpeg.FS.readFile(path, {encoding})`
`MOUNT`	`mount()`	调用 `ffmpeg.FS.mount(fs, options, mountPoint)`
`LOG`	(内部)	由 Worker 在核心日志记录时分发
`PROGRESS`	(内部)	在处理期间由 Worker 分发

错误处理

错误在 Worker 的全局 onmessage try-catch 块中被捕获。如果操作失败（例如 ERROR_NOT_LOADED 或 WASM 崩溃），Worker 将发送一条类型为 type: FFMessageType.ERROR 且数据为错误字符串的消息

在主线程上，FFmpeg类在 #registerHandlers 中捕获此内容并调用存储的 #rejects[id] 回调，导致原始 API Promise 被拒绝

事件系统

API 层使用简单的观察者模式来处理不遵循请求 - 响应 ID 模式的流式数据（日志和进度）。

注册：用户使用 ffmpeg.on("log", callback) 将处理器添加到 #logEventCallbacks
发射：Worker 的 load 函数设置 ffmpeg.setLogger 和 ffmpeg.setProgress钩子。这些钩子在发生时立即向主线程发送消息
分发：在主线程上，FFMessageType.LOG 和 FFMessageType.PROGRESS消息触发各自数组中所有已注册回调的执行