# WB Cut

> 本地视频剪辑工具：用中文指令剪片，素材不出本机。

WB Cut 把完整的剪辑能力封装成一个 MCP Server——素材分析、裁剪拼接、竖屏改编、字幕、配音、调色、蒙版、关键帧、预览与导出都能用自然语言驱动；同时提供一个浏览器里的多轨编辑器，可以完全不用 AI，纯鼠标操作。

- **本地优先**：素材、工程、缓存、导出全部留在本机，默认不联网，不调用云端模型。
- **能力诚实**：`video_capability_get` 返回的能力开关与实际实现同源；模型或外置命令缺失时返回 `ENGINE_UNAVAILABLE`，不假装可用。
- **原子编辑**：一次批量操作只产生一个 revision，失败不留半成品；撤销/重做走完整快照历史。
- **导出不降级**：`resolution: "source"` 跟随素材原始分辨率，发生降采样会返回 `DOWNSCALE` 警告。

当前版本 `v0.29.0`（工程 schema 7）。版本历史见 [CHANGELOG.md](CHANGELOG.md)，第三方组件许可见 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。

## 功能概览

| 分类 | 能力 |
|---|---|
| 基础剪辑 | 多轨时间线、裁剪/分割/移动、波纹删除、变速（0.1–100x，含曲线变速）、倒放、定格、音画联动、复合片段 |
| 画面 | 关键帧、四角变形、画中画、蒙版（圆/矩/心/星/多边形/自由路径）、绿幕抠像、混合模式、22 种转场、画面特效、边框圆角投影 |
| 调色 | 16 项参数、`.cube/.3dl/.dat` LUT、8 色带 HSL、RGB 曲线、Lift/Gamma/Gain 色轮、示波器数据（波形/矢量/分量） |
| 音频 | 真总线混音（EQ/压缩/混响/并行发送）、降噪、变调、变声、闪避、响度归一、采样级编辑、5.1 上混 |
| 文本 | ASS 渲染、竖排、真实发光与阴影模糊、60 套花字、文字模板、逐字卡拉OK、双语字幕、软字幕封装 |
| 智能 | ASR 字幕（whisper.cpp / faster-whisper）、场景检测、节拍卡点、文稿驱动剪辑、主体跟踪、人像美化、ONNX 抠像 |
| 交付 | 分段缓存、流式实时预览、浏览器编辑器、批量与多版本导出、FCPXML/EDL、渲染队列、剪同款模板 |

## 环境要求

| 组件 | 要求 | 说明 |
|---|---|---|
| Node.js | ≥ 22 | 运行时；`npm run ci` 会检查 |
| FFmpeg / ffprobe | 6.x | 由 `scripts/get-ffmpeg.mjs` 下载，或用 `WBCUT_FFMPEG` 指向已有二进制 |
| 操作系统 | Windows 10/11 x64 | 主要开发与验证平台。macOS / Linux 可运行服务和渲染，FFmpeg 需自行准备 |
| Python | 3.13+（可选） | 仅 faster-whisper 语音识别后端需要 |
| 磁盘 | ≥ 2 GB 空闲 | 分段缓存、预览帧与导出临时文件 |

## 安装

```bash
git clone <repository-url> wb-cut
cd wb-cut

npm install                    # 安装依赖
node scripts/get-ffmpeg.mjs    # 下载 FFmpeg 到 vendor/ffmpeg（Windows）
npm run build                  # 编译 TypeScript 到 dist/
```

`get-ffmpeg.mjs` 从 gyan.dev 下载 essentials 构建并解压出 `ffmpeg.exe` / `ffprobe.exe`。该构建为 GPLv3，对外分发前请阅读 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。

macOS / Linux 没有自动下载脚本，请自备 FFmpeg 并设置：

```bash
export WBCUT_FFMPEG=/usr/local/bin/ffmpeg
export WBCUT_FFPROBE=/usr/local/bin/ffprobe
```

可选组件，按需安装：

