浏览器里剪视频成真了：FilmCraft Web 版架构全拆解（WebCodecs + OPFS）

浏览器里剪视频成真了：FilmCraft Web 版架构全拆解（WebCodecs + OPFS）

【免费下载链接】filmcraftAn open-source, clean-room reimplementation of Adobe Premiere Pro built in pure Rust.项目地址: https://gitcode.com/gh_mirrors/fi/filmcraft

当「网页版视频剪辑」在大多数项目里还停留在「用<video>预览 + 服务器端拼接」时，开源项目 FilmCraft 选择了一条更硬核的路：把一套完整复刻 Adobe Premiere Pro 工作流的 Rust 剪辑引擎，连同 egui 界面一起编译成wasm32-unknown-unknown，交给浏览器直接运行。媒体文件不出本机、不经过服务器，解码交给 WebCodecs 硬件加速，崩溃恢复落在 OPFS，连导出都发生在网页内。

这听起来像 Demo，但它的代码就摆在我们面前：apps/filmcraft-web是一个依赖filmcraft-engine、filmcraft-ui-egui等十余个 crate 的独立 Web 宿主，非 wasm 目标下整个 crate 直接为空，因此它既不污染cargo test --workspace，也迫使所有浏览器专属逻辑集中在一处。本文从源码出发，拆开三条主线：单线程协作式调度如何撑起桌面级剪辑引擎、异步的 WebCodecs 如何被改造成同步接口、OPFS 又如何接住了自动保存与崩溃恢复——最后用仓库里诚实的性能账本，看它还差什么。

从「编译目标」到真正的浏览器工作台

先看它到底编译出了什么。docs/web.md 写得很清楚：这是一个纯静态站点——一个.wasm、一份 wasm-bindgen 胶水 JS、一个index.html、一个AudioWorklet脚本和一个图标。没有任何后端、没有任何上传，媒体始终留在用户机器上（内存中的Blob或 OPFS 中）。

构建链在 xtask/src/main.rs 里值得细看：

• cargo build --target wasm32-unknown-unknown -p filmcraft-web --profile release之后，用wasm-bindgen --target web生成胶水代码，且 CLI 版本与 crate 版本被硬性锁定为0.2.129——版本不匹配直接报错退出，杜绝了胶水与运行时错位的经典坑；
• 若检测到wasm-opt（binaryen），release 构建会对 wasm 执行-O2优化，显式开启--enable-bulk-memory、--enable-nontrapping-float-to-int、--enable-sign-ext、--enable-mutable-globals等特性；
• 产物经过 FNV-1a 哈希后以?v=<hash>注入index.html，让filmcraft_web.js与filmcraft_web_bg.wasm可以被 CDN 按 immutable 缓存——每次构建换 URL，彻底绕开缓存失效问题。

被?v=钉住的index.html自身还带了一层「自救」逻辑（apps/filmcraft-web/web/index.html）：如果 WebGPU 能探测到但启动失败（wgpu/requestDevice/requestAdapter等关键字命中），页面会自动带?webgl参数重载一次；Rust panic 或 OOM abort 会被包装成「FilmCraft stopped working」遮罩而不是一帧冻结的 canvas，并设置window.filmcraftLoad.fatal——注意遮罩文案："Unsaved changes are kept in the browser every few seconds and come back when you reload"，这正是 OPFS 恢复机制在 UX 层的落地。

桌面组件如何映射到浏览器，apps/filmcraft-web/src/lib.rs 的文档注释给出了一张堪称教科书级别的对照表：

这张表也顺带划清了边界：Web 版不是「重写」，而是同一套引擎的宿主替换。这也解释了为什么 ROADMAP 里把它称为 "the browser app shell"——引擎早已就绪，难的是壳。

单线程协作式调度：没有 worker 的引擎怎么「并行」

