WeCut

WeCut

WeCut 是一款面向 AI Agent 的免费开源视频编辑引擎。 Agent 编写一个小型 JSON 项目，wecut 就会使用设备上已有的 FFmpeg 渲染。它可以剪辑、添加字幕、调整画面并混合短视频，还能分析爆红视频并将其风格作为模板应用到新素材上。支持命令行和 MCP 服务。无需云服务、API 密钥、GPU，也不会收集遥测数据。

使用 WeCut 的 Agent 可以完成以下任务：

• “把这段 40 分钟的播客剪成 5 个竖屏片段，并添加卡拉 OK 字幕。”
• “给 talk.mp4 添加逐字字幕，并在下面加上音乐；说话时把音乐调小。”
• “这条 TikTok 爆红了。分析它爆红的原因，并用我的素材制作同类型视频。”
• “把这 8 张照片制作成一段 9:16 的幻灯片视频，配合节拍并添加标题。”
• “把这次剪辑保存为模板，这样我们每周都能照着做。”

npx -y wecut doctor                           # is FFmpeg ready?
npx -y wecut guide                            # the full guide for agents
npx -y wecut probe media/talk.mp4             # duration, size, fps, audio
npx -y wecut validate project.json            # errors with JSON pointers and fix hints
npx -y wecut preview project.json --at 1,5,9  # small JPG frames to look at
npx -y wecut render project.json              # out/clip.mp4
npx -y wecut mcp                              # the same, as an MCP server on stdio

每条命令都会在 stdout 上打印一个 JSON 对象。退出代码：0 成功，2 输入无效，3 缺少依赖，4 渲染失败，5 超出限制。

在 Agent 中安装

WeCut 需要 FFmpeg 6 或更高版本，并且必须包含 libass（npx -y wecut doctor 会检查并告知需要安装什么）：

• Debian/Ubuntu：sudo apt-get install -y ffmpeg
• macOS：brew install ffmpeg-full（精简版 ffmpeg 安装包不包含 libass；WeCut 会自动找到 ffmpeg-full）
• Windows：winget install Gyan.FFmpeg

然后将其连接到你使用的 Agent。MCP 服务在固定的工作区文件夹中运行（--root，默认值：启动服务时所在的文件夹）；所有媒体路径都相对于该文件夹。

Claude Code

claude mcp add wecut -- npx -y wecut mcp

也可以作为插件使用，它还会安装 WeCut 技能：

/plugin marketplace add 13kailouis-stack/wecut
/plugin install wecut@wecut

任意 MCP 客户端

Claude Desktop、Cursor、Windsurf、Cline、Roo Code、LM Studio 和大多数其他客户端都可以在 MCP 设置文件中使用此配置块。请明确指定 --root，因为桌面应用启动服务时所在的文件夹不可预测。

{
  "mcpServers": {
    "wecut": { "command": "npx", "args": ["-y", "wecut", "mcp", "--root", "/path/to/workspace"] }
  }
}

VS Code（Copilot Agent 模式）

code --add-mcp '{"name":"wecut","command":"npx","args":["-y","wecut","mcp"]}'

或在 .vscode/mcp.json 中：

{ "servers": { "wecut": { "type": "stdio", "command": "npx", "args": ["-y", "wecut", "mcp"] } } }

OpenAI Codex CLI

codex mcp add wecut -- npx -y wecut mcp

或在 ~/.codex/config.toml 中：

[mcp_servers.wecut]
command = "npx"
args = ["-y", "wecut", "mcp"]

Gemini CLI

gemini extensions install https://github.com/13kailouis-stack/wecut

可使用终端的 Agent

Grok、Manus、OpenHands、Devin、Codex 云任务、Claude 的代码执行功能，以及任何能够运行 shell 命令的 Agent，都可以不通过 MCP 使用 WeCut：

npx -y wecut guide     # read this first: workflow, project format, templates
npx -y wecut doctor

然后按照指南操作：probe、编写 project.json、validate、preview、render。在全新的 Linux 沙箱中，请先使用 sudo apt-get install -y ffmpeg 安装 FFmpeg。

Agent 技能

skills/wecut/SKILL.md 中的技能会向能够加载技能的 Agent（Claude Code、Claude 应用、Codex、Cursor 等）讲解工作流：

npx skills add 13kailouis-stack/wecut

获取二进制文件的其他方式

