---
name: beat-sync-editor
display-name-zh: 音乐卡点
description: |
  音乐卡点剪辑 Skill。输入音乐（URL / 本地文件 / AI 生成）+ 视频或图片素材，
  自动完成情绪张力分析 → 智能裁剪 → 节拍分析 → 卡点时间轴生成 → 素材匹配 → ffmpeg 拼接合成，
  输出与音乐完美对齐的卡点视频成片。
  支持图片幻灯片、视频片段、混合素材三种输入，支持每 N 拍换素材、
  前奏/副歌自动分段、用户手动标注关键点等多种卡点模式。
  触发词包括：音乐卡点、卡点剪辑、beat sync、beat-sync video、
  节拍剪辑、卡点视频、音乐节奏剪辑、节奏卡点、beat detection、
  按节拍剪辑、自动卡点、music sync edit。
summary-cn: 输入音乐和素材，自动按节拍卡点剪片
summary-en: Auto beat-sync edit by emotion + cuts
version: 0.2.3
tags: [Video, Audio, Editing, Music]
tags-cn: [视频, 音频, 剪辑, 音乐]
trigger-words:
  - 音乐卡点
  - 卡点剪辑
  - 卡点视频
  - 节拍剪辑
  - 自动卡点
  - beat sync
  - beat-sync video
  - beat detection
  - music sync edit
  - 按节拍剪辑
exported-by: MiniMax-hub
---

# Beat-Sync Editor — 音乐卡点剪辑

当用户想要「把一批图片/视频素材配上音乐，按节拍自动切换」时，使用此 Skill。
核心流程：**音乐来源确认 → 情绪张力分析 → 目标时长裁剪 → 节拍分析 → 时间轴规划 → 素材分配 → ffmpeg 拼接 → 成片**。

---

## STEP 0: 收集输入

确认以下三项输入，缺哪项就问用户：

### 0a. 音乐来源（三选一）

| 类型 | 操作 |
|------|------|
| HTTP/HTTPS URL | 用 `curl -L -o music.ext <url>` 下载到会话目录，记录本地路径 |
| 本地文件路径 | 直接使用，调用 `save_file_to_session` 注册到会话 |
| AI 生成音乐 | 调用 **audio agent**，告知风格/BPM/时长需求，获取生成后的本地路径 |

> **注意**：下载后用 `ffprobe` 验证文件时长，记录 `total_duration`（秒）。

### 0b. 素材列表

支持三种类型（可混合）：

- **图片**（jpg/png/webp）：每张图将被处理成一段静态视频片段
- **视频片段**（mp4/mov）：直接按时间轴截取或整段使用
- **AI 生图补充**：若用户素材数量少于节拍数，告知用户并询问是否调用 image agent 自动补充生图

记录所有素材的本地路径列表。

### 0c. 卡点参数

询问用户（若未指定）：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 检测模式 | `beat` | `beat`=标准节拍 / `onset`=音头（更敏感） / `segment`=自动分段 |
| 每 N 拍换一次 | `1` | `2` 表示每 2 拍换一次素材，节奏感更舒缓 |
| 手动关键点 | 无 | 用户可提供额外时间点（秒），强制在此处切换素材 |
| 输出比例 | `9:16` | 竖屏短视频 / `16:9` 横屏 / `1:1` 方形 |

---

## STEP 0.5: 情绪张力分析 + 目标时长裁剪

> **触发条件**：音频时长 > 用户预期的成片时长，或用户未指定时长但音频超过 60s。
> 若音频已经很短（≤ 30s）或用户明确说"用整首歌"，跳过此步骤直接进入 STEP 1。

### 0.5a. 运行情绪张力分析脚本

使用内置脚本 `scripts/energy_analyze.py`，分析音频的能量分布，找出情绪张力最强的区段：

```bash
python scripts/energy_analyze.py <音乐本地路径> \
  --targets "15,30,60" \
  --out json
```

脚本输出：
- `energy_peak`：全曲能量峰值时间点（秒）
- `sections`：各段落的能量得分排序（高→低）
- `trim_options`：针对每个目标时长（15s / 30s / 60s）的**最佳裁剪窗口**（start, end, energy_score, description）

> **脚本路径**：`scripts/energy_analyze.py`（与 SKILL.md 同目录）

### 0.5b. 向用户展示裁剪方案

将分析结果整理成选项，**用 question 组件**呈现给用户选择：