```bat
vendor\ai\setup-asr.cmd        :: Windows：创建 vendor/pyenv，安装 faster-whisper，下载 whisper small 与 u2net
```

whisper.cpp 后端则把 `whisper-cli` 与 `ggml-*.bin` 放进 `vendor/asr/`。

## 快速开始

### 1. 启动 MCP Server

```bash
npm start        # 以 stdio 方式运行，由 MCP 客户端拉起
start.cmd        # Windows：自动装依赖、编译、校验 ffmpeg 后启动（可双击）
./start.sh       # macOS / Linux
```

### 2. 接入 MCP 客户端

任意支持 stdio 的 MCP 客户端，把路径换成你的实际安装位置：

```json
{
  "mcpServers": {
    "wb-cut": {
      "command": "node",
      "args": ["D:/path/to/wb-cut/dist/src/index.js"],
      "env": { "WBCUT_HOME": "D:/WBCut" },
      "timeout": 120000
    }
  }
}
```

`connector/` 是配套的连接器包（`mcp.json` + `connector-meta.json` + `skills/wb-cut/SKILL.md`），装入支持 Connector 的客户端后，内置技能会告诉模型如何调用工具。

### 3. 打开浏览器编辑器

```bash
npm run editor                      # 打开最近一个工程
npm run editor -- <project_id>      # 指定工程
npm run editor -- --port 5173       # 指定端口（默认自动分配）
npm run editor -- --list            # 列出所有工程
```

控制台会打印两个地址：`/editor` 是完整编辑器，`/` 是只读预览。

### 4. 直接下指令

接好 MCP 客户端后，可以直接这样描述需求：

- 把 `a.mp4` 的第 5 到 8 秒删掉，后半段自动接上，导出 1080p
- 自动识别语音配字幕，做成中英双语，标题用花字模板
- 改成竖屏，构图跟住人物，结尾加关注贴纸
- 调成日系通透感，套这个 `.cube` LUT，按 -14 LUFS 导出
- 实时预览一下这一版，我边看边改

## 一次完整剪辑的调用顺序

MCP 客户端（或你自己写的调用方）按下面的顺序走即可：

1. `video_capability_get` — 先确认引擎、字体、ASR 与导出能力是否可用
2. `video_probe` — 探测每个素材的时长、分辨率、帧率、旋转与音轨
3. `video_project_create` — 新建工程（或 `video_project_list` 复用已有工程）
4. `video_asset_import` — 逐个导入素材，记录返回的 `asset_id`
5. `video_edit_apply` — 批量提交编辑操作，必须带 `expected_revision`；高风险改动先 `dry_run: true` 预演
6. `video_preview_frame` / `video_preview_live` — 看单帧或流式预览
7. `video_project_validate` — 校验时间线、字幕与导出参数
8. `video_export` — 提交导出，用 `video_job_get` 轮询到终态

时间单位统一为整数毫秒，全部按工程帧率量化，返回值里 `snapped` 表示实际生效值。

## 目录结构

| 路径 | 说明 |
|---|---|
| `src/` | MCP Server、工程模型、编辑引擎、渲染管线、任务管理 |
| `src/preview/` | 预览与编辑器 HTTP 服务（`/api/edit`、`/api/live/*`、`/api/export`） |
| `ui/` | 编辑器与只读预览前端页面 |
| `connector/` | Connector 包：`connector-meta.json`、`mcp.json`、`icon.svg`、`skills/wb-cut/SKILL.md` |
| `scripts/` | 构建、CI、素材生成、ffmpeg 下载、基准测试、渲染 agent |
| `tests/` | 单元、任务与渲染端到端测试（`vNN.test.ts` 按版本组织） |
| `vendor/fonts/` | 随仓库分发的中文字体 Noto Sans SC（SIL OFL 1.1） |
| `vendor/ffmpeg/` | FFmpeg 二进制（**不入库**，用脚本获取） |
| `vendor/asr/`、`vendor/ai/models/` | ASR 与抠像模型（**不入库**） |
| `CHANGELOG.md` | 版本历史 |