• npm（Node 16+）：npx -y wecut <command>，或 npm i -g wecut。npm 只会安装适用于你平台的二进制文件（@wefluence/wecut-<os>-<arch>）；不会运行安装脚本。
• 二进制文件：从 GitHub Releases 下载适用于你操作系统的压缩包，并使用 SHA256SUMS 校验。
• 源码（Go 1.22+）：go build -o wecut ./cmd/wecut

提供适用于 Linux、macOS 和 Windows 的预编译版本，支持 x64 和 arm64。设置 WECUT_BINARY，即可通过 npm 启动器使用你自己的构建版本。

功能

• 剪辑、拼接片段并调整播放速度（0.25x 到 4x），支持 9:16、16:9、1:1、4:5 等画布比例
• 按焦点和缩放裁剪以铺满画布，或在纯色或模糊背景上完整显示
• 为照片添加 Ken Burns 动态效果
• 36 种转场（FFmpeg xfade），以及片段淡入淡出
• 文本支持 17 种样式（包括新闻风格标题卡片和标签）、13 种内置字体、用另一种颜色突出显示词语，以及弹出／打字／滑入／淡入动画
• 根据转录文本生成字幕：短语、卡拉 OK（突出显示正在说出的词语）或逐词显示。转录时间可保留为源文件中的秒数；WeCut 会根据剪辑位置进行映射
• 图片叠加层（徽标、贴纸），支持不透明度、旋转和淡入淡出
• 音乐和音效支持裁剪、循环、淡入淡出，以及在人声下方自动降低音量
• 颜色滤镜和效果（闪光、电影黑边、画框、变暗、夜景、棕褐色）
• 分析现有视频：镜头、节奏、开场钩子时长、闪光、节拍和节奏同步、停顿、平台片尾，以及模型可查看的帧图
• 模板（“配方”）：一种剪辑结构，可应用于新的片段、文字和音乐；也可从任意项目保存自己的模板
• 输出为 MP4（H.264 + AAC，faststart）或 GIF

分析视频，复用其格式

wecut analyze media/viral.mp4                 # shots, pace, hook, flashes, tempo, pauses + a frame sheet
wecut recipe list                             # templates: built-in and the workspace's recipes/*.json
wecut recipe apply --input request.json       # recipe + new clips, words, music -> project
wecut recipe from-project my-edit.json --write recipes/my-style.json   # "save as template"

analyze 会测量模型无法从转录文本中获知的内容：剪辑点的位置（白色闪光或频闪效果算作一次）、开场镜头持续时长、剪辑点是否落在节拍上，以及文件结尾是否有静音的平台片尾。帧图每个镜头取一帧并附上时间戳，Agent 可通过它识别标题卡片、文本样式和画面构图。

配方（wecut.recipe/1，架构定义见 schema/wecut.recipe.schema.json）描述的是剪辑的结构，而非内容：由角色填充的片段（一个带标题卡片的 5 s hook，接着是 body）、应用时填充的文本占位槽（可通过 emphasis 指定要着色的词语）、字幕和音乐样式，以及剪辑点上的效果。配方可以附带自己的默认音轨，就像 CapCut 模板一样；应用时传入的音乐会替换默认音轨，传入 "none" 则会移除音轨。内置配方复刻了当今印度尼西亚短视频中常见的内容格式结构：带标题卡片的新闻风格转载、引言式开场钩子、短语字幕 Vlog、放大画面的播客、照片幻灯片。

复用结构，而非内容：其他创作者的镜头、措辞和音乐仍归其所有。

MCP 工具和提示词

工具	功能
wecut_doctor	检查 FFmpeg、编码器和滤镜
wecut_probe	获取媒体文件的时长、尺寸、fps 和音频信息
wecut_validate	检查项目；错误会附带 JSON 指针和提示
wecut_preview	渲染帧并以图片形式返回，供模型查看
wecut_render	渲染 MP4/GIF，并发送进度通知
wecut_list、wecut_schema、wecut_example	名称、项目格式和可运行的示例
wecut_analyze	测量视频并以图片形式返回帧图
wecut_recipe_list、wecut_recipe_show	模板及其角色和文本占位槽
wecut_recipe_apply	配方 + 新片段、文字和音乐 -> 项目
wecut_recipe_from_project	将完成的项目保存为模板

提示词（在支持显示提示词的客户端中作为斜杠命令使用）：clips-from-video、copy-viral-format、add-captions、save-template。

项目可作为对象（project）或工作区文件（projectFile）传入。该服务同时支持两个协议版本：现代客户端（2026-07-28，按请求提供 _meta、server/discover）以及通过 initialize 握手的客户端（2024-11-05 至 2025-11-25）。渲染任务一次运行一个；notifications/cancelled 会停止任务并删除其未完成的文件。

