从 ffmpeg.wasm 到 WebCodecs：浏览器视频编辑器导出架构的演进与实践-阿里云开发者社区

前言

在浏览器中实现视频编辑，最容易想到的方案通常是 ffmpeg.wasm。

项目中的实际实现已经开源，包括多轨时间线、字幕、贴纸、画中画、WebCodecs 离线导出、OfflineAudioContext 混音和 ffmpeg.wasm 兼容转码：

https://github.com/MartinDelophy/ai-video-editor

正文继续

FFmpeg 本身拥有完整的音视频处理能力。通过 WebAssembly，它可以在浏览器中完成音频提取、格式转换、视频编码、音视频封装和滤镜处理。

我们开发的浏览器视频编辑器最初也采用了类似思路：将素材写入 ffmpeg.wasm 的虚拟文件系统，通过 FFmpeg 命令生成最终视频。

但随着项目逐渐加入多轨时间线、字幕、贴纸、画中画、蒙版、关键帧、转场、配音和背景音乐，单纯依赖 ffmpeg.wasm 的问题开始显现：

首次加载成本较高
大文件复制带来明显的内存压力
预览和导出需要维护两套渲染逻辑
浏览器的编码能力没有被充分利用
长任务的进度、取消和错误恢复不够灵活
MP4 转码失败可能导致整个导出结果丢失

经过多轮调整，我们最终采用了下面的混合架构：

Canvas
  + WebCodecs
  + OfflineAudioContext
  + Mediabunny
  + MediaRecorder
  + ffmpeg.wasm

本文将介绍各项技术在这套浏览器视频导出架构中的职责，以及 ffmpeg.wasm 更适合承担哪些工作。

第一版：以 ffmpeg.wasm 为中心

最直接的导出方式是将输入文件写入虚拟文件系统：

const {
    FFmpeg } = await import("@ffmpeg/ffmpeg");
const {
    fetchFile } = await import("@ffmpeg/util");

const ffmpeg = new FFmpeg();

await ffmpeg.load({
   
  coreURL: "/ffmpeg/ffmpeg-core.js",
  wasmURL: "/ffmpeg/ffmpeg-core.wasm",
});

await ffmpeg.writeFile(
  "input.webm",
  await fetchFile(inputBlob),
);

随后执行转码：

await ffmpeg.exec([
  "-i",
  "input.webm",
  "-c:v",
  "libx264",
  "-c:a",
  "aac",
  "-movflags",
  "+faststart",
  "output.mp4",
]);

读取输出文件：

const data =
  await ffmpeg.readFile("output.mp4");

const result = new Blob([data.buffer], {
   
  type: "video/mp4",
});

对于格式转换工具来说，这套方案非常实用。

但视频编辑器不只是格式转换。编辑器需要根据时间线，在每一个时刻计算当前应该出现的内容。

例如：

当前使用哪个视频片段
视频片段应该播放到哪一帧
字幕是否显示
贴纸是否处于有效时间范围
画中画图层位于什么位置
关键帧应该插值到什么数值
转场进行到什么进度
多条音频轨道如何混合

如果全部转换为 FFmpeg 命令和 Filter Graph，前端预览和导出逻辑就会逐渐分离。

为什么预览与导出的一致性很重要？

在编辑器中，用户看到的预览就是对最终结果的承诺。

假设预览使用 Canvas 和 CSS，而导出使用另一套 FFmpeg Filter Graph，那么以下细节很容易产生差异：

字幕换行宽度
字体大小和行高
字幕背景内边距
图片的 contain/cover 计算
画中画的位置和缩放
贴纸透明度
蒙版圆角
关键帧插值
转场的起止时间

功能越复杂，两套渲染器越难保持一致。

因此，我们决定让预览和导出共享同一套画面合成函数。

使用 Canvas 进行逐帧合成

导出开始时，首先根据项目时长和帧率生成帧计划。

export function createFramePlan(
  duration,
  frameRate = 30,
) {
   
  const fps = Math.max(
    24,
    Math.min(60, Math.round(frameRate)),
  );

  const frameCount = Math.max(
    1,
    Math.ceil(duration * fps),
  );

  return Array.from(
    {
    length: frameCount },
    (_, index) => ({
   
      index,
      timestamp: index / fps,
      duration: 1 / fps,
      keyFrame: index % (fps * 2) === 0,
    }),
  );
}