## 常见问题

**启动时报 `missing vendor\ffmpeg\ffmpeg.exe`**
先执行 `node scripts/get-ffmpeg.mjs`，或设置 `WBCUT_FFMPEG` / `WBCUT_FFPROBE` 指向已安装的二进制。

**导出分辨率比素材低，并收到 `DOWNSCALE` 警告**
平台预设（抖音/小红书/视频号/B站）固定输出 1080p。要保留原始分辨率，导出时不选平台预设，或显式设置 `resolution: "source"`。

**`ASR_UNAVAILABLE`**
没有可用的语音识别后端。装 `vendor/ai/setup-asr.cmd`、放置 whisper.cpp 模型，或改为导入现成字幕文件（`import_subtitles`）。

**`REVISION_CONFLICT`**
工程已被其他进程改动。重新 `video_project_get` 取回最新 revision 再规划，不要用旧 revision 重试。

**`ENGINE_UNAVAILABLE`**
对应的外置能力未配置。错误详情会给出需要的环境变量名与命令契约。

**编辑器打不开 / 端口被占用**
用 `npm run editor -- --port 5173` 换端口；默认由系统分配空闲端口。

**想清掉缓存释放磁盘**
`video_cache_stats` 查看占用，`video_cache_clear` 清理；缓存目录默认为 `<WBCUT_HOME>/cache`。

## 配置（环境变量）

| 变量 | 默认 | 说明 |
|---|---|---|
| `WBCUT_HOME` | 程序目录下 `vedio` | 工作目录（工程、快照、任务、预览、临时、日志） |
| `WBCUT_EXPORTS` | 同 `WBCUT_HOME` | 生成视频的输出目录，默认直接写入 `vedio` |
| `WBCUT_ALLOWED_READ_ROOTS` | 主目录 + 当前目录 | 允许读取素材的根目录，多个用 `;` 分隔 |
| `WBCUT_ALLOWED_WRITE_ROOTS` | 工作目录 | 允许写入导出目标的位置 |
| `WBCUT_FFMPEG` / `WBCUT_FFPROBE` | `vendor/ffmpeg/*.exe` | 自定义引擎路径 |
| `WBCUT_FONT` | `vendor/fonts/NotoSansSC.ttf` | 字幕字体文件 |
| `WBCUT_RENDER_CONCURRENCY` | 1 | 同时渲染任务数 |
| `WBCUT_FFMPEG_THREADS` | 0 | 单任务 ffmpeg 线程数，0 为自动 |
| `WBCUT_WHISPER_BIN` | `vendor/asr/whisper-cli.exe` | 可选 whisper.cpp 可执行文件 |
| `WBCUT_WHISPER_MODEL` | 自动扫描 `vendor/asr` 下 `ggml*.bin` | whisper.cpp 模型；缺失时该后端不可用 |
| `WBCUT_PYTHON` | `python.exe` / `python3` | faster-whisper 解释器；建议设绝对路径，避开 WindowsApps 占位符 |
| `WBCUT_FASTER_WHISPER_MODEL` | `vendor/asr` 下含 `model.bin` 的目录（如 `fw-small`），否则 `small` | faster-whisper 本地模型目录或模型名 |
| `WBCUT_ASR_DEVICE` | `cpu` | faster-whisper 推理设备；`cuda` 需 CUDA 12 运行时，失败自动回退 CPU |
| `WBCUT_EDGE_TTS_TOKEN` | 无（不设则 edge 通道不可用） | edge 朗读的客户端 token，由使用者自行提供；仓库不附带任何默认值 |

faster-whisper 后端需要 Python 3.13+：`pip install faster-whisper`。**PyAV 必须锁 15.x**（`pip install "av==15.1.0"`），16+ 移除了 `metadata_errors` 参数会让推理直接报错。设备默认 `cpu`，避免有显卡驱动但无 CUDA 运行时的机器被 `auto` 误判为 CUDA。

