cuttingfloor

cuttingfloor

面向 Agent 的无头视频编辑器，以 MCP 服务的形式提供。Agent 导入素材，使用细粒度编辑工具在时间线上剪辑，每次编辑后查看结果、检查并导出文件。

• 每次编辑都会返回一个新的时间线 ID，以及结果的预览图像。时间线不可变，因此只需使用旧 ID 即可返回之前的版本。
• 不会为你保存任何内容。 时间线、媒体和输出都存放在缓存中，并受时间限制（时间线为 24 小时，媒体和导出文件为 7 天）。请导出以保留作品。
• 一个 Docker 镜像即可在本地（免费）或托管环境中运行。镜像内置引擎（FFmpeg、MLT）；你只需安装 Docker。

状态：第 3 阶段进行中。导入、时间线、片段编辑、时序调整（速度、变速、倒放、定格、卷动/滑动/平移、范围提取、嵌套时间线）、转场、标题和字幕、音频（增益、声像、淡入淡出、闪避、响度）、效果（色彩、LUT、模糊、色度键等；均衡器、压缩器、降噪、音高）、分析（转录、节拍、人脸、跟踪）、合成（变换、关键帧、蒙版、混合模式、动画）、动态图形和 HTML 静帧（沙盒隔离）、遮罩、本地配音及定时词语、人物抠像、预览、精确 QA 检查以及 H.264/ProRes 导出，均已实现端到端运行。接下来将推出提供商工具（ElevenLabs、OpenAI）和 NLE 互通。

运行

docker compose up -d          # local mode: one node on 127.0.0.1:8787, plus the motion sandbox

Compose 会从同一个镜像启动两个容器：cuttingfloor（服务）和 cuttingfloor-motion，后者是用于渲染 Agent 为 create.motion 和 create.still 编写的 HTML 的沙盒。沙盒无法连接外部网络，没有数据卷和任何功能权限，文件系统为只读，并且 CPU、内存和进程数量均受固定限制。Chromium 自身的沙盒也会在其中保持启用，并使用 tools/motion/seccomp.json 中的 seccomp 配置文件（Docker 默认配置加上命名空间创建权限）。请从本仓库的检出目录运行 compose，以确保该文件存在。

通过 Streamable HTTP 连接 MCP 客户端：

{ "mcpServers": { "cuttingfloor": { "url": "http://127.0.0.1:8787/mcp" } } }

也可以通过 stdio 连接，适用于只能启动命令的客户端。stdio 进程会将请求转发到正在运行的容器，因此客户端退出后，耗时较长的导出仍会继续：

{ "mcpServers": { "cuttingfloor": { "command": "docker", "args": ["exec", "-i", "cuttingfloor", "cuttingfloor", "mcp"] } } }

文件夹（在 .env 中设置，文件放在 compose.yaml 旁边，参见 .env.example）：

在你的计算机上	在容器中	用途
$CUTTINGFLOOR_MEDIA（默认为 ~/Movies）	/media/videos（只读）	视频素材。使用 {"path": "/media/videos/clip.mp4"} 导入
$CUTTINGFLOOR_EXPORTS（默认为 ~/cuttingfloor/exports）	/exports	已完成的导出文件
Docker 卷 cuttingfloor-data	/data	时间线、代理文件、任务（均受时间限制）

提供商密钥由你自行提供，并放在同一个 .env 文件中，或使用 Docker secrets（/run/secrets/<name lower-cased>）。密钥不会经过任何工具；video://server/health 只会显示各密钥是否已设置。create.lipsync 需要来自 sync. labs 的 SYNC_API_KEY（Settings → API keys）；每发送一秒内容，费用都会记入你的账户。添加密钥后运行 docker compose up -d。

镜像中包含 /samples/sample.mp4（带音调的 10 秒测试图案）和 /samples/card.png，无需挂载任何内容即可进行试用。

在 Mac 上使用 Docker Desktop 时，请提高内存限制以处理较长的 4K 时间线；绑定挂载的素材读取会通过 VirtioFS。在 Linux 上，请在首次启动前创建导出文件夹，以确保该文件夹归你所有。

Agent 如何使用

