# CapCut 成片组装

> 将图片/视频素材通过 CapCut 组装为成品视频。支持配音、字幕、特效、音乐、云渲染。

- **触发词**: 图片成片、视频合成、剪映成片、CapCut 渲染

---

## 前置条件

```
1. CapCut Mate API 可达 → curl {config.capcutMateApiBase}/../docs
   - 部署在 capcut.muyetools.cn（配置在 skills/config.json）
2. npm 依赖            → cd scripts && npm install
3. TTS 配音            → 阿里云 CosyVoice TTS（配置在 config.json 的 ttsApiKey）
4. 同步到本地剪映       → 纯 Node.js（sync-to-jianying.js），无需 Python/uv
```

所有路径和 API 地址统一从 `skills/config.json` 读取。

---

## CLI 接口（快速开始）

```bash
node 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` | 否 | 画幅（默认取账号配置） |
| `--output` | 否 | 输出目录 |

---

## 完整流程

```dot
digraph assembly_flow {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  input [label="素材 + manifest.json", shape=folder, fillcolor="#e3f2fd"]
  step1 [label="1. TTS 配音（可选）\ncosyvoice → MP3 + 时长"]
  step2 [label="2. 上传图片到 OSS\n本地图片 → 公网 URL"]
  step3 [label="3. 创建草稿\ncreate_draft → draft_url"]
  step4 [label="4. 导入素材+音频+字幕+特效"]
  step5 [label="5. 保存草稿\nsave_draft"]
  step6 [label="6. 同步本地剪映\n下载→重写→注册→扫描"]
  step7 [label="7. 云渲染（可选）\ngen_video → 成片 MP4", fillcolor="#e8f5e9"]

  input -> step1 -> step2 -> step3 -> step4 -> step5 -> step6 -> step7
}
```

---

## 详细步骤

### 1. TTS 配音（可选）

使用阿里云 CosyVoice TTS 进行语音合成（通过 DashScope WebSocket，Node.js）。

```js
const { synthesize } = require('./qwen-tts')
const { filePath, duration } = await synthesize('文案', { voice: 'Neil', outputDir: './audio' })
// → ./audio/seg_001.mp3, duration: 3.456
```

配置在 `skills/config.json`：

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `ttsApiKey` | 阿里云百炼 API Key | （必填） |
| `ttsModel` | 模型名称 | `cosyvoice-v3.5-plus` |
| `ttsVoice` | 音色名称 | 账号配置 |
| `ttsLanguage` | 语言类型 | `Chinese` |

推荐音色：

| voice 参数 | 音色名 | 风格 | 适用 |
|------|------|------|------|
| `Cherry` | 芊悦 | 阳光积极小姐姐 | 通用、生活 |
| `Serena` | 苏瑶 | 温柔小姐姐 | 情感、故事 |
| `Ethan` | 晨煦 | 阳光温暖男声 | 科技、教程 |
| `Moon` | 月白 | 率性帅气男声 | 潮流、解说 |
| `Vincent` | 田叔 | 沙哑烟嗓男声 | 军事、纪录 |
| `Kai` | 凯 | 温柔磁性男声 | 情感、配音 |
| `Neil` | 阿闻 | 新闻主持人 | 新闻、财经 |
| `Bellona` | 燕铮莺 | 洪亮有力女声 | 热血、武侠 |

所有音色均支持中英文，输出 MP3 格式（24kHz）。

**作为模块调用**：

```js
const { synthesize, synthesizeBatch } = require('./qwen-tts')

// 单段
const { filePath, duration } = await synthesize('你好世界', { voice: 'Cherry' })

// 批量
const results = await synthesizeBatch(
  [{ id: 1, text: '文案' }, { id: 2, text: '文案2' }],
  { voice: 'Cherry', outputDir: './audio' }
)
```

### 2. 图片上传

CapCut API 需要公网 URL，本地图片通过 OSS 上传：

```bash
node scripts/oss-upload.js ./image.png
# → https://i.ibb.co/xxx/image.png
```

OSS 配置在 `skills/config.json` 的 `ossRegion/ossAccessKeyId/ossAccessKeySecret/ossBucket` 中。

`capcut_assemble.js` 自动处理上传，无需手动调用。

### 3. 创建草稿

```
POST /create_draft  { width: 1080, height: 1920 }
→ 返回 draft_url（后续所有操作都需要传入）
```

### 4. 导入素材

**图片模式** (`--mode images`):

```
POST /add_images
每张图片 3-5 秒，附带动画（默认缩放）
```

**视频模式** (`--mode videos`):

```
POST /add_videos
逐个添加视频片段，自动计算时长
```

### 5. 添加音频

```
POST /add_audios
- BGM: 账号默认音乐 或 用户指定 URL
- 配音: Step 1 生成的 TTS 音频
```

### 6. 添加字幕

```
POST /add_captions
- 文案来自 manifest.json（TTS 分句时按 segment 精确对齐）
- 字体大小、颜色从账号配置读取
```

### 7. 添加特效/滤镜

```
POST /add_effects   ← account.json 中 capcut.effects
POST /add_filters   ← account.json 中 capcut.filter
```

### 8. 保存 + 同步 + 渲染

**保存草稿（服务器端）：**

```
POST /save_draft → 保存到 CapCut Mate 服务器
```

**同步到本地剪映（纯 Node.js）：**

```
sync-to-jianying.js → 下载素材文件 → 路径重写为本地 → 写入剪映草稿目录 → 注册 root_meta_info.json → 触发目录扫描
```

无需 Python/uv，`capcut_assemble.js` 自动调用。

**504 超时回退：**

add_videos 提交 9+ 视频时可能触发网关 504。脚本自动降级：
1. 先尝试全量提交
2. 504 时自动分批（每批 3 个），保持绝对时间不变


---

## 图片动画预设

| 动画名称 | 说明 | 适用场景 |
|---------|------|---------|
| 缩放 | 缓慢放大 | 默认，适合大多数场景 |
| 渐显+放大 | 淡入+放大组合 | 强调、冲击感 |
| 左平移 | 右→左平移 | 风景、全景 |
| 右平移 | 左→右平移 | 风景、全景 |

---

## 质量检查

- [ ] 字幕与文案对应正确
- [ ] 图片动画流畅（无卡顿）
- [ ] BGM 音量与配音平衡
- [ ] 转场自然（无黑帧）
- [ ] 总时长合理（建议 30-90 秒）