TooBox 也盒 · 视频剪辑功能集成方案#

把视频剪辑能力集成进现有 Tauri 桌面工具箱 TooBox 也盒 的落地方案。 通用技术调研见 桌面视频剪辑调研；本文只写「在这个具体项目里怎么做」。 编写时间：2026-07-28。基线版本：1.0.3。

本文是方案文档，不是实现记录。除 §1 现状事实外，其余均为待实施设计，尚未落地到源码。

修订说明（以最新为准）：

1. 首版为「单视频轨 + 单音轨」，现已改为叠加型多轨（画中画 / B-roll）。
2. 目标场景锁定短视频平台 + 微信分享：导出预设固定三档，预览改为代理预渲染为主，确定不采购商业 SDK。
3. 现金支出 0 元，MVP 工时约 22~28 天（见 §10.1）。

怎么用这份笔记#

1. 判断可行性 → 看 §1.3 可复用范式（结论都在这里）
2. 对齐范围 → 看 §2，尤其 §2.3 待确认问题
3. 动手前 → 看 §5 数据模型、§6 接口清单
4. 排期 → 看 §10
5. 踩坑预防 → 看 §12

1 · 现状事实#

以下均来自当前源码，可直接核对。

1.1 技术栈基线#

1.2 视频剪辑页面现状#

• 页面已存在：src-ui/features/ai-video-editor/AIVideoEditorPage.tsx（474 行）+ 同目录 CSS。
• 已在 src-ui/App.tsx 注册并渲染（import 约 86 行，使用点约 1558 行）。
• 页面当前不含任何 invoke、convertFileSrc 或 Tauri API 调用，属于纯静态 UI 原型：

• 已实现的真实能力：双模式切换（timeline / transcript）、三区可拖拽布局并持久化（localStorage 键 toobox-ai-video-editor-layouts-v1）。

1.3 可直接复用的既有范式#

这是本方案成立的核心前提。

2 · 需求范围#

2.1 当前已确认需求#

• 导入本地视频素材，读取真实时长、分辨率、帧率等元数据
• 非破坏剪辑：裁切、分割、删除、排序
• 叠加型多轨：主视频轨 ×1 + 叠加视频轨 ×1（画中画 / B-roll，支持位置、缩放、裁切、不透明度、z 序）+ 字幕轨 ×1 + 音频轨 ×2（原声 + BGM，含音量与淡入淡出）
• 基础转场：仅交叉溶解一种
• 时间线预览播放与拖动定位；叠加区间走代理预渲染，与成片一致（见 §3.3）
• 导出 MP4，含进度显示与取消
• 导出预设固定三档（不做自定义参数面板）：平台竖屏 1080×1920、平台横屏 1920×1080、微信分享 720×1280；统一 30fps、H.264 + AAC
• 引擎路径可自定义：设置里允许用户指定本机 ffmpeg 路径
• 导出完成后对微信场景给出提示：请以「文件」形式发送，避免被二次压缩
• 项目保存与再次打开
• 文稿剪辑：基于转录文本删语气词、压缩长停顿，并反写时间线
• 字幕烧制与画面比例裁切
• 视频引擎按需下载，不增大安装包体积

2.2 非目标范围#

• 不做通用专业非线编：无限轨、嵌套序列、节点式调色、关键帧动画均不做
• 叠加轨只做静态参数（位置/缩放/不透明度固定），不做“画中画飞入”类动画
• 不做绿幕抠像、混合模式、交叉溶解以外的转场
• 不做实时特效预览与 GPU 合成管线
• 不做 4K / 8K / HDR 导出，不做码率与编码参数自定义面板
• 不随包分发任何 GPL 构建（含 libx264 的版本由用户自行安装）
• 不采用 .NET 系商业 SDK（跨平台不友好，见 §3.5）
• 不自研解码器，不把 FFmpeg 链接进主程序进程内
• 不引入 MLT / melt 等第二套媒体引擎
• 不承诺专业交换格式（ProRes、DNxHR）与冷门摄像机格式
• 语音转录的服务端实现不属客户端职责，客户端只调用
• macOS / Linux 不在首期范围

2.3 待确认问题#