对于每个输出时间戳，合成器解析当前时间线状态：

function resolveTimelineAtTime(
  project,
  timestamp,
) {
   
  return {
   
    visual: resolveVisual(
      project.visualSegments,
      timestamp,
    ),

    captions: resolveCaptions(
      project.captionSegments,
      timestamp,
    ),

    stickers: resolveStickers(
      project.stickerSegments,
      timestamp,
    ),

    overlays: resolveOverlays(
      project.overlaySegments,
      timestamp,
    ),
  };
}

然后绘制到离屏 Canvas：

async function renderFrame(
  context,
  canvas,
  project,
  timestamp,
) {
   
  const state = resolveTimelineAtTime(
    project,
    timestamp,
  );

  context.clearRect(
    0,
    0,
    canvas.width,
    canvas.height,
  );

  drawVisual(
    context,
    state.visual,
    canvas,
  );

  drawOverlays(
    context,
    state.overlays,
    canvas,
  );

  drawStickers(
    context,
    state.stickers,
    canvas,
  );

  drawCaptions(
    context,
    state.captions,
    canvas,
  );
}

这种方式有一个重要优势：预览与导出可以共享 drawVisual、drawCaptions、drawStickers 等几何计算。

导出不再需要重新实现一套视觉规则。

使用 WebCodecs 进行确定性编码

Canvas 完成当前帧合成后，可以通过 WebCodecs 编码。

与 MediaRecorder 的实时录制模型不同，WebCodecs 允许应用显式控制每一帧的时间戳。

这意味着即使设备实际只能以每秒 10 帧的速度完成渲染，最终输出文件仍然可以是准确的 30 FPS。

概念上可以表示为：

for (const frame of framePlan) {
   
  await renderFrame(
    context,
    canvas,
    project,
    frame.timestamp,
  );

  const videoFrame = new VideoFrame(
    canvas,
    {
   
      timestamp:
        Math.round(
          frame.timestamp * 1_000_000,
        ),
    },
  );

  encoder.encode(videoFrame, {
   
    keyFrame: frame.keyFrame,
  });

  videoFrame.close();
}

这种确定性导出路径适合：

视频编辑器
时间线动画
字幕烧录
数据可视化视频
图片序列生成
需要精确帧数的内容生产工具

项目中使用 Mediabunny 负责 MP4/WebM 容器，以及编码结果的音视频 mux。

使用 OfflineAudioContext 混合多轨音频

画面可以逐帧渲染，音频则更适合一次性离线混合。

编辑器包含多种音频来源：

视频原声
AI 配音
用户录音
背景音乐
人声分离结果
伴奏音轨

每个音频片段具有独立的时间属性：

{
   
  start: 3.5,
  sourceOffset: 1.2,
  sourceDuration: 4.8,
  volume: 0.8,
  playbackRate: 1,
  fadeIn: 0.2,
  fadeOut: 0.5,
}

首先创建最终视频长度对应的 OfflineAudioContext：

const sampleRate = 48_000;

const context =
  new OfflineAudioContext(
    2,
    Math.ceil(duration * sampleRate),
    sampleRate,
  );

将音频片段放到对应位置：

for (const clip of audioClips) {
   
  const source =
    context.createBufferSource();

  const gain =
    context.createGain();

  source.buffer = clip.buffer;

  gain.gain.setValueAtTime(
    clip.volume,
    clip.start,
  );

  source
    .connect(gain)
    .connect(context.destination);

  source.start(
    clip.start,
    clip.sourceOffset,
    clip.sourceDuration,
  );
}

如果需要淡入：

gain.gain.setValueAtTime(
  0,
  clip.start,
);

gain.gain.linearRampToValueAtTime(
  clip.volume,
  clip.start + clip.fadeIn,
);

最终生成完整混音：

const mixedAudio =
  await context.startRendering();

这样可以让预览、时间线和导出的音频位置保持一致。

ffmpeg.wasm 负责哪些工作？

调整架构后，ffmpeg.wasm 不再承担主画面渲染，但依然是项目中的重要组件。