wasm 线程不是不能有：它要求页面 cross-origin isolated且wasm 构建带 atomics（需要 nightlybuild-std）。这个发布构建两者都没有，所以一切都在 UI 线程上协作式完成，rayon退化为内联执行。启动时filmcraft.info()会把crossOriginIsolated、threads: false、frameWorkers: "cooperative"如实上报——先探测环境，将来有线程版构建也能在启动时选择。

协作式调度有两个实现核心。第一个是帧服务器（crates/ui-egui/src/frames.rs 的FrameServer::pump）：从队列里按优先级取出任务（min_by_key(|(i, j)| (j.prio, *i))），在 UI 线程上跑，播放时预算 24ms、其余 40ms，超时就停；媒体还在加载的任务会被放回队首（retry.push(job)），不会当作解码错误缓存。WebApp::logic里每帧调用它，并视结果决定是否request_repaint继续推进。

第二个是导出（crates/engine/src/lib.rs 的Session::pump_jobs）。SteppedJob把Exporter装进 session，宿主每帧步进一次：exporter.step(...)返回Progress就继续、返回Pending就等下一帧（媒体的字节还在路上）、返回Done才结算结果。WebApp::logic中以 30ms 预算推进，进度照旧显示在头部。桌面版pump_jobs只服务于无线程宿主（web），这是一个很干净的抽象：引擎不知道线程是否存在，宿主告诉它「你只能一次走一步」。

异步 I/O 被缝进这个同步模型，靠的是 crates/media/src/pending.rs 的线程局部标志：BlobReader没有命中的 chunk 时，先发起Blob.slice().arrayBuffer()抓取（并顺带预取 3 个 chunk），然后返回std::io::ErrorKind::WouldBlock并mark()；请求方事后take()检查标志，置位就说明「结果不完整，数据到了请重试」，而不是误判为解码失败或离线媒体。这样整个MediaSource接口保持同步签名不变，异步只发生在BlobReader之下。

内存与 IO 的账也写在 apps/filmcraft-web/src/fs.rs：1 MiB 的 chunk、384 MiB 的 LRU 预算（CACHE_BUDGET = 384 << 20），够一个多 GB 的 MP4 只读索引 + 当前播放窗口而不整文件进内存。导入前还会prewarm：MP4 逐级遍历顶层 box 定位moov并预取，Matroska 小的整文件、大的取头尾各 8 MiB（因为打开要扫每个 cluster 头）。import_path的重试上限是 2000 次——足够宽容，但也能防止死循环拖死页面。

音频侧同样协作：apps/filmcraft-web/src/audio.rs 的Handle::pump每帧把序列混音到250ms 提前量，以 2048 帧为一块投递给 worklet（apps/filmcraft-web/web/audio-worklet.js）。worklet 回传真实播放帧数与currentTime，played_frames在音频时钟上外推但绝不超过已投递量——所以播放头永远以音频为主时钟，worklet 饥饿就停播，绝不超前。浏览器在用户首次点击/按键前会挂起 AudioContext，这段时间播放回退到墙钟，pointerdown/keydown一触发立即resume()。

图形侧的分工是：eframe 拿到 WebGPU 设备就用filmcraft-gpu的 GPU 合成器；WebGL2 下帧合成退到 CPU（?cpu强制关闭 GPU 合成器）。index.html的「WebGPU 失败自动重载为 WebGL2」配合?webgl参数，是这套降级链的最后一环。

WebCodecs 硬件解码：把异步世界适配成同步接口

FilmCraft 自己的 H.264/HEVC/VP9/AV1 解码器在浏览器里原样运行——这是它和所有「前端剪辑库」的根本区别。但 WebCodecs 存在时，MP4/MOV 的 H.264、HEVC、VP9、AV1 视频会被浏览器的（通常是硬件）VideoDecoder接管。apps/filmcraft-web/src/webcodecs.rs 的实现思路非常明确：WebCodecs 解码是异步的，而引擎的VideoDecodertrait 是同步的，所以 WebCodecs 不伪装成解码器，而是伪装成媒体源。