工作目录结构（`vedio/`）：生成视频直接写入根目录；`projects/`（工程 + history 快照）、`snapshots/`、`jobs/`、`previews/`、`tmp/`、`logs/` 为内部数据。

## 工具（132 个）

能力查询 `video_capability_get`；素材 `video_probe` / `video_asset_import` / `video_asset_thumbnail` / `video_asset_waveform`；工程 `video_project_create` / `video_project_list` / `video_project_get` / `video_project_validate` / `video_project_snapshot` / `video_project_delete` / `video_project_duplicate` / `video_project_export` / `video_project_import`；编辑 `video_edit_apply` / `video_edit_undo` / `video_edit_redo`；预览 `video_preview_render` / `video_preview_frame` / `video_preview_strip` / `video_preview_live`（流式实时预览会话）；字幕与语音 `video_transcribe` / `video_subtitle_generate` / `video_subtitle_export` / `video_tts_generate`；素材效果 `video_filter_presets` / `video_sticker_pack` / `video_sticker_add` / `video_text_templates` / `video_text_template_apply`；模板 `video_template_export` / `video_template_apply`；分析 `video_scene_detect` / `video_audio_beats`；导出 `video_export` / `video_export_batch` / `video_export_interchange`（FCPXML/EDL）；任务 `video_job_get` / `video_job_list` / `video_job_cancel`；渲染队列 `video_render_queue_submit` / `video_render_queue_status` / `video_render_queue_cancel`；专业增强 `video_scope_data`（histogram/waveform/vectorscope/parade）、`video_audio_sample_edit`（采样级音频编辑）、`video_asset_pack_import` / `video_asset_pack_list`（本地资产包）、`video_engine_doctor`（外置引擎体检）；预览服务 `video_preview_server_start` / `video_preview_server_status` / `video_preview_server_stop`；素材市场 `video_asset_market_sync` / `video_asset_market_search` / `video_asset_market_install` / `video_asset_market_remove` / `video_asset_market_list`；花字 `video_text_styles`；发布 `video_publish_preflight` / `video_publish`；ASR 诊断 `video_asr_backends`；特效扩展 `video_effect_register`；分镜 `video_shot_plan`；原生抠像 `video_ai_matte_models` / `video_ai_matte_frame`；同步 `video_project_sync` / `video_project_sync_status`。

`video_edit_apply` 支持 64 个 operation：

- 轨道：`add_track`、`set_track_state`、`reorder_track`、`set_canvas_fill`
- 片段：`add_clip`（append/insert/overwrite）、`duplicate_clip`、`trim_clip`、`split_clip`、`move_clip`、`remove_clip`、`ripple_delete`、`set_speed`、`set_speed_curve`
- 画面：`set_transform`（含 fit/anchor）、`set_corner_pin`（四角变形）、`set_keyframes`、`clear_keyframes`、`set_canvas`、`set_color_adjustment`（clip/track/all）、`set_color_management`、`apply_lut`、`set_effect`、`add_effect`、`remove_effect`、`set_effect_range`、`set_visual_fade`、`set_reverse`、`set_body_shape`
- 合成：`set_mask`、`set_blend`、`set_chroma_key`
- 调整图层：`add_adjustment_layer`、`set_adjustment_layer`、`remove_adjustment_layer`
- 动画：`set_animations`、`clear_animations`、`set_clip_animation`
- 音频：`set_audio`、`set_audio_keyframes`、`trim_silence`、`trim_audio_range`、`set_track_solo`、`set_track_bus`
- 文本：`add_or_update_text`、`import_subtitles`、`set_subtitle_style`
- 字幕时间：`split_subtitle`、`merge_subtitles`、`retime_subtitles`、`replace_subtitle_text`
- 转场：`add_or_update_transition`
- 时间线：`link_clips`、`unlink_clips`、`insert_gap`、`close_gap`、`set_markers`、`snap_to`、`freeze_frame`、`detach_audio`、`group_clips`、`ungroup_clips`
- 复合：`create_compound`、`expand_compound`

