FableCut

# FableCut **一个可由 AI 代理驱动的浏览器视频编辑器** FableCut 是一个类似 Premiere 的非线性视频编辑器，完全在您的浏览器中运行，并将其整个时间线作为一个 JSON 文档公开。您可以手动编辑，从 UI 编辑，或者让 AI 代理（Claude Code、Claude Desktop 或任何支持 MCP/REST 的代理）为您剪辑视频，同时实时更新时间线。 零 npm 依赖。一个 `node server.js` 命令即可运行。  ## 为什么它很有趣 大多数“AI 视频”工具都将编辑隐藏在 API 后面。FableCut 则相反：**项目文件就是接口**。`project.json` 描述了媒体、剪辑、音轨、特效、关键帧和过渡 —— 任何可以写入 JSON 的进程都可以编辑视频，并且开放的浏览器 UI 通过服务器发送事件在约 150 毫秒内热重载。人类和代理可以同时在同一时间线上工作。 ## 功能 **编辑** - 4 条视频轨道 + 3 条音频轨道，支持拖拽、修剪、对齐、撤销/重做 - **时间线多选** — 橡皮筋选择（在空白轨道区域拖拽），<kbd>Ctrl/Cmd/Shift+click</kbd> 添加/删除剪辑，<kbd>Ctrl+A</kbd> 选择全部，<kbd>Esc</kbd> 取消选择。拖动任意选定剪辑以移动整个组；<kbd>Delete</kbd> 删除所有选定剪辑；<kbd>S</kbd> 在播放头处分割所有选定剪辑。检查器显示“N 个剪辑已选择”的横幅。 - 节拍和提示标记（在播放过程中按 <kbd>M</kbd> 键在节拍处标记）并支持边缘吸附 - 剪辑上显示解码后的音频波形 - 画布宽高比预设（16:9，9:16 卷轴，4:5，1:1）+ 安全区域参考线 **外观** - 12 种一键滤镜预设（电影风格、青橙色调、黑色电影、复古风格、赛博朋克风格……） - **调整层** — 一个剪辑可分级其下所有内容，类似 Premiere 风格 - 完整的分级控制：亮度/对比度/饱和度/色调，**温度和色度**，模糊，灰度/棕褐色/反转，**晕影**，动画 **胶片颗粒** - 混合模式（屏幕、乘法、叠加……），拟合模式（包含/覆盖/拉伸），每边裁剪，圆角半径，水平/垂直翻转 - **色键控** （绿幕）具有容差/柔和度 + 溢出抑制 - **AI 背景移除** （人像抠图，在浏览器中通过 MediaPipe 实现） **运动** - 约 25 个属性的关键帧动画，支持缓动 - **速度坡道** — 关键帧 `speed`，引擎实时调整视频和导出音频混合（快速进入慢动作的转场效果） - **相机抖动** 和 **RGB 分离/色差**，两者均可动画化 - 17 种过渡效果：渐入渐出、滑动、擦除（4 个方向）、缩放、虹膜、旋转、模糊、**故障**、**弹出** **文本** - 动态字幕：打字机、逐字弹出、逐字滑动、卡拉 OK、**逐字母弹出**、**波浪**、**弹跳**、**抖动** - **霓虹灯光**，呈现 TikTok 字幕风格 - 字体编辑器：系统字体、直接替换自定义字体（`library/fonts/`），以及 **任何 Google 字体名称** — 自动加载 - 渐变填充、轮廓、背景药丸、字母间距、行高、权重、斜体、大写字母、Alignment、软阴影 **动画 SVG 剪辑** - 一流的 `svg` 剪辑类型：CSS-`@keyframes` 动画 SVG 在预览和导出时 **帧准确性** 渲染（合成器在任意时间冻结动画）。代理可以创作自己的加层 — 较低的 thirds、彩带、火花 — 作为纯 `.svg` 文件。包含启动器。 **重制参考视频** - 提供参考编辑（您喜欢的视频片段），并获取 **编辑蓝图**：镜头边界、音乐节拍 + BPM、响度曲线、每镜头能量、转场 — 加上参考的 **音乐轨道提取** 到您的媒体中，准备使用自己的素材重建相同的创意。零额外依赖项（ffmpeg 解码；onset/tempo 检测是纯 Node）。`node analyze.js ref.mp4`，`POST /api/analyze`，或 `fablecut_analyze_reference` MCP 工具。 **资产库** - `library/` 文件夹在 UI 中显示为选项卡：**元素** （叠加层艺术）、**音效**、**SVG** — 放入文件，打开编辑器实时刷新 **导出** - 快速导出：浏览器渲染每个帧 + 离线音频混合，ffmpeg 编码帧准确的 CRF-18 MP4（如果您切换选项卡，仍继续渲染） - 当 ffmpeg 无法使用时，实时 MediaRecorder 备用 ## 快速开始 ```bash https://github.com/ronak-create/FableCut.git cd FableCut node server.js # → http://localhost: ``` 需求：**Node 18+** 和基于 Chromium 的浏览器。**ffmpeg on PATH** 是可选但推荐的（快速导出 + 上传重混音）。AI 背景移除会在首次使用时从 CDN 获取其模型。 将媒体放入窗口 `./media/`），将剪辑拖到时间线，导出。 ## 使用 AI 代理驱动 代理所需的一切都在 **[CLAUDE.md](CLAUDE.md)** — 完整的模式、语义和配方。将任何有能力的模型指向该文件，它可以端到端地操作编辑器。 三种等效的控制界面： 1. **MCP** （适用于 Claude Code / Claude Desktop 最佳）— 注册捆绑的零依赖 MCP 服务器一次： ```bash claude mcp add -s user fablecut -- node "<path-to>/fablecut/mcp-server.js" ``` 工具：`fablecut_status` （自动启动编辑器），`fable`，`fablecut_get_project`，`fablecut_set_project`，`fablecut_patch_project`，`fablecut_import_media`，`fablecut_`。 该界面 **设计时即考虑了标记效率**：代理通过小的操作修补时间线（`fablecut_patch_project`）而不是往返整个文档，读取紧凑的单行每剪辑摘要（`fablecut_get_project {compact:true}`），并仅获取他们需要的手动部分（`fablecut_docs {section:"props"}`）。 2. **文件** — 读取 `project.json`，修改，更新 `revision`，写入。UI 实时重载。 3. **REST** — `GET/PUT /api/project`，`POST /api/upload`，`GET /api/library`，`/api/events` 的 SSE。有关完整列表，请参见 CLAUDE.md。 示例：询问 Claude Code *"将这六个剪辑剪辑到节拍标记，添加青橙色分级，在顶部添加逐字弹出字幕，并在每个剪辑处添加哨声"* — 并观看时间线自行重建。 或者，给它一个参考：*"这里有一个我喜欢的视频片段 — 分析它，并用我的剪辑重制它，使用相同的音乐"*。代理调用 `fablecut_analyze_reference`，获取蓝图（剪辑、节拍、BPM、能量、转场、提取的音乐），并使用您的素材逐镜头重建结构。 **冲突安全的并发编辑**：UI、MCP 工具和直接 `project.json` 写入都同意一个 `revision` 计数器。如果您在 UI 中编辑剪辑时，代理正在执行任务，代理的下一次写入将被拒绝（REST API 返回 409 或 `fablecut_set_project` 返回冲突错误），而不是静默覆盖您的更改。UI 类似地检测到代理写入何时取代了尚未保存的本地调整，并通过 Toast 通知您，而不是静默丢弃。 ## 项目布局 ``` server.js 零依赖 HTTP 服务器：静态托管、REST API、SSE、ffmpeg 导出管道 app.js 编辑器：时间线 UI、合成器、关键帧、文本引擎、SVG 光栅化、色键控、导出器 index.html 单页 UI style.css 黑色编辑器主题 mcp-server.js stdio MCP 服务器，向 AI 代理公开编辑器 analyze.js 参考视频分析器：镜头、节拍/BPM、能量、转场、音乐提取（模块 + CLI） CLAUDE.md 代理手册（模式 + 配方）— 同时由 fablecut_docs 提供 project.json 您的时间线（首次运行时创建；gitignored） media/ 项目素材（gitignored） analysis/ 缓存的编辑蓝图来自 /api/analyze（gitignored） library/ 默认资产：elements/ sfx/ svg/ fonts/ exports/ 完成渲染（gitignored） ``` ## 编写动画 SVG 叠加层 SVG 使用纯 CSS `@keyframes` 动画。一个约定：从不硬编码 `animation-delay` — 而是设置 `--d: 0.4s`，然后合成器驱动时间通过暂停所有动画并重新设置其延迟。完整的规则 + 骨架在 [CLAUDE.md](CLAUDE.md#authoranimated-svgs-the-svg-clip-kind) 中；[`library/svg/`](library/svg有工作示例。 ## 备注 - 仓库自带 **20 种 Google** （`library/fontsOFL — 见 `LICENSES.md`）和一套自行制作的 SVG 叠加层和动画元素（`library/elements/`，`library/svg/`，类似仓库其余部分采用 MIT 许可） - `library/sfx/` 由您填充（gitignored）：音效站点通常不允许在公共仓库中重新分发其文件，因此 FableCut 不这样做 — `library/sfx/README.md` 列出了来源。 - 导出中运行，因为合成器 *即是* 浏览器；代理要求您单击导出（或使用 ffmpeg 直接从 `media/` 渲染）。 ## 许可证 [MIT](LICENSE)