1. 提取视频原声

用户导入视频后，编辑器需要提取音频用于波形、剪辑、字幕识别和人声分离。

await ffmpeg.exec([
  "-i",
  "input.mp4",
  "-vn",
  "-acodec",
  "pcm_s16le",
  "-ar",
  "48000",
  "-ac",
  "2",
  "source.wav",
]);

其中：

-vn 忽略视频轨道
pcm_s16le 输出 PCM WAV
-ar 48000 设置采样率
-ac 2 设置双声道

这类输入明确、输出明确的媒体处理任务，很适合交给 ffmpeg.wasm。

2. 拼接与标准化音频

不同视频的音频可能具有不同的编码格式、采样率和声道数。

在进行波形计算或时间线拼接前，可以先利用 FFmpeg 统一格式。

3. WebM 转 MP4

不同浏览器对 H.264 和 AAC 的 WebCodecs 编码支持不同。

如果浏览器可以直接生成 MP4，导出流程不需要 FFmpeg。

如果只能先生成 WebM，而用户明确要求 MP4，则在最后一步动态加载 ffmpeg.wasm：

async function transcodeToMp4(
  webmBlob,
) {
   
  const {
    ffmpeg, fetchFile } =
    await loadFFmpeg();

  const taskId =
    crypto.randomUUID();

  const inputName =
    `input-${
     taskId}.webm`;

  const outputName =
    `output-${
     taskId}.mp4`;

  try {
   
    await ffmpeg.writeFile(
      inputName,
      await fetchFile(webmBlob),
    );

    await ffmpeg.exec([
      "-i",
      inputName,
      "-c:v",
      "libx264",
      "-c:a",
      "aac",
      "-movflags",
      "+faststart",
      outputName,
    ]);

    const data =
      await ffmpeg.readFile(
        outputName,
      );

    return new Blob([data.buffer], {
   
      type: "video/mp4",
    });
  } finally {
   
    await ffmpeg
      .deleteFile(inputName)
      .catch(() => {
   });

    await ffmpeg
      .deleteFile(outputName)
      .catch(() => {
   });
  }
}

保留最后一个正确结果

导出系统中有一个容易被忽视的问题：如果 WebM 已经生成成功，但最后的 MP4 转码失败，是否应该让整个任务失败？

我们的答案是否定的。

WebM 已经是一个有效的完整视频，不应该因为后续格式转换失败而被丢弃。

if (result.nativeMp4) {
   
  download(
    result.blob,
    "video.mp4",
  );

  return;
}

try {
   
  const mp4 =
    await transcodeToMp4(
      result.blob,
    );

  download(
    mp4,
    "video.mp4",
  );
} catch (error) {
   
  console.error(error);

  download(
    result.blob,
    "video.webm",
  );
}

因此，系统始终保留“最后一个正确结果”：

优先生成确定性的 MP4 或 WebM
需要时再转换为 MP4
MP4 转换成功后保存 MP4
转换失败则保存已经完成的 WebM

这种设计避免用户因为最后一个转换步骤失败，失去前面几分钟的渲染成果。

完整导出流程

当前导出链路如下：

解析时间线
    ↓
生成精确帧计划
    ↓
Canvas 逐帧合成
    ↓
WebCodecs 编码
    ↓
OfflineAudioContext 混音
    ↓
Mediabunny 封装 MP4/WebM
    ↓ WebCodecs 不可用
MediaRecorder 兼容导出
    ↓ 用户要求 MP4
ffmpeg.wasm 兼容转码
    ↓ 转码失败
保存已完成的 WebM

各组件的职责如下：

组件	职责
Canvas	画面、字幕、贴纸、蒙版和转场合成
WebCodecs	确定性视频编码
OfflineAudioContext	多轨音频混合
Mediabunny	MP4/WebM 封装与 mux
MediaRecorder	浏览器兼容回退
ffmpeg.wasm	音频处理和格式转换

ffmpeg.wasm 的内存管理

ffmpeg.wasm 的虚拟文件系统不是磁盘，它使用的仍然是浏览器内存。

因此，每次任务完成后都应该清理文件：