1. 语音转录由服务端接口提供，还是本地运行时（如 whisper.cpp）？影响 P4 工期与体积
2. 引擎下载包托管位置与校验方式（是否复用 WD14 的 R2 与 scripts/upload-r2-object.py 流程）
3. 导出是否计积分；若计，扣减时机是提交任务还是导出成功
4. 工程是否跨设备同步；若同步，素材路径缺失如何处理
5. 是否需要「快速模式（关键帧对齐、无损切）/ 精确模式（重编码）」两档
6. 是否采购商业 SDK（见 §3.5）；叠加型多轨使自研工期增加约 4 周，采购的性价比随之上升
7. 转录与“压停顿”是否直接复用开源件（whisper.cpp、auto-editor，均为 MIT）以消掉问题 1

3 · 技术选型#

3.1 视频处理引擎#

3.2 FFmpeg 构建与分发#

按需下载而非随包的三个理由：

3.3 预览方案（叠加型多轨下已修订）#

基础不变：通过 asset_protocol_scope().allow_directory(parent, false) 授权素材目录，再用 asset 协议交给 <video>，与 resolve_crop_default_reference_image 一致。

因为要叠加，单 <video> 方案不再成立。又因为目标场景是短视频（1~5 分钟），主次关系如下：

• 单图层区间仍直接用 asset 协议播原素材，不需代理
• 非 H.264 素材、4K 长素材先生成低码率代理文件再预览
• 不引入 WebCodecs / canvas 逐帧合成

3.4 导出画质与体积（方案的主要代价）#

用系统编码器换来的是「合规 + 零体积 + 零成本」，代价是编码效率。

主要对策：段级智能重编码（必做）#

构图区间只有单图层且切点对齐关键帧 → stream copy（零损失、零膨胀、极快）
切点落在 GOP 中间                     → 只重编码这一个 GOP，其余 copy
区间内有叠加 / 转场 / 字幕         → 必须重编码（无解）

微信分享场景：三招免费对策（优先做）#

微信不经平台二压，画质直接可见；且发送有体积限制，目标是有限体积内画质最好。

编码器升级路线#

3.5 商业 SDK 对比与采购决策#

三类方案#

桌面 SDK 候选#

注意：阿里云 / 腾讯云 / 火山引擎 / 商汤 / 涂图 / 七牛的短视频 SDK 绝大多数只有 iOS / Android，对 Windows 桌面不适用，直接排除。

可直接复用的开源件#

采购结论#

不采购。 理由：

1. .NET 系方案（VisioForge）跨平台不友好，直接排除
2. 其余桌面 SDK 均需重写渲染层，且不公开报价
3. x264 商业授权约 $10,000 起，不符合个人开发者量级
4. 画质需求可用 §3.4 的三招以 0 元 解决

仅当以下同时成立时重新评估：年出货接近 10 万台（已有规模与收入）、且本地交付成为主场景、且三招均不满意。

4 · 功能模块划分#

4.1 前端模块#

4.2 Rust 模块#

5 · 数据模型#

5.1 模型清单#

5.2 VideoProject#

5.3 VideoSource#

5.4 TimelineTrack#

首期轨道数量固定：video_main ×1、video_overlay ×1、caption ×1、audio ×2。不支持用户新增轨道。

5.5 TimelineClip#

5.6 TransitionItem#

5.7 RenderProgress#

6 · 接口设计#

以下 Tauri command 与事件均为待实现，命名对齐既有 command 风格（动词前缀 + 模块名）。

6.1 接口清单#

6.2 render_video_project（关键接口）#

• 命令：render_video_project
• 调用方：features/ai-video-editor/video-api.ts
• 提供方：src-tauri/src/video/render.rs

用途：把当前时间线编译为一次 FFmpeg 调用并导出 MP4，用户在导出面板确认参数后触发。

请求字段

响应字段

处理规则