项目格式

wecut guide（内容与 skills/wecut/SKILL.md 相同）说明了工作流、两种时钟（源文件秒数与输出秒数）、字幕和故障排查。wecut schema 会打印完整的 JSON Schema，wecut example <name> 会打印一个可运行的项目。

{
  "wecut": "1",
  "output": { "file": "out/clip-01.mp4", "ratio": "9:16" },
  "clips": [ { "src": "media/talk.mp4", "from": 754.2, "to": 781.0, "focus": { "x": 0.42, "y": 0.5 } } ],
  "texts": [ { "text": "How I made my first $10k", "end": 3, "style": "hook", "y": 0.2, "in": { "type": "pop" } } ],
  "captions": { "words": "media/talk.words.json", "src": "media/talk.mp4", "style": "karaoke" },
  "audio": [ { "src": "media/music.mp3", "volume": 25, "loop": true, "duck": true } ]
}

常见问题

WeCut 是什么？ 一款为 AI Agent 打造的开源命令行视频编辑器。Agent 用 JSON 描述编辑内容，WeCut 会检查内容、显示预览帧，并在同一台机器上使用 FFmpeg 渲染。它由印度尼西亚的 UGC 和剪辑市场 Wefluence 开发。

它免费吗？ 是。采用 Apache-2.0 许可，无需账号或 API 密钥，也没有使用限制。它运行在你自己的电脑或 Agent 的沙盒中，因此也无需支付服务器费用。

如何让 ChatGPT、Claude、Grok 或其他 AI 编辑视频？ 向 Agent 提供 WeCut：在支持 MCP 的客户端中将其用作 MCP 服务（npx -y wecut mcp），将其用作技能，或让带有终端的 Agent 运行 npx -y wecut guide 并按说明操作。请参阅在你的 Agent 中安装。没有代码沙盒的聊天应用无法访问你电脑上的文件；请改用桌面或终端 Agent。

AI Agent 能从长视频制作 TikTok、Reels 或 YouTube Shorts 吗？ 可以。Agent 会读取转录文本、挑选片段，为每个剪辑编写一个项目，并将 captions.src 指向源文件；预览其中一个剪辑，然后将所有剪辑渲染为带字幕的 9:16 视频。

它能模仿热门视频的格式吗？ 它会分析视频（wecut analyze：剪辑、节奏、钩子长度、闪烁、速度、停顿、结尾），并返回模型可查看的帧表。然后，Agent 会选择或编写一份配方，并将其应用于新素材、文字和音乐。它模仿的是结构，而非素材、措辞或音乐。

它能转录语音吗？ 它可以读取 OpenAI 或 Groq Whisper verbose_json、whisper.cpp JSON、SRT、VTT 或纯文本词语列表中的单词时间戳。如果本地 FFmpeg 带有 Whisper 筛选器，wecut doctor 会报告 local_transcription: true。

它会把我的视频上传到别处吗？ 不会。WeCut 不会发起网络请求，也没有遥测功能。如果媒体路径是 URL 或位于工作区之外，WeCut 会拒绝使用。

它需要 GPU 吗？ 不需要。默认使用 CPU 上的 libx264 编码，也可通过 --encoder 使用 NVENC、Quick Sync 或 VideoToolbox。在一台 2019 年的笔记本上，渲染带字幕的 43 秒 1080x1920 剪辑大约需要 28 秒。

支持哪些平台？ 支持 x64 和 arm64 架构的 Linux、macOS 和 Windows，需搭配 FFmpeg 6+ 和 libass。

我可以制作自己的模板吗？ 可以。编辑项目直至效果满意，然后运行 wecut recipe from-project my-edit.json --write recipes/my-style.json。工作区 recipes/ 文件夹中的配方会和内置配方（包括音乐配方）一起显示在 wecut recipe list 中。

与其他通过 Agent 编辑视频的方式相比

	WeCut	手动使用 FFmpeg	Remotion / MoviePy	云视频 API	CapCut
专为 Agent 打造（输入 JSON，出错时提供修复提示）	是	否，需编写很长的滤镜图	需要编写代码	输入 JSON	否，是面向用户的应用
在本地运行，媒体不会离开设备	是	是	是	否，需上传	部分支持
费用	免费	免费	免费到付费许可	按渲染分钟数计费	免费到订阅制
根据转录文本生成字幕，并根据剪辑映射字幕	是	手动	手动	部分支持	应用内自动生成字幕
模型可查看的预览帧	是	手动	手动	部分支持	否
分析热门视频并复用其格式	是	否	否	否	人工制作的模板
MCP 服务	是	否	否	部分支持	否

