WB Cut

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

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

• 本地优先：素材、工程、缓存、导出全部留在本机，默认不联网，不调用云端模型。

• 能力诚实：video_capability_get 返回的能力开关与实际实现同源；模型或外置命令缺失时返回 ENGINE_UNAVAILABLE，不假装可用。

• 原子编辑：一次批量操作只产生一个 revision，失败不留半成品；撤销/重做走完整快照历史。

• 导出不降级：resolution: "source" 跟随素材原始分辨率，发生降采样会返回 DOWNSCALE 警告。

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

功能概览

Related MCP server: CapCut & Google Flow MCP

环境要求

安装

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。

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

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

可选组件，按需安装：

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

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

快速开始

1. 启动 MCP Server

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

2. 接入 MCP 客户端

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

{
  "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. 打开浏览器编辑器

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 表示实际生效值。

目录结构

常见问题

启动时报 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。

配置（环境变量）

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）

分发注意

• 若你把 FFmpeg 二进制与本项目一起分发，需自行满足 GPLv3：提供对应源码或有效书面要约、附完整许可文本。本仓库只通过命令行子进程调用 FFmpeg，未链接其代码，因此本项目代码可保持 MIT。

• H.264 / H.265 / AAC 涉及第三方专利池，本项目不提供专利授权。

• provider=edge 的朗读通道调用微软非公开在线接口，默认关闭，需 WBCUT_ALLOW_EDGE_TTS=1 显式启用，并自备 WBCUT_EDGE_TTS_TOKEN（仓库不附带该值）。该通道未获微软授权，启用后的合规责任由使用者承担。

• 请勿向仓库提交真实人物拍摄素材、第三方音乐音频或第三方 UI 截图。

• 文中提及的第三方产品名称与商标归各自权利人所有，本项目仅作功能对照说明，与其无关联、无背书关系。