1. 对每个文件调用 media.import。这是长时间运行的操作：对于支持 MCP Tasks 的客户端，会创建一个任务；否则会返回 job_id，可用 job.get 轮询。任务报告 processing 后，media_id 即可使用。
2. media.analyze 会将媒体转换为 Agent 可编辑的数据：transcript（包含每个词及其时间；在 CPU 上运行 whisper.cpp，模型只需下载一次）、beats（节奏、节拍、重拍）和 faces（随时间变化的人脸框）以及 track（跟踪一个区域）。然后使用 clip.add {source: {words: [i, j]}} 按词剪切，并使用 caption.add {in_clip: {clip_id, segments}} 添加字幕，时间以媒体中的秒数为准。media.seek 可通过普通文字查找片段，让 Agent 无需观看整段视频：提供类似 {too_dark: "人脸太暗，无法辨认眼睛", demo: "产品仪表板占满屏幕"} 的条件，它会返回视频中或正在渲染的剪辑中符合各条件的片段，并提供每段的最佳帧。可用于检查质量、查找某内容的起始位置、挑选镜头、发现变化或寻找添加标题的空白区域。TypeSafe Jev 会评估这些帧，需要 TYPESAFE_API_KEY。
3. 使用序列创建 timeline.create（{width, height, fps: {num, den}}）。
4. 编辑：使用 clip.add、clip.trim（用 side 设置 J/L 剪辑）、clip.split、clip.move、clip.remove（用 ripple）、clip.link、track.*，或使用 edit.batch 一次应用多项编辑；对于批次中较早创建的 ID，使用 {"$ref": "ops[0].clip_id"}。
5. 时间处理：使用 clip.set_speed（恒定速率、速度渐变 curve、reverse；保留音高）、clip.freeze、clip.roll、clip.slip、clip.slide、clip.replace，以及 range.extract / range.lift 一次从所有轨道中剪切一段内容。clip.add {nested_timeline_id} 可将整个时间线嵌套为一个剪辑。
6. 转场：在一个剪辑之后的剪切点使用 transition.add：可添加溶解、淡入黑场或白场、擦除、滑动、推入、缩放、光圈和旋转转场。关联音频会在同一剪切点交叉淡化。默认情况下，剪辑会重叠，后面的剪辑会向前移动；mode: "handles" 会使用剪切点之后的源素材，且不移动任何内容。
7. 文字：title.add 和 caption.add（使用带词语时间信息的片段，或使用 SRT/VTT）会在视频轨道上添加文字，并由 libass 渲染：可设置字体、大小、颜色、描边、阴影、文本框、卡拉 OK 效果和词语高亮，也可设置打字机和逐词显示效果。text.set 可一次性为多项文字重新设置样式。字体列表见 video://catalog/fonts；使用 media.import 导入自己的 .ttf/.otf 文件，并通过 font_media_id 使用。
8. 音频：audio.set_gain（以 dB 为单位，可用关键帧调整音量）、audio.set_pan、audio.fade 和 audio.set_master（设置整个混音的增益和限制器上限）。音频编辑会以波形图像预览，并显示测得的响度。
9. 效果：可对单个剪辑、轨道上的每个剪辑或整个时间线使用 filter.add：色彩（亮度、对比度、饱和度、曝光、色温、曲线、导入为 .cube 的 LUT）、模糊、锐化、暗角、颗粒、故障、像素化、色度键；声音效果包括均衡器、压缩器、降噪、去齿音、对话增强、混响、回声和音高。adjustment.add 会添加一个剪辑，其效果会在播放期间影响下方的所有内容。带参数的效果列表见 video://catalog/effects。
10. 合成：将剪辑放在更高的视频轨道上，然后使用 clip.set_transform（位置、缩放、旋转、不透明度、裁剪、翻转、适配；任意数值都可添加带缓动的关键帧）、clip.set_mask（矩形、椭圆、线性、镜像、心形、星形、多边形）、clip.set_blend 和 clip.set_animation（入场、退场和循环预设）。可用名称作为资源列于 video://catalog/{name}。
11. 创建：create.motion 会将任意动画 HTML 精确到帧地渲染为带透明通道的视频：CSS 动画和过渡、Web Animations API、SVG、canvas 或在 requestAnimationFrame 中绘制的 WebGL、计时器，或页面定义的 window.__seek(seconds)，都会在虚拟时钟上运行，由渲染器逐帧推进。anime.js、three.js、Lottie 和 D3 从 lib/ 加载（<script src="lib/anime.umd.min.js">）。create.still 会将 HTML 页面渲染为 PNG，create.matte 会生成纯色或渐变图片。每个工具都会返回可供 clip.add 使用的 media_id；相同的配方会返回相同的媒体。页面无法访问网络，因此图片和字体需通过 assets（已导入的媒体）提供，并以 assets/<name> 引用。create.voiceover 会在 CPU 上使用 28 种 Kokoro 语音之一朗读英文文本（约 350 MB 的模型只需下载一次），并为每个词标注时间，因此 caption.add {in_clip} 可精确添加字幕。create.cutout 会移除主体背后的背景：any（BiRefNet；适用于产品、动物、物体和人物；图片的默认选项；Docker 需要约 3 GB 可用内存）或 people（MODNet；速度足以处理视频，视频的默认选项），并保留声音。create.lipsync 可让镜头中的人物说出新的台词：提供视频、新语音（重新录制的台词或旁白）以及要修改的视频片段，sync. labs 会根据音频重新绘制人物嘴部，使之匹配。使用你自己的密钥（本地使用 SYNC_API_KEY，托管环境使用 X-Cuttingfloor-Key-Sync 请求头）。只会发送指定片段；返回的也是该片段，可叠加到原视频上。
12. 查看：在任意编辑操作中设置 preview: "inline" 即可返回图像；render.frames 可返回最多 16 帧的联系表，或最多 4 张全尺寸缩略图（size: "full"）。
13. qa.check 会测量渲染结果：间隙、离线媒体、帧数、响度和真峰值，以及符合你所设定条件的黑屏和静音片段。只提供事实，不给结论。
14. 使用预设调用 export.video：web_1080p_h264、master_prores_422hq、social_9x16_h264、web_1080p_av1、gif、audio_wav_48k 或 audio_mp3；并可通过 overrides 设置尺寸、帧率、比特率或质量（video://catalog/presets）。结果会包含一个带签名的下载 URL；在本地还会将文件保存到 exports 文件夹。
15. export.timeline 可将剪辑交给其他编辑器，格式包括 FCPXML（Final Cut Pro、Resolve）、OTIO（Premiere、Resolve）或 CMX 3600 EDL；也可将字幕导出为 SRT 或 VTT，并提供 warnings 说明格式无法保留的内容。media: "collect" 会将媒体一并打包为 ZIP 文件。timeline.get 会保留无损副本。 时间以序列帧率下的整数帧计，结束帧不包含在内。timeline.get 以 JSON 格式返回完整时间线；时间线过期后，timeline.load 可将其恢复。video://server/health 会报告引擎版本和限制。

