fablecut

这是什么？适合谁？

FableCut（MIT，JavaScript，零 npm 依赖，node server.js 一条命令启动）是一个跑在浏览器里的 Premiere 风格非线性视频编辑器，但它的真正卖点在于：整个时间线项目就是一个 JSON 文档（project.json），人和 AI Agent 可以同时编辑同一个时间线。

多数”AI 视频工具”把剪辑过程藏在 API 后面。FableCut 反其道而行：project.json 描述媒体、轨道、片段、特效、关键帧和转场——任何能写 JSON 的进程都能剪视频。你在浏览器里拖拽，Agent 在另一头改 JSON，UI 通过 SSE（Server-Sent Events）在大约 150 毫秒内热重载，你能实时看到 Agent”动手剪”的过程。

适合谁：

• 想让 Claude Code / Claude Desktop / 任意 MCP 客户端替自己剪视频、又想全程看得见、随时插手修正的开发者和创作者
• 做 Reels / 短视频批量生产流水线、需要程序化剪辑 API 的人（REST 直接可调）
• 想要一个零依赖、一条命令就能跑起来给自己人用的本地剪辑工具的团队

不适合谁：

• 只想要”一句话出片”全自动视频生成、不想看时间线的人（这是剪辑器不是生成器；生成类的需求看 vox-director 这类 Agent Skill）
• 需要专业达芬奇级调色/多机位剪辑的重度剪辑师

使用前提：Node 18+ 和一个 Chromium 系浏览器；ffmpeg（可选，推荐装上，快速导出和上传转封装需要它）；AI 抠像首次使用会从 CDN 拉模型。

准备工作

1. 环境：Node 18+；Chromium 系浏览器（Chrome/Edge）；ffmpeg 加入 PATH（可选但推荐）
2. 获取：git clone https://github.com/ronak-create/FableCut.git
3. 成本：MIT 开源免费，无任何付费项；自用纯本地
4. 时间：克隆+启动 2 分钟；接上 Agent 跑通第一条自动剪辑 10 分钟
5. 前置知识：会用命令行；想走 Agent 驱动需要会用 Claude Code 或任意 MCP 客户端
6. 替代方案：Remotion（代码即视频但非交互编辑器）、Shotcut（传统桌面剪辑无 Agent 接口）、直接调 ffmpeg 脚本（无 UI 无热重载）

快速上手（3 步）

第一步：启动编辑器

git clone https://github.com/ronak-create/FableCut.git
cd FableCut
node server.js        # → http://localhost:7777

零依赖安装、无构建步骤。默认只绑定 127.0.0.1（v1.3.1+ 安全默认）；想在局域网另一台设备用需显式 HOST=0.0.0.0 FABLECUT_ALLOWED_HOSTS=<your-ip> node server.js。

把媒体拖进窗口（或放 ./media/，或用 + URL 粘贴 HTTPS 视频地址导入），拖到时间线上，剪，导出。

预期产出：浏览器里一个可用的多轨剪辑器，导出 MP4。

第二步：（可选）装成 Claude Code 插件

/plugin marketplace add ronak-create/FableCut
/plugin install fablecut@fablecut

这一步会自动注册 MCP server 并装上两个技能（edit-video 和 remake-reel）。你的时间线和素材放在插件自己的数据目录里，插件升级不会动它们。Node 18+ 和 ffmpeg（可选）仍然需要在机器上。

预期产出：Claude Code 里可以 /plugin 看到 fablecut，Agent 具备驱动编辑器的能力。

第三步：把 Agent 接上编辑器

三个等价控制面，按你的客户端选一个：

MCP（Claude Code / Claude Desktop 最佳路径）——注册自带的零依赖 MCP server：

claude mcp add -s user fablecut -- node "<path-to>/FableCut/mcp-server.js"

其他 MCP 客户端（如 OpenCode）等价地注册同一个 stdio server（node /absolute/path/to/FableCut/mcp-server.js）。FableCut 也已发布在 MCP 官方 registry（io.github.ronak-create/fablecut），支持 MCPB 的客户端可以直接装 fablecut.mcpb 打包文件。

