clipswarm

clipswarm

开源、原生支持 Agent 的视频剪辑工具。 将任意数量的 AI Agent 指向 YouTube 视频 或直播流，即可获得随时可发布的爆款短视频：9:16 画幅、吸睛标题栏和逐词字幕。在你的机器上运行，无需 API 密钥或订阅。

_{只需一条命令即可制作：clipswarm clip https://youtu.be/75-H-i9ctkE 6 14.4 --viral --title "Astronauts celebrate July 4th from 250 miles up"
视频素材：NASA（公共领域）。不代表 NASA 认可。}

"Get me the 3 best moments from each of these 10 podcasts as shorts"
        │
        ├─ clipper agent 1 ─┐
        ├─ clipper agent 2 ─┼─► clipswarm MCP ─► yt-dlp ─► ffmpeg ─► clips/*_viral.mp4
        └─ clipper agent N ─┘     shared queue, cached transcripts, retries

为什么选择 clipswarm

OpusClip 风格的应用会替你决定什么内容算“爆款”。clipswarm 将工具交给你的 Agent来决定，再负责完成制作：

• 内置爆款格式：1080×1920、吸睛标题卡、完整视频画面（绝不裁剪或放大），以及随说话逐词高亮的动态字幕。布局会适应源视频的画面比例。
• 支持 YouTube 视频和直播流：剪辑直播流中刚刚发生的内容（start: -60, end: "now"），或晚上 8:41 播出的内容。
• 字幕采用真实词语时间戳：普通视频使用 YouTube 自动字幕，直播流使用本地 whisper.cpp。免费且离线。
• 自动运行：提供类别和计划（“netflix 股票，每 6 小时”），它就会查找新视频，让 AI 挑选片段并撰写吸睛标题，然后在后台渲染短视频。
• 专为集群设计：通过一个共享队列，在多个视频上运行数十个并行任务，支持多个 Agent 同时工作。每个视频只获取一次转录文本，单个任务出错也不会拖垮整个批次。
• 快速且省资源：只下载剪辑所需的片段（而非整个 3 小时直播），并在 macOS 上使用硬件编码。
• 兼容任意 ffmpeg：文本由 clipswarm 自行渲染，因此不带 drawtext/libass 的常规构建版本（例如 Homebrew 版本）也能正常使用。

安装

1. 安装依赖（Node 20+）：

brew install yt-dlp ffmpeg whisper-cpp     # macOS
# Linux: pip install -U yt-dlp && sudo apt install ffmpeg   (+ whisper.cpp for live captions)
npx -y clipswarm setup                     # checks everything; downloads the caption model (~140MB)

whisper-cpp 为可选组件。不安装也能正常使用所有功能，但直播流短视频渲染时不会带字幕。

请保持 yt-dlp 为最新版本（yt-dlp -U / brew upgrade yt-dlp）。YouTube 经常导致旧版本失效。这是导致故障的首要原因。

2. 将其添加到你的 AI 应用中：

应用	方法
Claude Code（推荐，包含 clipper Agent）	/plugin marketplace add Shoberman2/clipswarm 然后 /plugin install clipswarm@clipswarm
Claude Code（仅 MCP）	claude mcp add clipswarm -- npx -y clipswarm mcp --out ./clips
Claude Desktop	Settings → Developer → Edit Config，在其中添加下方 JSON
ChatGPT 桌面应用 / Codex	codex mcp add clipswarm -- npx -y clipswarm mcp（Codex CLI、IDE 扩展和 ChatGPT 桌面应用共用）
Cursor	~/.cursor/mcp.json，使用下方 JSON
VS Code	code --add-mcp '{"name":"clipswarm","command":"npx","args":["-y","clipswarm","mcp"]}'
Gemini CLI	gemini mcp add clipswarm npx -y clipswarm mcp

{ "mcpServers": { "clipswarm": { "command": "npx", "args": ["-y", "clipswarm", "mcp", "--out", "/Users/you/clips"] } } }

为什么不能使用 claude.ai 或网页版 ChatGPT？ 它们只能连接托管服务。托管 YouTube 下载器会遇到数据中心 IP 封禁、服务条款风险，还要通过聊天窗口传输 50 MB 视频。clipswarm 在本地运行，这三个问题都不复存在。

使用方法

安装插件后，在 Claude Code 中：

为以下每个视频并行启动一个 clipper Agent，并从每个视频中为我找出最适合制作爆款短视频的 3 个片段：

将 https://www.youtube.com/@aljazeeraenglish/live 的最后 60 秒剪成一条爆款短视频。

每个 clipper Agent 都会读取对应视频的转录文本，挑选独立成段的片段，为每个片段撰写吸引人的开场，并调用 create_clips。它们会同时运行。

爆款视频格式

选项	默认值
style	"plain"	设为 "viral" 可使用 9:16 格式
title	视频标题	标题钩子。Agent 应撰写简短有力的标题（≤10 个词）；设为 "" 则不显示标题
background	"#000000"	视频背后的颜色（或设为 "blur"）
captions	true	逐词字幕，每次显示 1–3 个词，并高亮当前词
accent	"#FFE600"	高亮颜色

始终显示完整画面。 clipswarm 绝不会裁切或缩放，因为视频中的重要内容（电子表格、图表、另一位说话者）可能出现在画面的任何位置。布局会根据源视频调整：

源视频	布局
宽屏（16:9、屏幕录制、播客）	视频占满宽度，标题置于上方，字幕置于下方，画面居中显示在黑色背景上
竖屏（9:16 短视频、手机视频）	视频填满画面；标题和字幕叠加在视频上
正方形 / 4:3 / 其他比例	尽可能放大显示，不裁切任何内容

普通视频的字幕来自 YouTube 自动字幕（精确到每个词的时间）；直播流或没有字幕的视频则使用本地 whisper.cpp 生成。如果两者都不可用，仍会渲染片段，并在结果中添加一条 warnings 说明原因。

直播流

粘贴当前正在直播的链接（watch?v= 链接或频道的 /live 链接）。时间相对于直播边缘计算：

你想要的片段	start	end
最后 30 秒	-30	"now"
2 分钟前开始、时长 20 秒	"-2:00"	"-1:40"
特定时刻播出的内容	"2026-10-08T00:51:00Z"	"2026-10-08T00:51:30Z"

• 可获取大约最近 1 小时的内容（YouTube 的 DVR 窗口）。
• 普通直播片段会直接复制流以加快处理速度，并从前一个关键帧开始（最多提前 ≤5 秒）。结果中的 live.from / live.to 会提供精确的实际时间范围。若要按帧精确剪辑，请使用 precise: true。爆款短视频始终按帧精确剪辑。
• end 不能设为未来时间。请在内容播出后重试。

监控：自动发现精彩片段

为 clipswarm 指定一个类别和计划。它会搜索 YouTube 上的新视频，挑选最精彩的时刻，并在你离开时将其剪辑成爆款短片。新片段生成后，Mac 会显示通知。

clipswarm watch add "netflix stock analysis" --every 6h          # what to look for, how often
clipswarm watch install                                          # background job (launchd on macOS)
clipswarm watch run --force                                      # or run it right now
clipswarm watch inbox                                            # what it found and clipped

或者直接向你的 Agent 提问：“每隔 12 小时监控新发布的 AI agent 新闻视频，并剪辑最精彩的片段。”（MCP 工具：create_watch、list_watches、run_watch、get_inbox、update_inbox_item、delete_watch、watch_scheduler。）

挑选时刻的方式，按优先顺序排列：

1. AI。 如果已安装 Claude Code CLI，Claude 会读取转录文本，挑选完整独立的片段，并为每个标题撰写引子（例如 “Netflix 股价为 67 美元，但这个模型预测为 127 美元”）。此功能使用你自己的 Claude 账户运行。
2. 重播次数最多的片段。 对于上传时间足够久的视频（通常是几天），使用 YouTube 的重播峰值。
3. 转录文本启发式分析。 免费且离线：为包含提问、数字、强烈论断和富有感染力内容的片段打分。

如果 YouTube 字幕缺失或受到速率限制，监控器只会下载音频，并使用 whisper.cpp 进行转录。无法剪辑的内容会以 needs_agent 状态放入收件箱，由你的 Agent 处理。

选项	默认值
--every	6h	30m、6h、1d……（最短 5m）
--max-age	72h	仅处理在此时间范围内上传的视频
--min-views	无	跳过播放量较低的视频
--videos	3	每次运行处理的新视频数
--clips / --seconds	2 / 45	每个视频的片段数、目标时长
--picker	auto	可指定 ai、heatmap 或 transcript
--live	关闭	也将当前正在直播的内容列入收件箱
--no-auto	关闭	仅收集视频；不剪辑
--out	~/clipswarm/<id>	片段的保存位置

状态保存在 ~/.clipswarm/ 中（可通过 CLIPSWARM_HOME 更改位置）。每个视频只会处理一次。在 Linux 上，watch install 会打印一行 crontab 配置，clipswarm watch daemon 则可在任意位置运行前台循环。

工作原理

1. 找到精彩时刻。 Agent 会调用 get_video_info、search_transcript 和 get_transcript。转录文本来自 YouTube 字幕，通过 yt-dlp 获取并缓存。
2. 剪辑。
   • 常规视频： yt-dlp 仅下载指定片段。
   • 直播： clipswarm 会读取 YouTube 持续更新的 HLS 播放列表（包含带有实际时间戳的 5 秒分段），并仅获取覆盖指定时间范围的分段。
3. 制作爆款短片。 clipswarm 获取每个词的时间信息，并绘制标题和字幕帧（字体 → 矢量路径 → PNG）。ffmpeg 会将它们与未经裁切的完整视频合成到 9:16 画布上。
4. 共享机器资源。 所有 Agent 的每个任务都会经过同一个并发限制器；遇到 YouTube 间歇性返回 403 时会重试。

贡献者：请参阅 docs/ARCHITECTURE.md，了解完整的代码讲解。

MCP 工具

工具	功能
get_video_info	标题、频道、时长、章节、liveStatus
get_transcript	带时间戳的转录文本，按紧凑的 [m:ss] 文本 行呈现；也可通过 from/to 指定时间范围
search_transcript	查找某个短语出现的位置，并返回带前后时间的窗口，方便直接剪辑
create_clips	在任意数量的视频中并行剪辑多个片段，无论是否为直播。选项：style、title、captions、accent、background、label、vertical、maxHeight、precise
get_clips	获取仍在渲染的批次结果。create_clips 会在约 40 秒后返回 jobId，这样 MCP 客户端约 60 秒的超时限制就不会中断长批次任务
create_watch、list_watches、delete_watch、run_watch	管理定时 YouTube 主题搜索和可选的自动剪辑
get_inbox、update_inbox_item、watch_scheduler	查看需要 Agent 处理的视频，并管理可选的后台调度器

CLI

clipswarm clip <url> 13:53 14:28 --viral --title "His best advice in 30 seconds"
clipswarm clip <live-url> -60 now --viral --title "This just happened live"
clipswarm clip <url> 1:23 1:58 --label raw-cut                    # plain clip
clipswarm batch jobs.json --out clips                             # many jobs at once, writes clips/manifest.json
clipswarm search <url> stay hungry
clipswarm transcript <url>
clipswarm setup

定时监控

监控会在 YouTube 中搜索某个类别下近期上传的视频，并可剪辑其中最精彩的片段。只有在运行监控或安装后台调度器时，才会搜索视频并进行剪辑；添加监控仅会保存其设置。

clipswarm watch add "AI research" --every 6h
clipswarm watch list
clipswarm watch run ai-research
clipswarm watch inbox
clipswarm watch remove ai-research

默认开启自动剪辑。默认的 --picker auto 会在本地 Claude Code CLI 可用时使用它，否则会改用 YouTube 回放峰值或转录文本启发式方法。调用 Claude CLI 时会使用其配置的账户，并可能消耗该账户的使用额度；使用 --picker heatmap 或 --picker transcript 可避免调用它。使用 --no-auto 可将发现的视频放入收件箱，供 AI Agent 审核。无法自动挑选的视频，以及启用 --live 时的直播，都会放入收件箱。clipswarm watch install 会选择加入 macOS launchd 任务，每五分钟检查一次到期监控；clipswarm watch uninstall 会移除该任务。监控状态存储在 ~/.clipswarm/state.json 中（设置 CLIPSWARM_HOME 可使用其他位置）。

配置

环境变量	默认值
CLIPSWARM_CONCURRENCY	min(6, cpus)	同时进行的下载／编码任务数上限，所有调用方共享；必须为正整数
CLIPSWARM_MAX_CLIP_SEC	600	防止意外下载完整视频；必须大于 0
CLIPSWARM_RETRIES	3	针对 YouTube 临时错误的重试次数；必须为非负整数
CLIPSWARM_WHISPER_MODEL	~/.cache/clipswarm/ggml-base.en.bin	任意 whisper.cpp 模型，例如多语言模型
CLIPSWARM_FONT	内置 Montserrat Black	用于标题和字幕的任意 TTF/OTF 字体

平台支持

	macOS	Linux	Windows
剪辑、病毒式传播格式、直播	✓（硬件编码）	✓	✓
监控	✓ launchd	✓ watch install 打印的 cron 行	✓ 任务计划程序
通知	✓	–	–

CI 会在所有三个平台上运行测试套件（包括实际的 ffmpeg 渲染）。

已知限制

• YouTube 的变更会导致下载器失效。 如果剪辑开始失败，请先更新 yt-dlp（yt-dlp -U）。clipswarm 的错误消息会提示这一点。
• 频繁使用可能触发限流。 请求多次后，YouTube 有时会对字幕请求返回 HTTP 429。clipswarm 会重试，并改用 whisper.cpp 在本地转录音频。
• 直播： 只能获取最近约一小时的内容，直播期间也没有转录文本。
• “Most replayed”数据 只会出现在上传数天的视频中，因此监控会优先使用 AI 挑选。
• 宽屏视频在手机上显示较小，因为 clipswarm 从不裁剪画面。这是有意为之：不会裁掉任何相关内容。

负责任地使用

仅剪辑你有权使用的内容：自己的视频、已获授权的内容，或在你所在司法辖区受合理使用原则保护的内容。YouTube 服务条款可能限制下载行为。你需对如何使用此工具负责。

路线图（欢迎协助）

根据用户的需求推进。请提交 issue。

• 更多字幕样式（卡拉 OK 方框、表情符号、逐词弹出）
• 本地文件和其他平台（大多数 yt-dlp 支持的网站都已可用）
• 可选的托管模式／用于远程 Agent 的 HTTP 传输

许可证

MIT。内置的 Montserrat 字体遵循 SIL Open Font License。如需协助，请参阅 CONTRIBUTING.md。