reader_opener通过filmcraft_codecs::register_reader_opener注册在内建 opener 之前：它先用自己的Mp4Source解析容器（音频轨与媒体信息完全复用自家代码），再取出视频轨的CodecConfig生成 WebCodecs 需要的 codec 字符串——avc1.{profile}{compat}{level}、hvc1/hev1带 profile/tier/level 与 constraint 的完整拼装、vp09.xx.yy.zz、av01.…，全部来自 isobmff 解析出的真实参数而非猜测。VideoDecoder.isConfigSupported在启动时探测四个族，?nowebcodecs可一键关闭。

解码会话的调度是一套完整的异步状态机，常量都是工程味道：

/// Samples fed past the wanted one (decoders hold pictures for reordering). const LOOKAHEAD: usize = 8; /// Decoded frames kept per source. const CACHE_FRAMES: usize = 40; /// Chunks allowed in the decoder's queue before feeding pauses. const MAX_QUEUE: u32 = 24; /// A session that delivered nothing for this long may be restarted by another request. const STALE_MS: f64 = 2000.0;

一个帧请求找不到缓存帧时，从最近的 sync sample 起（重新）启动会话，喂到目标 sample 之后LOOKAHEAD个，然后pending::mark()并返回MediaError::Decode("WebCodecs: decoding")——帧服务器稍后重试，届时解码器的 output 回调已经把画面送进该源专属的 40 帧缓存。为防止缩略图与监视器互相重置对方的会话，STALE_MS规定「一个尚未交付目标帧的会话不被其他请求打断」，只有安静 2 秒才允许重启；流末尾则用flush()逼出为重排序而滞留的画面。任何VideoDecoder错误或配置不支持，都会把该源整体切换回自家解码器（计数器fallbacks可见）。

像素搬移是性能的关键分水岭（apps/filmcraft-web/src/webcodecs/pixels.rs）：VideoFrame.copyTo直接把原生 YUV 平面（NV12/I420/I422/I444，含 alpha 变体与交错 UV）拷进PixelData::Yuv8，不做任何色彩转换或色度重建——色彩空间信息（colorSpace的 matrix/transfer/primaries/fullRange）原样映射成filmcraft_color::ColorInfo，交付给桌面级 frame/compositor 契约。只有浏览器格式不支持、带旋转/flip 或几何异常时才退回OffscreenCanvas.drawImage + getImageData的 RGBA 路径，并逐一计数原因（canvasReasons）。MAX_COPY_BYTES = 256 MiB则防止浏览器驱动的分配失控。这些数字全都能通过filmcraft.info().webcodecsStats现场审计：nativeFrames、canvasFrames、closedFrames、staleFrames、nativeBytes、各会话的queue/idleMs——一个把「可观测性」焊进生产代码的例子。

局限也如实写在文档里：WebCodecs 路径只覆盖 MP4/MOV；HEVC 在部分浏览器/厂商上本就不可用（探测到的才注册）；音频始终走自家解码器。但方向是对的——浏览器只解码，不做任何媒体理解，理解还在 Rust 这边。

OPFS 崩溃恢复：把桌面级自动保存搬进浏览器

桌面版有崩溃恢复日志，Web 版把它映射到 OPFS，但工程上做了两个关键升级。

第一，写入被合并。apps/filmcraft-web/src/opfs.rs 维护一个按路径聚合的队列：同一路径的新写入覆盖旧字节并合并回调，写任务串行执行，createWritable→write→close一步不省。自动保存（apps/filmcraft-web/src/recovery.rs）每帧tick：项目有未保存变更时，最多每 5 秒（recovery_policy.rs的INTERVAL_S）写一次recovery/snapshot.fcproj，recovery/meta.json标记dirty: true；快照与 meta两笔都落地才算成功（失败则下一个周期自动重试，无需再有新编辑）；用户下载保存后 meta 被标记 clean 退役。策略逻辑被抽成纯函数Policy::tick，脱离浏览器原生测试——apps/filmcraft-web/tests/recovery_policy.rs直接跑在cargo test里，这是「不可测的浏览器代码与可测的策略分离」的范本。