REST——GET/PUT /api/project、POST /api/upload、POST /api/import-url、GET /api/library、GET /api/export/profiles，事件流在 /api/events（SSE）。任何语言写 HTTP 就能剪。

纯 JSON——直接读改 project.json（想把工程放别处就设 FABLECUT_DATA_DIR，它会把 project.json、media/、exports/、analysis/、library/ 全部挪到你指定的目录）。

Agent 的完整操作手册在仓库根的 CLAUDE.md——project.json 的完整 schema、语义和操作配方都在里面，把任意够强的模型指向这个文件它就能端到端操作编辑器。

预期产出：你在编辑器里拖一个片段的同时，Agent 能通过 MCP 改转场、加字幕、调滤镜，UI 实时刷新。

常见踩坑（症状 → 原因 → 解决）

1. 局域网设备打不开页面。症状：另一台电脑访问 http://<ip>:7777 无响应。原因：v1.3.1+ 默认只绑 127.0.0.1。解决：显式 HOST=0.0.0.0 FABLECUT_ALLOWED_HOSTS=<your-ip> node server.js——这是有意的安全默认，不是 bug。
2. 导出慢且占浏览器。症状：Fast 导出时切到别的标签页渲染还继续但没加速。原因：Fast 导出是浏览器逐帧渲染 + 离线混音，再由 ffmpeg 编码 JPEG 帧序列。解决：装 ffmpeg 并走 WebCodecs 导出（浏览器硬件编码 H.264，服务器转封装），速度更快；在导出对话框里选。
3. 设置了 Export frame 后 WebCodecs/Realtime 导出不可用。原因：导出画框（exportFrame）与硬件编码路径不兼容，官方在 UI 里直接禁用。解决：设了画框就用 Fast 导出；16:9 画布重切成 9:16 的需求本来就是 Fast 导出裁切。
4. Agent 导入的 URL 视频画布被污染、导出报错。原因：FableCut 故意不把远程 URL 存成 media.src——那会 taint canvas 弄坏导出。解决：走 fablecut_import_media（MCP 工具）或 POST /api/import-url，它会先下载进 ./media/ 再引用本地文件；远程 SVG 会被直接拒收。
5. 以为 MCP 没注册成功。症状：Claude 里 Agent 说没有 fablecut 工具。原因：claude mcp add 用了相对路径或 FableCut 目录后来移动了。解决：注册时用绝对路径 claude mcp add -s user fablecut -- node "C:/绝对路径/FableCut/mcp-server.js"；或干脆走插件方式让插件管理器管路径。
6. 多声道视频（5.1/7.1）时间线出现一排 A 轨。原因：不是 bug——每个声道一条链接音轨（最多 16 条），换媒体时会按新素材声道数自动增删。解决：导出时它们会正确混音，不需要手动清理；嫌多就用立体声素材。

初级用法

• + URL 导入：粘一个 HTTPS 视频链接直接进 Project bin，适合给 Agent 喂参考素材再让它照剪。
• J/K/L 梭动播放：监看器里 J 倒放、L 快进（1×→1.5×→2×→4×）、K 暂停归 1×，只用预览不影响导出，粗剪时非常快。
• g / ⇧G 找洞补洞：g 跳到下一个全轨空隙，⇧G 把洞后面所有片段左拉闭合——批量清理 Agent 剪出来的空段。

高级玩法