关键帧通道：`x/y` 用表达式直接驱动，`scale/rotation/opacity/volume` 按表达式或分段实现，`rotate_x/rotate_y` 按工程帧率逐帧求出四角坐标后串联透视滤镜（每帧一次真实投影）；缓动 `linear/ease_in/ease_out/ease_in_out`。曲线变速用分段线性 `setpts` 编译，时长按速度积分求解，音频按子段 `atempo` 链同步。调色支持 16 个参数 + .cube/.3dl/.dat LUT（强度混合）；画面特效 10 种（glitch/shake/old_film/mirror/dreamy/rgb_split/scan_line/zoom_pulse/noise/vignette_flash）；蒙版支持 linear/circle/rect/mirror/heart/star/triangle/polygon（真实几何 + 羽化/旋转/反转，polygon 可设边数、star 可设角数与内径）；抠像用 RGB colorkey；混合模式支持 screen/multiply/overlay/lighten/darken/add。音频支持降噪、变调、变声（robot/echo/deep/chipmunk/telephone）、闪避与导出响度归一。转场：`fade/flash/wipe_*/slide_*/circle_open/zoom_blur` 以及 `push_*/pull_*/whip_*/rotate/blur_fade/glitch/iris/stutter/perspective/bounce`。导出：`video|audio|gif|frames`，H.264/HEVC/VP9/ProRes，MP4/MOV/WebM，CRF/CBR/VBR，码率、硬件编码与平台预设。

## 渲染分段缓存

视频导出时长 ≥5s 时按镜头边界（媒体片段起止、量化到帧）切段渲染，每段以内容哈希缓存到 `vedio/cache/segments`：

- 内容未变的段直接复用，最终用 concat 无损拼接，再与缓存的音频轨混流；
- 修改某条字幕只让与其时间重叠的 1~2 个段失效，其余命中（实测 30s/10 段工程：改动后二次导出约首次的 24%）；
- 音频轨单独渲染并缓存，字幕/画面变化不会触发音频重编；
- 同一进程内的相同内容并发渲染走 single-flight：一个任务渲染，其余任务等待并计为命中；
- 缓存键包含工程内容、导出参数与所用素材签名（`asset.id + size/head/tail hash`），同路径素材内容变化后必然全部 miss；
- 缓存按文件数与体积（400 个 / 6GB）LRU 淘汰；`video_job_get` 的 `result.cache` 返回 `{count,hits,misses}`；
- 容器为 MOV、GIF、纯音频、图片序列或带区间预览时不走分段缓存。

## 实时预览（G-01）

`video_preview_live` 与预览服务的 `/api/live/*` 提供流式实时预览，和逐帧接口的关键差别是「一次建图、持续出帧」：

- 启动时按目标时间切片工程（丢弃窗口前片段、推进源入点、裁剪调整图层），只建一次滤镜图；
- 常驻 ffmpeg 以 `image2pipe` 输出 MJPEG，按序写入有界环形缓存（默认 120 帧，可设 24–600），缓存满时暂停 ffmpeg 读取形成背压；
- `stats` 返回 `first_frame_ms`（首帧时延）、`measured_fps`（出帧吞吐）、`buffered/capacity`、`last_seek_ms`；实测 1080p 双视频轨 + 字幕 + 调色：首帧约 230ms、出帧约 95fps（本机 CPU，非 GPU）；
- 拖动只做「切片 + 重启」，不逐帧重建滤镜图；`/api/live/stream` 按会话帧率节流输出 `multipart/x-mixed-replace`，浏览器 `<img>` 直接播放；
- 音频由同一份切片工程生成 WAV 侧载（`/api/live/audio.wav`，支持 Range），供 `<audio>` 与画面同步；
- 预览与导出共用 `buildRenderPlan`，同帧 PSNR 实测 43.9dB（1280×720，`tests/preview-rt.test.ts` 断言 > 35dB）；逐帧 `/api/frame` 保留为降级路径。

