227 lines
7.3 KiB
Markdown
227 lines
7.3 KiB
Markdown
---
|
||
name: capcut
|
||
description: 剪映/CapCut 自动化。通过 CapCut Mate API 实现草稿创建、素材导入、字幕添加、特效动画及云端渲染。支持两种模式：(1) API模式 — 单个接口调用；(2) 成片模式 — 素材目录一键组装（TTS配音+字幕+特效+BGM+云渲染）。触发词：剪映、CapCut、视频编辑、图片成片、视频合成、成片、CapCut组装、图片轮播、配音+成片。
|
||
---
|
||
|
||
# CapCut Mate 剪映自动化
|
||
|
||
通过 CapCut Mate API 自动化剪映草稿创建、素材导入及云端渲染。
|
||
|
||
## 前置条件
|
||
|
||
使用远程 CapCut Mate API（`config.capcutMateApiBase`），无需本地部署。
|
||
路径和密钥统一配置在 `skills/config.json`。
|
||
|
||
视频/音频素材通过 OSS 上传获取公网 URL（API 需要可下载的 URL）。
|
||
上传工具：`node .claude/skills/video-from-script/scripts/oss-upload.js`
|
||
|
||
**成片模式额外依赖：**
|
||
|
||
```
|
||
1. npm 依赖 → cd .claude/skills/video-from-script/scripts && npm install
|
||
2. TTS 配音 → 阿里云 Qwen-TTS（config.json 中配置 ttsApiKey）
|
||
```
|
||
|
||
---
|
||
|
||
## 两种使用模式
|
||
|
||
### 模式一：API 模式（单接口调用）
|
||
|
||
用户给具体指令（加字幕、加特效等），Claude 直接调单个 API。
|
||
|
||
典型工作流：
|
||
|
||
```
|
||
1. create_draft(width, height) → draft_url
|
||
2. add_videos / add_images → 添加素材
|
||
3. add_audios → 添加配音/音乐
|
||
4. add_captions → 添加字幕（支持关键词高亮）
|
||
5. add_effects / add_keyframes → 特效和动画
|
||
6. save_draft → 保存
|
||
7. gen_video → 提交云端渲染
|
||
8. gen_video_status → 轮询进度
|
||
```
|
||
|
||
### 模式二：成片模式（一键组装）
|
||
|
||
用户给素材目录 + manifest.json，走 CLI 自动流水线。
|
||
|
||
```bash
|
||
node .claude/skills/video-from-script/scripts/capcut_assemble.js \
|
||
--input ./output/batch_xxx \
|
||
--manifest ./output/batch_xxx/manifest.json \
|
||
--mode images|videos \
|
||
--subtitles true \
|
||
--bgm <url> \
|
||
--effects "录制边框 III,雪花" \
|
||
--filter "电影感:50" \
|
||
--format 9:16 \
|
||
--output ./output/final/
|
||
```
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--input` | 是 | 素材目录 |
|
||
| `--manifest` | 是 | manifest.json 路径 |
|
||
| `--mode` | 是 | `images` 或 `videos` |
|
||
| `--subtitles` | 否 | 字幕（默认 true） |
|
||
| `--bgm` | 否 | 背景音乐 URL |
|
||
| `--effects` | 否 | 特效，逗号分隔 |
|
||
| `--filter` | 否 | 滤镜名称:强度 |
|
||
| `--format` | 否 | 画幅（默认账号配置） |
|
||
|
||
**完整流程：**
|
||
|
||
```dot
|
||
digraph capcut_assembly {
|
||
rankdir=LR
|
||
node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]
|
||
edge [fontsize=10]
|
||
|
||
input [label="素材 + manifest.json", shape=folder, fillcolor="#e3f2fd"]
|
||
|
||
step1 [label="1. TTS 配音（可选）\nnode qwen-tts.js\n→ WAV + 时长"]
|
||
step2 [label="2. 上传图片到 OSS\n本地图片 → 公网 URL"]
|
||
step3 [label="3. 创建草稿\ncreate_draft\n→ draft_url"]
|
||
step4 [label="4. 导入素材+音频+字幕+特效\nadd_images / add_videos\nadd_audios / add_captions\nadd_effects"]
|
||
step5 [label="5. 保存草稿\nsave_draft"]
|
||
step6 [label="6. 同步本地剪映\nsync-to-jianying.js\n下载→重写→注册→扫描"]
|
||
step7 [label="7. 云渲染（可选）\ngen_video → 成片 MP4", fillcolor="#e8f5e9"]
|
||
|
||
input -> step1 -> step2 -> step3 -> step4 -> step5 -> step6 -> step7
|
||
}
|
||
```
|
||
|
||
**模式选择规则：**
|
||
- 用户提到"成片"、"组装"、"图片轮播"、"配音+成片" → 成片模式
|
||
- 用户给具体操作指令（加字幕、加特效等） → API 模式
|
||
- 不确定时 → 询问用户
|
||
|
||
---
|
||
|
||
## 通用约定
|
||
|
||
- **时间单位**: 微秒（1秒 = 1,000,000）
|
||
- **xxx_infos 参数**: JSON **字符串**（需 `JSON.stringify`），非对象
|
||
- **draft_url**: 创建草稿后返回，后续所有操作都需要传入
|
||
|
||
---
|
||
|
||
## 核心接口速查
|
||
|
||
| 接口 | 用途 | 关键参数 |
|
||
|------|------|----------|
|
||
| `create_draft` | 创建草稿 | width, height |
|
||
| `add_videos` | 添加视频 | video_infos (URL+时长+转场) |
|
||
| `add_images` | 添加图片 | image_infos (URL+动画+转场) |
|
||
| `add_audios` | 添加音频 | audio_infos (URL+时长) |
|
||
| `add_captions` | 添加字幕 | captions (文本+关键词高亮+时间线) |
|
||
| `add_effects` | 添加特效 | effect_infos (名称+时间线) |
|
||
| `add_keyframes` | 关键帧动画 | keyframes (segment_id+属性+值) |
|
||
| `easy_create_material` | 一站式添加 | video/img/audio/text |
|
||
| `gen_video` | 云端渲染 | draft_url + apiKey |
|
||
|
||
## 工具类接口
|
||
|
||
| 接口 | 入参 | 产出 |
|
||
|------|------|------|
|
||
| `audio_timelines` | `links: [mp3 URLs]` | 自动算时间线 |
|
||
| `audio_infos` | mp3_urls + timelines | add_audios 的 audio_infos |
|
||
| `caption_infos` | texts + timelines + keywords | add_captions 的 captions |
|
||
| `effect_infos` | effects[] + timelines | add_effects 的 effect_infos |
|
||
| `video_infos` | URLs + timelines | add_videos 的 video_infos |
|
||
| `imgs_infos` | URLs + timelines | add_images 的 image_infos |
|
||
| `get_audio_duration` | mp3_url | 音频时长（微秒） |
|
||
| `get_text_animations` | 无 | 可用文本动画列表 |
|
||
| `get_image_animations` | 无 | 可用图片动画列表 |
|
||
| `search_sticker` | 关键词 | 贴纸列表（含 sticker_id） |
|
||
| `get_url` | 文本 | 提取 URL |
|
||
|
||
## 完整 API 参数文档
|
||
|
||
详细的请求参数、响应格式、字段说明见 [api-reference.md](references/api-reference.md)
|
||
|
||
---
|
||
|
||
## TTS 配音（成片模式用）
|
||
|
||
使用阿里云 Qwen-TTS（Node.js），替代原 Edge-TTS。
|
||
|
||
```bash
|
||
# 准备输入
|
||
echo '{"segments":[{"id":1,"text":"文案"}],"voice":"Cherry","output_dir":"./audio"}' > input.json
|
||
|
||
# 生成
|
||
node .claude/skills/video-from-script/scripts/qwen-tts.js input.json
|
||
# → stdout: {"segments":[{"id":1,"audio":"./audio/seg_001.wav","duration":3.456}]}
|
||
```
|
||
|
||
配置在 `skills/config.json`：`ttsApiKey`（必填）、`ttsModel`、`ttsVoice`、`ttsLanguage`。
|
||
|
||
推荐音色：
|
||
|
||
| 音色 | 风格 | 适用 |
|
||
|------|------|------|
|
||
| `Cherry` | 阳光积极小姐姐 | 通用、生活 |
|
||
| `Ethan` | 阳光温暖男声 | 科技、教程 |
|
||
| `Vincent` | 沙哑烟嗓 | 军事、纪录 |
|
||
| `Neil` | 新闻主持人 | 新闻、财经 |
|
||
| `Moon` | 率性帅气男声 | 解说、潮流 |
|
||
|
||
---
|
||
|
||
## 账号配置
|
||
|
||
`account.json` 中 CapCut 相关字段：
|
||
|
||
```json
|
||
{
|
||
"capcut": {
|
||
"effects": ["录制边框 III"],
|
||
"filter": "电影感:40",
|
||
"subtitleStyle": {
|
||
"fontSize": 36,
|
||
"color": "#FFFFFF",
|
||
"highlightColor": "#FF6B35",
|
||
"bold": true
|
||
},
|
||
"defaultBGM": "https://example.com/bgm.mp3"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 图片动画预设
|
||
|
||
| 动画 | 说明 | 适用 |
|
||
|------|------|------|
|
||
| Ken Burns (zoom-in) | 1.0→1.1 缓慢放大 | 默认 |
|
||
| Ken Burns (pan-left) | 右→左平移 | 风景 |
|
||
| Ken Burns (pan-right) | 左→右平移 | 风景 |
|
||
| 缩放弹出 | 0.8→1.0 | 强调 |
|
||
|
||
---
|
||
|
||
## 质量要求
|
||
|
||
- 字幕与文案对应正确，关键词高亮醒目
|
||
- 图片动画流畅（Ken Burns 幅度 1.0→1.1）
|
||
- BGM 音量不盖过配音（配音为主、BGM 为辅）
|
||
- 转场自然（无黑帧、无跳帧）
|
||
- 底部字幕区不被遮挡
|
||
- 总时长 30-90 秒（保证完播率）
|
||
- 9:16 竖屏适配抖音/快手，16:9 横屏适配 B 站
|
||
|
||
---
|
||
|
||
## 成片模式详细参考
|
||
|
||
完整步骤说明、API 调用细节见 [assembly-guide.md](references/assembly-guide.md)
|
||
|
||
## index.js 封装
|
||
|
||
当前 `index.js` 只封装了 3 个接口（createDraft, addVideos, genVideo）。
|
||
调用其他接口时，直接用 axios POST 对应的 API 路径即可。
|