• 渲染前校验所有 sources[].path 存在，缺失则直接失败并列出缺失素材，不产出半成品
• 构图流程：按所有片段与转场的起止点把时间线切成区间 → 逐区间确定活动图层与 z 序 → 生成 scale/crop/overlay 与 amix 滤镜链 → 区间间 concat
• 单图层且切点对齐关键帧的区间走 stream copy；含叠加/转场/字幕的区间重编码（见 §3.4）
• 叠加轨坐标与缩放统一基于 output.width/height 画布计算，前端预览必须用同一套换算，否则预览与成片位置对不上
• ffmpeg -progress pipe:1 -nostats 按行解析 out_time_ms，换算百分比后 app.emit('video-render-progress', …)
• 取消复用 WD14 机制：AtomicBool + 活动 PID + child.kill()；取消后删除未完成输出
• 同一时刻只允许一个渲染任务；已有任务时返回明确错误，不排队
• h264_mf 初始化失败时降规格重试一次；仍失败则回报「当前设备不支持系统编码器」

7 · 业务流程#

7.1 首次进入剪辑页面#

进入页面
  → invoke resolve_video_runtime
  → 可用：进入编辑器
  → 不可用：提示需要下载视频引擎（约 80 MB）
      → invoke install_video_runtime
      → 监听 video-runtime-install-progress（复用现有 Progress 组件）
      → 校验通过后进入编辑器

7.2 导入到导出#

选择素材（rfd 文件对话框）
  → probe_video_source：元数据 + 授权素材目录
  → 加入 sources，时间线追加 clip
  → generate_video_thumbnails 异步补缩略图
  → 用户裁切 / 分割 / 排序（仅改内存 EDL）
  → 预览：构图区间判定 → 简单叠加走多路 <video>；滤镜区间走代理预渲染
  → 导出：render_video_project + 进度事件
  → 完成后用 tauri-plugin-opener 打开所在目录

7.3 文稿剪辑（P4）#

选定素材
  → 取得转录结果（服务端接口或本地运行时，见 §2.3）
  → 生成 transcriptLines（替换现有常量）
  → 用户勾选「删除语气词 / 压缩停顿」建议
  → transcript-edit.ts 把文本删除区间映射为时间区间
  → 转成 EDL 的裁切与分割操作
  → 时间线与文稿双向同步

8 · 与既有功能的协同#

9 · 安全与权限#

9.1 权限边界#

• 引擎只允许从既定候选目录加载，并校验为可执行文件，规则同 validate_pose_detector_path
• 引擎下载仅允许项目自有分发地址，下载后必须校验哈希再解压
• 解压时拒绝路径穿越条目（..、绝对路径），避免写出安装目录之外

9.2 本地文件系统#

• 素材目录按需授权 allow_directory(parent, false)，不整盘放开
• 导出路径必须来自用户在文件对话框中的选择，不接受前端任意字符串直接写盘
• 代理文件、缩略图、波形统一写入应用数据目录下独立缓存目录，提供清理入口
• 工程内素材为绝对路径，打开时逐一校验，缺失标记 missing 而非静默丢弃

9.3 待补充#

• 是否限制单次导出最大时长与分辨率，防止长任务占满磁盘
• 缓存目录容量上限与淘汰策略尚未确定

10 · 实施计划#

10.1 成本与工时估算#

现金支出：0 元。

工时（自行开发）：

换算日历：全职约 5 周完成 MVP；每天 3 小时约 2.5 个月。

11 · 测试与验证#

• timeline-model.ts 为纯函数，必须有单元测试：分割、删除、ripple、边界（零长片段、相邻片段、越界 in/out）
• 导出冒烟：样例素材集须含手机竖屏、无音轨、变帧率、含中文空格路径，逐项验证导出成功
• 取消验证：渲染中取消后确认进程退出且无残留输出文件
• 引擎缺失验证：清空引擎目录后进入页面，确认走下载流程而非崩溃
• 素材缺失验证：移动素材后打开工程，确认标记 missing 并给出重新定位入口
• 叠加一致性验证：同一工程分别取预览截图与成片对应帧，比对叠加层位置与缩放是否一致（允许时间上 1~2 帧偏差，不允许空间位置偏差）
• 混音验证：双音轨 + 淡入淡出导出后检查无爆音、无削波
• 转场边界验证：转场时长等于/超过片段时长时应被拒绝，不得生成非法滤镜图

12 · 风险与约束#

13 · 变更日志#

附录 · 与通用调研的分工#