try {
   
  await ffmpeg.writeFile(
    inputName,
    inputData,
  );

  await ffmpeg.exec(args);

  return await ffmpeg.readFile(
    outputName,
  );
} finally {
   
  await ffmpeg
    .deleteFile(inputName)
    .catch(() => {
   });

  await ffmpeg
    .deleteFile(outputName)
    .catch(() => {
   });
}

同时，应避免多个任务复用固定文件名：

const id = crypto.randomUUID();

const inputName =
  `input-${
     id}.webm`;

const outputName =
  `output-${
     id}.mp4`;

这可以避免并发操作发生覆盖。

按需加载与缓存

建议只在用户真正执行 FFmpeg 任务时加载运行时：

let ffmpegPromise;

function getFFmpeg() {
   
  ffmpegPromise ??=
    createFFmpegInstance();

  return ffmpegPromise;
}

第一次操作需要加载 WASM，后续操作可以复用实例。

如果项目以 PWA 形式交付，还可以通过 Service Worker 缓存 FFmpeg Core 和 WASM 文件，避免用户重复下载。

缓存时应使用版本化路径：

/vendor/ffmpeg/0.12.10/ffmpeg-core.js
/vendor/ffmpeg/0.12.10/ffmpeg-core.wasm

避免运行时代码与旧 WASM 文件不匹配。

多线程版本的部署要求

使用依赖 SharedArrayBuffer 的多线程版本时，需要启用 Cross-Origin Isolation。

常见响应头为：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

同时要注意，页面加载的跨域资源也必须满足要求，包括：

视频和图片
字体
Worker
FFmpeg Core
WASM 文件
AI 模型文件
第三方 CDN 资源

在云端部署时，可以先检查：

console.log(
  window.crossOriginIsolated,
);

只有返回 true，依赖 SharedArrayBuffer 的能力才能正常使用。

导出进度应该分阶段展示

不要只显示一个笼统的“正在导出”。

更清晰的状态包括：

正在准备素材
正在解析视频音频
正在混合音轨
正在渲染第 120 / 900 帧
正在编码视频
正在封装 MP4
正在加载 FFmpeg
正在转换 MP4
正在验证输出文件
正在保存

ffmpeg.wasm 的加载时间和实际转码时间是两个不同阶段，应该分别显示。

ffmpeg.on(
  "progress",
  ({
    progress }) => {
   
    updateProgress(
      90 + progress * 8,
    );
  },
);

例如，可以把前 90% 分配给主渲染，把最后的 8% 分配给 MP4 转码，剩余部分用于验证和保存。

不要只验证 Blob 大小

视频导出函数返回了一个非空 Blob，不代表输出文件一定正常。

更可靠的测试应该验证：

视频宽高
总时长
视频轨道
音频轨道
帧数
首尾帧
字幕是否可见
透明贴纸是否正确
画中画是否出现在正确时间
音频是否真的可以播放

基础检查：

expect(
  result.blob.size,
).toBeGreaterThan(0);

expect(
  metadata.width,
).toBe(1920);

expect(
  metadata.height,
).toBe(1080);

expect(
  metadata.audioTrackCount,
).toBeGreaterThan(0);

在端到端测试中，还可以重新解码输出视频，并抽取指定时间点的帧进行像素验证。

总结

ffmpeg.wasm 为浏览器带来了非常完整的音视频处理能力，但复杂视频编辑器并不一定要把全部渲染任务交给 FFmpeg。

在我们的实践中，更合适的分工是：

Canvas 负责与预览一致的画面合成
WebCodecs 负责逐帧确定性编码
OfflineAudioContext 负责多轨音频混合
Mediabunny 负责 MP4/WebM 容器封装
MediaRecorder 负责兼容性回退
ffmpeg.wasm 负责音频提取、格式标准化和 MP4 转码

这种架构充分利用浏览器原生媒体能力，同时保留 FFmpeg 在格式兼容方面的优势。

当 MP4 转码失败时，系统仍然保存已经完成的 WebM，避免用户失去整个导出结果。

如果你也在开发浏览器端音视频工具，可以把 ffmpeg.wasm 看作一个专业媒体处理层，而不是必须承担整个应用的唯一渲染引擎。

从 ffmpeg.wasm 到 WebCodecs：浏览器视频编辑器导出架构的演进与实践

前言