展示格式示例：
```
🎵 音频总时长：202s | BPM：143 | 情绪峰值点：87.3s

请选择成片时长：

  ① 15秒  ▎起 80.1s → 95.1s  ▏张力 ★★★★★  覆盖最强爆发点，情绪张力最高
  ② 30秒  ▎起 72.0s → 102.0s ▏张力 ★★★★☆  副歌完整段落
  ③ 60秒  ▎起 62.0s → 122.0s ▏张力 ★★★☆☆  含前奏引入 + 完整副歌
  ④ 使用完整音频（202秒）
  ⑤ 自定义时间段（手动输入 start/end）
```

**能量星级换算**：energy_score ≥ 0.85 = ★★★★★，≥ 0.70 = ★★★★☆，≥ 0.55 = ★★★☆☆，其余 = ★★☆☆☆

**默认推荐**：高亮显示 energy_score 最高的选项（通常是时长最短的那个，因为窗口越小越容易聚焦高能区）。

### 0.5c. 按用户选择裁剪音频

用户确认后，用 ffmpeg 裁剪音频为目标片段，后续所有步骤（节拍分析、素材分配、合成）均基于裁剪后的音频：

```bash
ffmpeg -i <原始音频> -ss <start> -to <end> -c copy <audio_trimmed.mp3>
```

> **为什么裁剪后再做节拍分析**：节拍分析的计算量与音频时长成正比；
> 同时裁剪后的 beat_times 直接对应最终视频的时间轴，无需再做偏移换算。

---

## STEP 1: 节拍分析

使用内置脚本 `scripts/beat_detect.py` 进行节拍检测：

```bash
# 安装依赖（首次运行）
pip install librosa soundfile

# 运行检测
python scripts/beat_detect.py <音乐本地路径> \
  --mode <beat|onset|segment> \
  --every-n <N> \
  --manual "<t1,t2,...>" \
  --min-gap 0.25 \
  --out json > beat_result.json
```

脚本输出 JSON，包含：
- `bpm`：检测到的 BPM
- `total_duration`：音乐总时长（秒）
- `beat_count`：有效节拍数
- `beat_times`：节拍时间点列表（秒）
- `sections`（仅 segment 模式）：段落分析结果

> **脚本路径**：`scripts/beat_detect.py`（与 SKILL.md 同目录）

向用户展示检测摘要：BPM、节拍数、时长，确认是否合理后继续。

---

## STEP 2: 时间轴规划

根据节拍分析结果，**在 orchestrator 自行计算**每个素材片段的时间区间：

```
segments = []
for i in range(len(beat_times)):
    start = beat_times[i]
    end   = beat_times[i+1] if i+1 < len(beat_times) else total_duration
    duration = end - start
    segments.append({ "index": i, "start": start, "end": end, "duration": duration })
```

**素材分配规则**：
- 素材数量 ≥ 节拍数：按顺序取前 N 个，多余的丢弃
- 素材数量 < 节拍数：**循环复用**（`material_index = segment_index % len(materials)`），并告知用户有复用
- 若用户不接受复用：提示调用 image agent 按缺口数量补充生图

**segment 模式额外逻辑**：
- 前奏/尾奏（`intro`/`outro`）节拍间隔较宽，建议每拍分配一张素材（慢切）
- 副歌/高潮（含"chorus"的 label）节拍间隔较窄，建议保持原始节拍密度（快切）
- 若用户提供了手动关键点，这些位置强制切换，不受 every-N 参数影响

向用户展示规划摘要表（前 5 行 + 总计），确认继续。

---

## STEP 3: 素材预处理

调用 **editing agent** 批量处理所有素材，统一规格：

告知 editing agent：

> 「请帮我处理以下 N 个素材文件，将每个文件转换为以下规格：
> - 分辨率：[目标宽x高，根据输出比例决定，如 1080x1920]
> - 帧率：30fps
> - 编码：h264，像素格式 yuv420p
> - 对于**图片**：转为 [duration]s 的静态视频（duration 来自时间轴规划）
> - 对于**视频**：截取前 [duration]s，若片段不足则 loop 补齐或 pad 黑帧
> - 对于**尺寸不匹配**：使用 scale+pad（保持原始比例，黑边补齐）
> 输出文件命名：`clip_001.mp4`, `clip_002.mp4` ...」

**为什么预处理**：ffmpeg concat 要求所有片段分辨率、帧率、编码完全一致，否则合成会报错或产生画面撕裂。

---

## STEP 4: 确认预览（可选）