第二，媒体副本「不经过 wasm 内存」。导入时keep_media把小于 4 GiB 的文件后台流式拷入 OPFSmedia/（store_blob用FileSystemWritableFileStream.write(blob)，浏览器内部搬移）；下次访问启动时restore_media()把它们重新注册回/files/路径，load_snapshot()若发现脏快照就把它作为/recovered/<name>.fcproj打开，并提示 "Recovered unsaved changes"。URL 参数?norecover（不重开快照）、?fresh（连媒体副本也不恢复）则给了测试和调试一条干净的退路——跳过恢复但不删快照，直到本次会话自己写入新快照才退役，避免误伤用户数据。

配合index.html的致命遮罩，这套组合的实际效果是：你在浏览器里改了半小时没保存，页面崩溃/刷新后回来，工程还在，素材还在。对一个 NLE（非线性剪辑器）来说，这几乎是最高的可靠性要求。

性能账本与下一步：离生产可用还差什么

仓库对现状的自我评估值得原样引用：ROADMAP.md 在 "Honest assessment" 里直言性能维度「~35–40%」，并把 "The web app shell: file access, WebCodecs, audio" 列为待办——也就是说，这套 Web 架构本身是「编译目标已验证、应用壳未完成」的状态。桌面端的数据（4K H.264 硬件解码每帧 CPU 11ms vs 软件 417ms、4K HEVC 10ms vs 203ms）暗示了 WebCodecs 硬件解码在浏览器里的价值上限；而 Web 端真正的瓶颈集中在三处：

1. 协作式单线程是最大的天花板。帧渲染、解码投喂、混音、编码推进全都挤在 UI 线程的时间预算里（播放 24ms / 非播放 40ms / 导出 30ms），这意味着重负载素材的回放帧率被 UI 交互直接拖累。出路是 cross-origin isolated 页面 + atomics 构建的线程版（代码已预留crossOriginIsolated探测），或者把导出挪进真正的 worker——filmcraft_export::Exporter本身是纯 Rust 可 Send 的，封装成本不高。
2. 像素搬移的两条路都不便宜。copyTo原生 YUV 已避开 RGBA 往返，但仍是 CPU 拷贝；Canvas fallback 的getImageData是明确的热点（canvasMs/canvasReasons就是为它准备的仪表）。真正零拷贝是 WebCodecs 输出直接进 wgpu 纹理——这和 ROADMAP 里桌面端 "zero-copy decoded frames into wgpu" 是同一个难题在浏览器的镜像。
3. 媒体可读性有时间窗。非 OPFS 副本的文件只在页面打开期间可读（刷新即失效），Matroska/WebM 大于 chunk 缓存时导入很慢，HEVC 支持又随浏览器而异——这些都会真实地出现在用户面前，而不是纸面指标。

回看整条链路：moov预取、WouldBlock重试、384 MiB 分块缓存、解码会话防重置、OPFS 双写快照——每一层都是「浏览器异步世界」对「桌面同步引擎」的适配，而引擎本身一行没改。这种「宿主替换、内核不动」的分层，加上window.filmcraft这层与 MCP/CLI 同协议的 Promise API（apps/filmcraft-web/src/api.rs），让无头 Chrome 的 smoke 测试（apps/filmcraft-web/tests/smoke.mjs，零 npm 依赖）能完整跑通「加载 → 播 Demo → 导入 MP4 → 播放 → H.264 导出下载」全流程。浏览器剪视频这件事，在 FilmCraft 这里已经不止是「成真」，而是把桌面级工程问题逐项搬到 Web 之后，还留下了清晰、可度量的下一步。

【免费下载链接】filmcraftAn open-source, clean-room reimplementation of Adobe Premiere Pro built in pure Rust.项目地址: https://gitcode.com/gh_mirrors/fi/filmcraft