托管模式

使用 CUTTINGFLOOR_MODE=hosted 的同一镜像：不支持导入本地路径（仅限 URL），没有导出文件夹，而且每个请求都需要 Authorization: Bearer <key>，密钥来自 CUTTINGFLOOR_API_KEYS（owner:key,owner2:key2，或 Docker 密钥 cuttingfloor_api_keys）。每个密钥对应的所有者拥有独立的时间线、媒体和作业。必须设置 CUTTINGFLOOR_PUBLIC_URL：下载链接根据它生成；未设置时，服务不会启动。

托管模式下，提供商密钥由客户端提供，绝不会来自服务器环境：MCP 客户端在其服务配置中将每个密钥作为标头发送，格式为 X-Cuttingfloor-Key-<Provider>。例如，调用 create.lipsync 时发送 X-Cuttingfloor-Key-Sync: <your sync. labs key>。密钥仅用于该请求及其启动的作业，之后即被丢弃；密钥绝不会被存储或记录。若某个工具需要的密钥尚未发送，它会返回 credential_required 并指出相应标头。

{ "mcpServers": { "cuttingfloor": { "url": "https://api.cuttingfloor.ai/mcp", "headers": { "X-Cuttingfloor-Key-Sync": "<key>" } } } }

变量	默认值
CUTTINGFLOOR_DATA	/data	数据根目录
CUTTINGFLOOR_MAX_JOBS	核心数 ÷ 4	并发导入、导出和 QA 运行数（沙盒作业改为在沙盒中排队）
CUTTINGFLOOR_HEAVY_JOBS	1	并发运行 create.cutout 的数量，使用独立时隙，不占用上述作业的时隙
CUTTINGFLOOR_MAX_RENDERS	核心数 ÷ 2，至少为 2	同时进行的渲染数（melt、编码、转录），作业与内联预览共用；其余任务等待轮候
CUTTINGFLOOR_OUTPUT_URL_TTL_HOURS	24	签名下载链接的有效期
CUTTINGFLOOR_MAX_DOWNLOAD_BYTES	10 GiB	URL 导入和上传的大小上限
CUTTINGFLOOR_MOTION_URL	未设置（compose 会设置）	create.motion 和 create.still 使用的沙盒；未设置时，这些工具会说明如何启动沙盒
CUTTINGFLOOR_MOTION_WORKERS	每两个 CPU 一个，最多 4 个	共享 create.motion 渲染任务的浏览器数量；在沙盒上设置

开发

pnpm install && pnpm check       # lint, typecheck, unit and protocol tests (Node 24+, pnpm 10)
docker build --target test .     # everything, including engine and end-to-end tests
docker build -t cuttingfloor:dev . && node scripts/smoke-image.ts cuttingfloor:dev
node scripts/smoke-motion.ts cuttingfloor:dev   # the sandbox in compose, attacked

目录结构

路径	内容
apps/cli	cuttingfloor serve（HTTP）、cuttingfloor mcp（stdio）和 cuttingfloor motion-worker（沙盒角色）
apps/hosted	HTTP 节点：MCP 端点、签名下载和上传、API 密钥及脚本密钥
packages/server	MCP 工具、资源和 Tasks 适配器
packages/schema	每个工具、时间线文档和错误的 Zod 模式
packages/core	时间线文档、编辑运算、内容哈希、带 TTL 的存储
packages/engine	作为子进程运行的 FFmpeg 和 MLT：探测、规范化、代理、帧、导出、QA
packages/motion	沙盒工作进程：页面在虚拟时钟上逐帧渲染，每次一帧
tools/	构建到镜像中的原生辅助工具（cf-vision、cf-segment），以及沙盒的 Chromium 封装程序和 seccomp 配置文件
packages/jobs	MCP Tasks 和 job.* 背后的文件型作业存储和运行器
packages/credentials	使用自带的提供商密钥

许可证

尚未确定。添加许可证之前，所有权利均予保留。