• Remake a reference video：给 Agent 一条你喜欢的成片（reel），它返回一份剪辑蓝图——镜头边界、音乐节拍 + BPM、响度曲线、逐镜头能量、drop 点，还会把参考视频的音乐轨单独抽出来放进你的媒体库。零额外依赖（ffmpeg 解码，节拍/速度检测是纯 Node 实现）。入口：node analyze.js ref.mp4、POST /api/analyze 或 MCP 工具 fablecut_analyze_reference。
• Agent 自己写 SVG 动画层：SVG 是一等公民 clip 类型，CSS @keyframes 动画在预览和导出里都帧精确。让 Agent 写 lower-thirds、彩带、星光的 .svg 覆盖层（自带入门示例）。
• JSON 驱动批量流水线：REST + PUT /api/project 让你用 Python/任何脚本批量生成剪辑工程——批量出 Reels 的正确姿势：一个模板 project.json，脚本替换媒体引用与文案，循环导出。
• 速度坡道（speed ramp）：给 speed 属性打关键帧，引擎对视频和导出音轨做时间重映射——快进接慢动作的 reel 手法，Agent 也能用 JSON 写出来。

小技巧

1. 别低估 CLAUDE.md：把任意模型的上下文指向它，Agent 就能学会整个 schema——比读源码快得多。
2. 想把工程和代码分开就设 FABLECUT_DATA_DIR，升级/换机器时只需要搬那个目录。
3. 转场 Alt+t 会根据播放头在选中片段上的位置自动加 in 或 out 转场，上次用的转场会被记住当默认。
4. 音频 Hold 开关：暂停时循环播放播放头处一帧音频，逐帧对音画时特别有用（剪辑点听感检查）。
5. 用 ⇧Z（zoom to selection）框选所有选中片段，多选编组时比一次次点击快。

常见问题 FAQ

Q1: 它和 Remotion 有什么区别？

A: Remotion 是”用 React 写视频”的渲染框架，产出是代码仓库，没有交互式编辑界面。FableCut 是交互式编辑器 + JSON 项目文件作为接口：人可以随时拖拽接管，Agent 改的是同一份 project.json，SSE 热重载让人机共编一个时间线。两者可以互补（FableCut 快速试剪，Remotion 最终批产）。

Q2: 不装 ffmpeg 能用吗？

A: 能。Fast 导出、WebCodecs 导出不可用时会退到 Realtime MediaRecorder 兜底导出。但 ffmpeg 推荐：快速导出的 JPEG 帧编码、上传转封装、参考视频分析、抠像等功能都靠它。

Q3: 会被收钱吗？有云依赖吗？

A: 不会、基本没有。MIT 开源，服务纯本地（127.0.0.1）。唯一的外部拉取是 AI 背景移除首次使用时从 CDN 下载 MediaPipe 模型；URL 导入是你自己指定的 HTTPS 地址。

Q4: 支持哪些导出格式/帧率？

A: 项目帧率 24/25/30/50/60（非预设值显示为 Custom）；画布预设 16:9、9:16（reels）、4:5、1:1；导出 H.264 MP4。Fast 导出走 JPEG 帧序列 + ffmpeg 编码（可选编码 profile，encoding-profiles.json），WebCodecs 走浏览器硬件编码。

Q5: 数据安全吗？素材会被上传吗？

A: 服务器只绑 127.0.0.1，素材、工程、导出全在本地目录（默认仓库内，可用 FABLECUT_DATA_DIR 挪走）。URL 导入是你主动给的地址。开源可自审，无遥测。

Q6: Windows 能跑吗？

A: 能。Node 18+ 跨平台，ffmpeg 有 Windows 构建；项目主体是 JavaScript + 浏览器 API，没有平台锁。

免责声明

本文基于公开资料整理（GitHub README 英文全文与仓库 API 元数据，核验日期 2026-09-15），AI 辅助生成，未在本站环境实际启动编辑器或验证 MCP/REST 驱动剪辑。热重载延迟（~150ms）、导出速度等以官方 README 声明为准，未逐一实测。仓库创建于 2026-07-06，处于活跃快速迭代期（最近 push 2026-09-14），功能细节可能随版本变化。

参考链接

• GitHub 仓库 ronak-create/FableCut
• CLAUDE.md（Agent 操作手册）
• 中文 README
• MCP 官方 registry 页面
• DeepWiki 代码库导览
• Discord 社区