## 交互式编辑器（G-02）

`video_preview_server_start` 返回的 `editor_url`（`http://127.0.0.1:<port>/editor`）是交互式编辑器，和 Agent 走同一条提交路径：

- 时间线：多轨（视频/字幕/音频）、点击选择、Shift/Ctrl 多选、拖动移动、拖两端裁剪、S 分割、Delete 删除、Shift+Delete 波纹删除、滚轮缩放、拖素材到轨道；
- 属性面板：位置/缩放/旋转/不透明度、调色（亮度/对比度/饱和度/色温/暗角）、HSL 分色带（8 个色带 × 色相/饱和/明亮）、色轮（Lift/Gamma/Gain，画布拖动取色相+强度）、RGB 曲线（主/R/G/B，点击加点、拖动调整、右键删点，最多 16 点）、色相-饱和度曲线（色相为横轴，中线=不变，向上加饱和）、四角变形（拖动角点贴合目标，双击重置）、蒙版（类型/宽高/羽化/反转）、变速、音量与声像、入点转场、字幕文本与样式；
- 关键帧：X/Y/缩放/旋转/不透明度按播放头打点，可一键清除；曲线面板按通道（X/Y/缩放/旋转/透明度/音量）拖拽关键点、点击加点、右键删点，并可选择该通道的缓动；
- 每个动作都是 `POST /api/edit` 的一次批量 operation，原子提交、单一 revision、一个撤销单元；冲突返回 `REVISION_CONFLICT`，前端自动重载工程；
- 撤销/重做走 `POST /api/history`（history cursor + snapshot），不维护第二套前端状态；
- 吸附点、片段时长、轨道/片段/关键帧上限、转场清单全部由 `GET /api/editor/state` 下发，前端不复制业务规则；
- 播放用 G-01 实时流（`/api/live/stream` + 音频侧载），暂停/拖动用逐帧 `/api/frame`；
- 导出按钮走 `POST /api/export` 并轮询 `GET /api/job`；
- 已知限制：多机位切换面板未做；网格变形（mesh warp）只到能力表，面板只提供四角；曲线面板按折线显示关键点，实际缓动由通道下拉决定；裁剪时的源入点推进按常量倍速估算，曲线变速片段以服务端校验结果为准。

## 行为约定

- 时间单位为整数毫秒；所有时间入参按工程帧率量化，返回 `snapped` 说明实际值；帧率用有理数（支持 30000/1001）；输出 CFR。
- 音画联动通过 `link_group_id` 生效：move/trim/split/remove/set_speed 会同步组内成员。
- 一次 `video_edit_apply` 批次原子提交：全部成功才写入，只加一个 revision，形成一个撤销单元；失败返回 `operation_index` 且不产生部分修改。
- 预览与导出始终异步；`idempotency_key` 在 project + 工具范围内持久去重；目标文件默认不覆盖，落盘使用原子 no-clobber。
- 删除时间段默认全时间线波纹删除（`ripple_delete`）；删除单个片段保留空隙（`remove_clip`）。
- 变速保持源区间不变，时长联动，默认保留音调（atempo）。
- 交叉淡化使用相邻片段可见区间，后片段与后续片段同步左移，总时长相应缩短。
- 导出分辨率：`resolution` 缺省为 `source`，输出跟随工程内素材最大边（保持画布比例、只放大不缩小、封顶 7680），4K 素材默认导出 4K；显式 `720p`/`1080p`/`2160p` 与平台预设仍按指定值输出，平台预设固定 1080p，高分辨率素材会被降采样并在 `video_project_validate` 返回 `DOWNSCALE` 警告。输出大于素材最大边时仍返回 `UPSCALE` 警告。
- 像素参数（字幕字号/描边/边距、贴纸位置与关键帧、背景模糊半径、文字入场位移）按「输出宽 / 画布宽」等比缩放，任意输出分辨率下构图与预览一致。注意：画布非 1080 级且使用平台预设导出时，这类参数相对尺寸会被修正为正确比例（旧版偏小），属预期行为变更。