若用户明确要求预览，或素材数量 > 20，**在合成前**展示：
- 时间轴规划表（序号 / 素材文件名 / 开始时间 / 时长）
- 总成片时长预估

询问用户是否有调整：
- 更换某个位置的素材
- 调整 every-N 参数重新规划
- 手动添加/删除关键卡点

如有调整，回到 STEP 2 重新规划，无需重新做节拍分析。

---

## STEP 5: ffmpeg 拼接合成

调用 **editing agent**，提供以下信息：

> 「请将以下片段按顺序拼接，并混入音轨：
>
> 片段列表：`clip_001.mp4`, `clip_002.mp4`, ... `clip_N.mp4`
> （按 STEP 3 生成的文件顺序）
>
> 音轨：`<音乐本地路径>`
>
> 要求：
> - 使用 ffmpeg concat（不转码，直接流合并）
> - 音频使用原始音乐，视频合成后去掉所有素材的原始音轨（-an），避免叠音
> - 音乐若长于视频则截断（`-shortest`），若短于视频则循环（`-stream_loop -1`）
> - 输出文件：`beat_sync_output.mp4`
> - 编码：h264 + aac，质量 CRF 18」

**为什么去掉素材原始音轨**：合成步骤会将音乐轨叠加进来，若保留素材原音会产生双重音频。

---

## STEP 6: 展示成片

向用户展示 `beat_sync_output.mp4`，并附上摘要：

```
✅ 卡点视频生成完成

🎵 音乐：<文件名> | BPM: <bpm>
🎬 素材：<N> 个（图片 X 张 + 视频 Y 段）
⏱ 成片时长：<duration>s
📐 输出比例：<ratio>
🔄 素材是否有复用：<是/否>
```

若用户对成片有以下调整需求：
- **换素材**：更换指定位置的素材 → 回 STEP 3 只重处理该素材，再回 STEP 5 合成
- **调节奏**（改 every-N）→ 回 STEP 2 重新规划
- **换音乐**：全流程重来（STEP 1 起）
- **加转场效果**（淡入淡出等）：告知 editing agent 在合成时对每个片段加 fade filter

---

## 技术说明

### 依赖安装
```bash
pip install librosa soundfile  # 两个脚本共用
```

### energy_analyze.py 脚本参数速查

| 参数 | 说明 | 示例 |
|------|------|------|
| `--targets "15,30,60"` | 要计算的目标时长列表（秒） | 根据场景调整，如 `"30,45,90"` |
| `--out json` | 输出格式（json / text） | text 适合快速调试 |

**能量分析维度**（加权合成）：
- 响度（RMS）× 0.5 — 最直接反映音量强弱
- 节拍冲击强度（Onset Strength）× 0.3 — 反映鼓点/节拍爆发感
- 音色明亮度（Spectral Centroid）× 0.2 — 高能段通常高频更丰富

### beat_detect.py 脚本参数速查

| 参数 | 说明 | 示例 |
|------|------|------|
| `--mode beat` | 标准节拍跟踪（默认） | 流行/电子音乐 |
| `--mode onset` | 音头检测，对打击乐更敏感 | 说唱/鼓点密集曲目 |
| `--mode segment` | 分段分析，自动识别前奏/副歌 | 有明显段落的流行曲 |
| `--every-n 2` | 每 2 拍输出一个切点 | 素材少、节奏舒缓时 |
| `--manual "8.5,32.0"` | 强制在 8.5s 和 32.0s 处加切点 | 用户有特定关键帧需求 |
| `--min-gap 0.5` | 相邻切点最少间隔 0.5s | 防止切换过快 |

### 常见问题

**Q: 情绪分析找到的"高能段"感觉不准？**
→ 可能是弦乐/人声主导的歌曲，能量特征不如打击乐明显。让用户选"自定义时间段"手动输入。

**Q: 检测到的节拍太多，画面切换太快？**
→ 增大 `--every-n`，或增大 `--min-gap`，或换 `segment` 模式

**Q: 某段音乐节拍检测不准（如弦乐、人声段落）？**
→ 改用 `--mode onset`，或让用户手动提供关键时间点 `--manual`

**Q: 素材数量远少于节拍数？**
→ 默认循环复用；或询问用户是否调用 image agent 按差额数量 AI 生图

**Q: ffmpeg 合成报错"Stream codec parameters not set"？**
→ STEP 3 预处理中可能有文件转换失败，让 editing agent 检查并重新处理失败的素材