capcut-cli

English | 中文

免责声明： 本项目为独立的、社区维护的项目，与 CapCut、剪映或字节跳动有限公司（ByteDance Ltd.）无任何隶属、赞助或背书关系。"CapCut" 与 "剪映" 为字节跳动有限公司的商标，所有产品名称、徽标与品牌均归各自所有者所有，此处仅用于标识（指称性使用）目的。

任何大模型 Agent 都能驱动的剪映 / CapCut 命令行 —— 零依赖、无服务、CapCut + 剪映共用一个二进制。

JSON 进、JSON 出：每个命令都直接读写本地草稿存储，不用 MCP 服务或 HTTP 守护进程。新版 CapCut 会自动检测并同步每个可读的时间线目标，不再假设只有 draft_content.json 是真源。这给任何模型（Claude、DeepSeek、GLM、Kimi）一个确定性边界，用于查看、构建、字幕、字幕烧录、翻译与长视频切短。

三种用法：

• 命令行（CLI） —— npm install -g capcut-cli，然后 capcut <command> <project>
• 库（Library） —— import { loadDraft, lintDraft, saveDraft } from "capcut-cli"（带类型、零依赖）
• 队列执行器 —— capcut serve 从 stdin 读取 JSONL 任务，对接 n8n / Make / Coze

v0.13.0 新增： CapCut ≥ 8.7 时间线镜像修复（sync-timelines）、逐词字幕导出（export-srt --granularity word，支持 SRT + VTT）、CapCut 原生关键帧缓动（keyframe --easing）、确定性镜头切分检测（detect-scenes）、可移植文字样式预设（make-preset + --preset），以及 lint --fix 自动修复。完整说明见 更新日志。

安装

前置要求： Node ≥ 18（仅用内置模块，无原生依赖）。可选工具解锁特定命令：Whisper 用于 caption，FFmpeg 用于 render，ffprobe 用于自动读取媒体元数据，ANTHROPIC_API_KEY 用于 translate。

npm install -g capcut-cli      # 或：npx capcut-cli <command>

从源码构建：git clone https://github.com/renezander030/capcut-cli && cd capcut-cli && npm install && npm run build（再 npm link 暴露 capcut）。

快速上手

capcut doctor                                  # 检查 Node、FFmpeg、whisper、草稿目录
capcut quickstart my-first --video clip.mp4    # 创建 + 加素材 + lint，并打印“在 CapCut 中打开”的步骤
capcut info ./my-first/                         # 查看草稿（加 -H 显示表格）

然后在 CapCut 中打开项目审阅并渲染。所有短视频平台都禁止自动上传，所以最后的发布按钮由你来点。

常用命令

默认输出 JSON（可管道给 jq）；加 -H 显示人类可读表格。加 --jianying 使用剪映枚举命名空间。运行 capcut <command> --help 查看完整参数。

| 分组 | 命令 | |------|------| | 查看 | info · tracks · materials · version · lint | | 浏览 / 下钻 | segments · texts · segment · material | | 创建 | init · quickstart · compile（用 JSON spec 构建草稿）| | 预览 | render（低清 ffmpeg 代理预览 —— 非 CapCut 最终渲染）| | 添加 | add-video · add-audio · add-text（支持 Wikimedia URL，自动校验授权）| | 编辑 / 动画 | 裁剪 · 变速 · 音量 · 转场 · 蒙版 · 文字/图片动画 · 缓动曲线 | | 模板 | 应用与提取可复用版式 · make-preset（可移植文字样式预设）| | 字幕 / 多语言 | caption · import-srt · export-srt（行级/逐词 SRT + VTT）· translate（多语言草稿克隆）| | 特效 | sfx · chroma（绿幕抠像）| | 长视频切短 | cut · detect-scenes（ffmpeg 场景切点检测）| | 自动化 | serve（无状态 JSONL 执行器）· migrate · doctor · sync-timelines（8.7 时间线镜像修复）|

完整命令参考（每个命令、参数与退出码）：docs/command-reference.md。

赞助

capcut-cli 采用 MIT 协议，永久免费。赞助会加速版本发布、让新版 CapCut / 剪映在同一周内得到支持 —— 同时解锁高级用户福利：

• $5/月 · 支持者 —— 仅赞助者可见的发布说明，以及把你的名字写进 BACKERS.md。让项目持续前进。
• $25/月 · Pro —— 受邀加入私有仓库 capcut-cli-pro：高级模板与字幕样式包、完整的 Claude 爆款短视频流水线、开箱即用的 compile 配置，以及抢先体验版构建。外加优先处理你的 issue。
• $100/月 · 团队 —— Pro 全部内容，覆盖最多 5 名团队成员；书面商用授权确认；你的 logo 展示在本 README；并优先快速实现你团队需要的功能。

成为赞助者 →

在工作中用 capcut-cli 吗？团队版只要帮工程师省下一个下午，当天就回本了。

工作原理

CapCut / 剪映把每个项目存为本地 JSON。capcut-cli 加载这个存储，按版本感知的 schema 校验，应用你的编辑，再原子写回（并留 .bak）。不上传任何项目文件，也不以服务方式运行。支持的 CapCut / 剪映版本与 schema 标志见 docs/version-support.md。

文档与示例

• docs/command-reference.md —— 每个命令与参数
• examples/ —— 端到端示例（配音对齐、serve 自动化、批量字幕修正）
• docs/version-support.md · docs/jianying-encryption.md
• CHANGELOG.md · Releases —— 更新内容
• draftcat —— 姊妹项目：受治理的 AI 流水线（Go, MIT），同样单二进制、无需 API

商标声明

CapCut™ 与剪映™ 为字节跳动有限公司（ByteDance Ltd.）的商标。本项目为非官方项目，与字节跳动无隶属或背书关系；相关商标仅用于指称性描述以说明互操作性。

License

MIT