安全性

WeCut 运行在他人的机器上，并会接收可能读过恶意内容的模型发出的指令。因此：

• FFmpeg 通过参数列表启动，绝不通过 shell 启动。
• 文本绝不会进入 FFmpeg 滤镜图。所有文本都会写入 .ass 文件，并对花括号和反斜杠进行转义，因此字幕无法注入覆盖标签或滤镜。
• 所有输入和输出都必须位于工作区内（--root，默认值：当前文件夹）。拒绝 ..、指向工作区外的绝对路径、指向外部的符号链接和 URL。输出不得覆盖输入。
• 输入使用 -protocol_whitelist file 和解复用器白名单打开（MP4/MOV、Matroska/WebM、常见音频和图像格式）。拒绝 HLS 播放列表、concat 列表和网络协议，包括扩展名被改为 .mp4 的播放列表。
• 限制：输出最长 10 分钟，最高 4K，最多 100 个片段；渲染会超时（默认超时时间随视频长度变化）。
• 渲染结果会先写入临时文件名，再通过 ffprobe 检查（大小、时长、音频），之后才移至目标位置。
• 不收集遥测数据。WeCut 不会发起网络请求。

速度

在 2019 年的笔记本电脑上测得（Intel i5-1035G7，4 核，负载状态），使用 final 预设，除非另有说明，分辨率为 1080x1920：

项目	视频长度	渲染时间
从 14 分钟的 720p 源视频中剪出 2 段，配有卡拉 OK 字幕和压低音量的音乐	43.3 秒	27.6 秒
3 张带缩放／平移效果的照片、2 个转场、文字、音乐	7.9 秒	9.4 秒
3 个片段、滑动转场、适应画面、Ken Burns 效果、徽标、字幕（720p）	7.4 秒	4.0 秒
预览帧（540p JPG）	任意	0.3 至 4 秒

编码是主要耗时所在；文字和字幕几乎不耗费时间。不使用不重新编码的简单剪切，因为任何裁剪、字幕或特效都需要重新编码。

项目结构

cmd/wecut          entry point (CLI and `wecut mcp`)
internal/spec      project format: types, strict decoding, validation, catalog
internal/engine    timeline, captions, .ass builder, FFmpeg graph compiler (pure, no I/O)
internal/analyze   shots, pace, tempo, pauses from FFmpeg's measurements (pure)
internal/recipe    the template format: validate, apply to new material, derive from a project
internal/ff        finding, probing and running FFmpeg
internal/cli       the commands; every result is one JSON object
internal/mcp       MCP stdio server, a thin layer over internal/cli
internal/workspace keeps every path inside the workspace
internal/assets    fonts embedded in the binary
schema/            JSON Schema (kept in sync with the Go types by a test)
examples/          example projects (`wecut example`)
recipes/           built-in recipes
skills/wecut/      Agent Skill (`wecut guide` prints it)
npm/wecut/         the npm launcher (`npx wecut`)
tools/release/     builds all platforms, npm packages and release archives into dist/

Agent 和注册表清单：server.json（MCP Registry）、.claude-plugin/（Claude Code 插件和市场）、gemini-extension.json 和 GEMINI.md（Gemini CLI）、glama.json、llms.txt、AGENTS.md（供修改此代码的 Agent 使用）。

发布构建：go run ./tools/release -version 0.1.0（不会发布任何内容；参见 .github/workflows/release.yml）。

测试：go test ./...（CLI 测试会渲染真实视频；未安装 FFmpeg 时会跳过）。FFmpeg 黄金计划位于 internal/engine/testdata；有意进行更改后，运行 go test ./internal/engine -update，并渲染示例进行检查。

路线图

• uvx wecut（PyPI wheels）和 MCPB 捆绑包，便于在 Claude Desktop 中一键安装
• 通过 FFmpeg 的 Whisper 滤镜进行本地转录、响度标准化
• 视频叠加画面（画中画）、贴纸和更多特效
• 可选的 Wefluence 桥接功能，用于付费剪辑活动（独立软件包）

许可证

代码：Apache License 2.0（参见 LICENSE）。捆绑字体：SIL Open Font License 1.1 或 Apache 2.0，参见 internal/assets/fonts/LICENSES.md。