## 一键字幕、朗读与智能分析

- `video_subtitle_generate`：对工程内视频片段跑本地 whisper.cpp，直接把 cues 写成字幕轨（`replace` 默认清空目标轨），无需上层转 SRT。未安装 ASR 时返回 `ASR_UNAVAILABLE`，不影响其他功能。
- 词级卡拉OK闭环：`split` 缺省按 `style.karaoke.enabled` 自动选择（开则 `word`），`split: "word"` 或句级结果带 token 时间时，每条字幕同时写入 `words`（相对行起点），预览与导出共用同一份词级时间；括号、停顿（≥700ms）与句子标点断行，标点不制造额外时长。ASR 构建不支持 token 时间时返回 `ASR_WORD_AXIS_UNAVAILABLE`，不静默降级为整块高亮。
- 字幕时间变换同步：`split_subtitle` / `merge_subtitles` / `retime_subtitles` 会同步换算 `words`；`replace_subtitle_text` 改动文本后词级时间失效，会丢弃并在开启卡拉OK时关闭该条并返回 `KARAOKE_WORDS_DROPPED` / `KARAOKE_DISABLED_NO_WORDS` 警告。
- `video_tts_generate`：Windows `System.Speech` 离线合成 WAV，自动登记素材并加入音频轨；非 Windows 返回 `ENGINE_UNAVAILABLE`。
- `video_scene_detect`：FFmpeg `scene` 分数切分镜头，返回 `marks_ms`，可 `write_markers` 写入工程。
- `video_audio_beats`：解码 PCM 做 onset 峰值检测，返回节拍与 BPM 估计，可写入 markers 做卡点。

## 滤镜预设与变声

- `video_filter_presets`：内置 10 组调色预设（通透/日系/电影感/鲜艳/暖调/冷调/复古/黑白/落日/月色），返回可直接传给 `set_color_adjustment` 的 `color` 参数；预设不绑定 LUT 文件。
- 变声通过 `set_audio.voice_effect`：`robot`（50Hz 环调，真实金属边带）、`echo`（双抽头回声）、`deep`/`chipmunk`（重采样+atempo 保时长变调）、`telephone`（300–3400Hz 带通）。

## 贴纸、花字与剪同款

- `video_sticker_pack` / `video_sticker_add`：6 个内置贴纸（新品/热卖/TOP/关注/惊叹/点赞，位于 `vendor/stickers`），也可传自定义图片；自动新建顶层视频轨、默认右上角 25% 缩放 3 秒。
- `video_text_templates` / `video_text_template_apply`：10 组花字/文字模板（标题横幅、干净字幕、花字·金/霓虹/红、角标、引用卡片、片尾、人名条、CTA）。
- `video_template_export` / `video_template_apply`：「剪同款」模板，文本里的 `{{slot}}` 为占位符；`values` 填充文本，`media_map` 按素材 id 或原路径替换素材并重新 probe/签名；缺失槽位给 `TEMPLATE_SLOT_MISSING` 警告。
- 批量导出 `video_export_batch` 为**原子批次**：任一条失败会取消本批已创建任务后报错，不留下半批任务。

## 远程渲染队列

- `video_render_queue_submit` 把导出任务写入共享目录队列（`WBCUT_RENDER_QUEUE`，可指向网络盘），返回 ticket；`video_render_queue_status` / `video_render_queue_cancel` 查询与取消。
- worker：`npm run render-agent`（默认轮询）或 `node dist/src/render/agent.js --once`（处理一个任务）。队列状态由文件原子迁移（pending → running → done/failed/cancelled），支持多 worker 认领与运行中取消。

## 工程管理与并发

- `video_project_delete`：无运行中任务时先把 `project.json` 备份到 `trash/<project_id>/`，再删除工程目录。
- `video_project_duplicate`：深拷贝为新 id，名称追加「副本」，revision 重置。
- `video_project_export` / `video_project_import`：`*.wbcut.json` 包含工程 JSON 与素材路径/签名清单（不打包素材本体）；导入时逐素材校验签名，漂移只产生 warning。
- 工程写入使用跨进程文件锁（wx 原子创建 + 陈旧 pid 接管），撤销历史上限 200 条并滚动清理不再引用的快照。

## 当前不含

人声分离、数字人与智能抠像（未配置外置模型时）、云端素材与团队协作、多机分布式调度（当前队列为共享目录 + 手动启动 agent）、自包含工程包（`.wbcut.json` 只含素材路径与签名，不含素材本体）、GUI。代理媒体与重链、HDR/10bit、透明通道、复合嵌套、多机位与远程队列均已可用，不再列入本节。

已知近似（`video_capability_get` 的 `status.approximations` 逐项可查）：仅 `TRACKING_MANUAL_APPROX`（`video_track_generate` 的 manual 模式，显式降级）；native 模式为真实块匹配，engine 模式依赖 `WBCUT_AI_TRACK_CMD`。legacy 文本渲染器对旋转/竖排/发光/阴影模糊直接返回 `UNSUPPORTED_OPERATION`（切回 `ass` 渲染器即真实）。词级 ASR 时间轴已接入卡拉OK，但构建是否提供 token 时间需运行时校验（缺失返回 `ASR_WORD_AXIS_UNAVAILABLE`）。

已知限制：实时播放仍不在后端边界内（异步取帧协议见 `src/preview/server.ts`）；内置跟踪为块匹配，跟踪框离开画面或目标剧烈变形时需要 manual 锚点兜底；转场视觉为独立实现，但不追求与其它软件逐像素一致。

## 许可与开源

本项目代码以 **MIT** 许可发布（见 `LICENSE`）。第三方组件许可见 `THIRD-PARTY-NOTICES.md`。

### 仓库不含以下内容（均已 `.gitignore`）

| 内容 | 原因 | 获取方式 |
|---|---|---|
| `vendor/ffmpeg/` | GPLv3 二进制，随仓库分发需履行 GPL 义务 | `node scripts/get-ffmpeg.mjs` |
| `vendor/asr/`、`vendor/ai/models/*.onnx` | 大模型体积超 GitHub 单文件上限 | `vendor/ai/setup-asr.cmd` 自动获取；u2net 权重许可未经原作者明确声明，商用前请自行核实 |
| `vendor/pyenv/` | Python 虚拟环境，含受 NVIDIA EULA 约束的 CUDA/cuDNN 库 | `python -m venv vendor/pyenv` 后按 `requirements` 安装 |
| `vedio/`、`vedio-work/` | 本机拍摄素材与工程数据（个人隐私） | 自行使用 `WBCUT_HOME` 指定目录 |

### 分发注意

- 若你把 FFmpeg 二进制与本项目**一起分发**，需自行满足 GPLv3：提供对应源码或有效书面要约、附完整许可文本。本仓库只通过命令行子进程调用 FFmpeg，未链接其代码，因此本项目代码可保持 MIT。
- H.264 / H.265 / AAC 涉及第三方专利池，本项目不提供专利授权。
- `provider=edge` 的朗读通道调用微软非公开在线接口，**默认关闭**，需 `WBCUT_ALLOW_EDGE_TTS=1` 显式启用，并自备 `WBCUT_EDGE_TTS_TOKEN`（仓库不附带该值）。该通道未获微软授权，启用后的合规责任由使用者承担。
- 请勿向仓库提交真实人物拍摄素材、第三方音乐音频或第三方 UI 截图。
- 文中提及的第三方产品名称与商标归各自权利人所有，本项目仅作功能对照说明，与其无关联、无背书关系。