---
name: qiaomu-mtv-creator
description: AI MTV/MV 制作工具。将 Suno 生成的歌曲自动转换为传统 MTV 或 HyperFrames/GSAP kinetic MV。触发词包括"制作MTV"、"生成MV"、"歌曲转视频"、"/mtv"。支持 Suno SRT/LRC、qiaomu-suno-master 下载、storyboard、Codex 生图计划、HyperFrames 动态歌词、GSAP 动效和 FFmpeg 合成。
---

# Qiaomu MTV Creator - AI 音乐视频制作

将 Suno 生成的歌曲自动转换为两类 MV：稳定快速的传统配图字幕版，以及更像音乐视频的 HyperFrames/GSAP 动态歌词版。

## V2.4 升级要点

- **MTV 审美规则沉淀**：新增“画面、字幕、转场、字体、验收”的设计原则。未来不要把 Hyper MV 做成固定底部字幕的幻灯片；每首歌都要有和歌词意象一致的 motion grammar。
- **字幕系统升级**：默认 Hyper 模板要使用多安全区 anchor、轻微倾斜、词级 stagger、回声/描边/玻璃质感等可控变化。字幕可以不规则，但必须服务歌曲气质；避免逐帧抖动、过度缩放、粗糙旋转和一直居中。
- **转场系统升级**：图片之间不只做淡入淡出。默认组合柔和溶解、玻璃擦拭、光扫、纹理遮罩、轻微场景分层，让镜头推进保留，同时让 scene change 有记忆点。
- **字体本地化**：Hyper 模板默认打包 `Anton` + `Space Grotesk` 本地 woff2，避免渲染时回退到系统字体导致质感变差或不同机器表现不一致。
- **去模板痕迹**：片头必须使用真实歌曲标题，优先从 LRC `[ti:]`、项目元数据或字幕文件名读取，并清理 clip/hash 后缀；motion profile、debug label、URL slug、占位文字不能出现在成片里。
- **固定作者署名**：所有歌曲作者/artist/author 默认写 `向阳乔木`。不要从 Suno、文件名、URL、LRC `[by:]` 或模型输出里猜作者；片头需要署名时也使用 `向阳乔木`。
- **音频 UI 默认关闭**：波形、频谱、进度条、节拍脉冲不再作为默认装饰。只有当歌曲概念明确需要“播放器/电台/信号/电子可视化”时才打开；冷感、叙事、梦幻歌曲默认不出现这些界面化元素。
- **渲染脚本稳定化**：`render_hyper_mtv.py` 默认使用本机 Puppeteer headless shell、streaming encode、长超时、缓存限制和 SDR 输出，并按可回收内存选择 worker，减少手动拼环境变量和系统 Chrome 崩溃概率。

## V2.3 升级要点

- **新名字**：主 skill 名为 `qiaomu-mtv-creator`；旧名 `mtv-creator` 不再保留，避免别名误触发。
- **单源目录**：skill 实体只放在 `/Users/joe/.agents/skills/qiaomu-mtv-creator`；不要再创建 `.claude` 兼容软链或 `mtv-creator` 旧名入口。
- **双模式**：`classic` 保留传统 FFmpeg 配图字幕工作流；`hyper` 用 HyperFrames + GSAP 制作动态歌词、场景内排版、音频响应和更丰富转场。
- **GSAP 官方技能吸收**：已吸收 `greensock/gsap-skills` 的 core/timeline/plugins/utils/performance 规则，落到 `references/gsap-mtv-motion.md`，并由 `scripts/create_hyper_mtv.py` 自动生成更丰富的 HyperFrames/GSAP MTV 工程。
- **动效谱系**：Hyper 模式新增 `cinematic`、`poster`、`glitch`、`dream`、`minimal` 五个 motion profile，用 GSAP timeline labels、position parameter、stagger、transform aliases、`autoAlpha`、`gsap.utils.wrap()` 等模式组织场景、歌词、粒子、光扫和节拍脉冲。
- **渲染加速策略**：新增 `scripts/render_hyper_mtv.py`，根据可用内存选择 HyperFrames `quality/fps/workers`；低内存时先提示清理，不再默认硬开 auto workers。
- **SRT/LRC 统一**：自动识别 Suno 同版本 `.srt` / `.lrc`，LRC 会转换为项目内可烧录 SRT。
- **项目化输出**：每次生成 `project.json`、`timeline.json`、`preflight_report.json`、`storyboard.html`。
- **可恢复阶段**：通过 `--stage preflight|prepare|storyboard|images|compose|hyper|all` 分步运行。
- **Codex 生图优先**：`--image-provider auto` 在 Codex 环境中解析为 `codex-plan`，优先让 Codex 内置生图接管关键帧；只有 Codex 生图不可用或非 Codex 运行时才回退即梦。
- **字幕 fallback**：如果本机 FFmpeg 没有 `subtitles` / `drawtext` filter，会自动用 Pillow 渲染透明字幕层再 overlay。

## 核心流程

```
Suno 歌曲（含 .srt / .lrc 精准歌词）
    ↓
解析为统一 timeline.json → preflight 检查 → storyboard.html
    ↓
Claude/Codex 读歌词 → 分析歌曲结构 → 生成 visual_config.json
    ↓
生图：优先 Codex 内置生图计划；失败或不可用时才用即梦批量落盘 fallback
    ↓
合成 MV：classic 用 FFmpeg；hyper 用 HyperFrames + GSAP kinetic timeline
    ↓
输出: MTV 视频 (MP4)
```

## ⚠️ 重要原则

1. **用 Suno SRT，不用 Whisper**：Suno 生成歌曲时已自动生成精准 SRT，路径与 mp3 同目录，优先使用
2. **Claude 直接生成描述**：Claude Code 本身就是大模型，读 SRT 后直接生成视觉描述，不调第三方 API
3. **音频选版本**：Suno 会生成两个版本（.mp3 和 -1.mp3），选时长更长、覆盖所有 SRT 时间戳的版本
4. **skill 单源在 .agents**：所有新增和修改都落在 `/Users/joe/.agents/skills/qiaomu-mtv-creator`；不要恢复 `.claude` 兼容软链或旧 `mtv-creator` 别名
5. **Codex 生图优先，不先跑即梦**：Codex 内置生图质量通常更适合关键帧；脚本生成 `codex_image_requests.md` 供 Codex 接管。只有 Codex 生图不可用、用户明确要求 fallback、或非 Codex 自动运行时，才使用即梦。
6. **Suno 资料先走 qiaomu-suno-master**：遇到 Suno URL、clip ID、下载音频、导出 LRC/SRT，先使用 `/Users/joe/.agents/skills/qiaomu-suno-master`，不要先手写抓页面。
7. **Hyper 渲染先看内存**：`hyperframes render --workers auto` 在可用内存很低时会同时启动多个浏览器并失败；最终渲染前先跑 `render_hyper_mtv.py --dry-run`，低于阈值时请用户清理内存，除非用户接受慢速 `--allow-low-memory`。
8. **GSAP 只用可渲染时间线**：HyperFrames 里 GSAP 必须同步创建 paused timeline，注册到 `window.__timelines.main`；不要 `tl.play()`、不要 `Date.now()` / `Math.random()` / 网络 fetch / 无限 repeat。
9. **MV 不是歌词 PPT**：默认避免“整首歌固定底部居中字幕 + 每张图同一种淡入淡出”。字幕、转场、镜头和氛围层都要有歌曲自己的节奏，但不能抢歌词。
10. **字幕稳定优先**：字幕动效可以丰富，但不能抖。优先使用 `autoAlpha`、`y`、低幅度 `rotation`、词级 `stagger` 和长一点的 `sine/power` ease；少用大幅 `scale`、`rotationX`、短促抖动和频繁 filter 切换。
11. **从歌词意象生成 motion grammar**：玻璃、雨、盐、霓虹、纸张、广播、海、风等意象要变成对应的视觉动效语言，例如 glass wipe、rain streak、salt grain、signal scan、paper slip，而不是套同一套模板。
12. **不要让模板身份露出**：片头可以有设计标题，但不能出现 `Poster Motion`、`cinematic motion`、`placeholder`、URL slug、clip id/hash、脚本调试名。真实歌名优先从 LRC `[ti:]` 获取，例如 `Salt On Glass`，不要显示 `salt-on-glass-ba258447`。
13. **不要把 MV 做成播放器界面**：波形、频谱、进度条、均衡器、底部节拍线默认关闭。除非歌曲主题是广播、电台、信号、俱乐部、电子设备或用户明确要求，否则这些元素会破坏沉浸感。
14. **作者固定为向阳乔木**：项目元数据、HyperFrames `mtv-data.json`、片头署名、发布说明中的歌曲作者统一写 `向阳乔木`，不要使用 Suno AI、下载账号、文件名、URL slug 或 LRC `[by:]` 作为作者。

## MTV 设计原则与风格原则

做 Hyper MTV 时先定一个 4 层视觉系统，而不是直接套模板：

1. **画面层**：关键帧要有统一摄影/插画风格、稳定色彩、重复母题。镜头推进可以慢，但每个段落的推进方向、焦点和速度要略有差别。
2. **字幕层**：字幕是 MV 的表演者，不是外挂字幕。每行歌词可以在 4-7 个安全 anchor 中切换：左下、右上、右中、左墙、低位桌面、居中宽屏等。位置变化要和画面负空间匹配，不能遮住主要主体。
3. **字体层**：每支 MV 至少有明确字体气质。优先选择凝练、有音乐感的 display sans / condensed sans；不要默认系统粗体一直居中。温柔歌用窄体、细腻阴影、低对比回声；强烈歌再用红色描边、glitch、切片。
4. **转场层**：每个 scene change 至少叠加两种转场语言，例如 cross-dissolve + glass sweep、soft bloom + texture wipe、rain scan + parallax drift。避免所有图片之间同一种 xfade。
5. **氛围层**：粒子、波形、光扫、噪声、进度条要低调服务节奏。不要为了“动”而动；能表达歌词母题的动效优先。
6. **片头层**：片头是作品的一部分，不是模板封面。只显示真实歌名或经过设计的短标题；作者署名统一写 `向阳乔木`。不要显示 motion profile、工程名、哈希后缀、下载文件名、调试标签。

字幕风格要按歌曲气质调节：

- **梦幻/怀旧/冷感**：位置有轻微漂移但不跳；文字可偏左/偏右，带玻璃回声、柔和描边、低透明度重复影；转场用长溶解、光扫、雾化遮罩。
- **摇滚/脏感/强节拍**：可使用更大字号、upper-case、红色/暖色强调词、切片、扫描线和短促冲击，但要控制在副歌或强拍。
- **民谣/叙事/安静**：减少字词拆分，使用低位、侧边或画面负空间的排版；用纸张、影子、窗光、慢变焦表达段落。
- **电子/赛博/不稳定**：允许 glitch、scanline、短促位移和硬切，但要避免全程抖动造成阅读疲劳。

质量门槛：

- 抽帧时不能整首歌都像同一个字幕位置的重复截图。
- 相邻两三帧字幕边缘不应出现肉眼可见抖动。
- 转场不能黑屏，不能只有硬淡出；至少几处 scene change 要能看出歌曲母题。
- 标题/水印式模板文字默认只用于片头，不能整首歌常驻左上角干扰歌词；片头也不能出现 profile label、slug 或 hash。
- 波形、频谱、进度条、节拍线这类播放器 UI 默认不出现；抽帧看到它们时，需要能说清楚它们为什么属于这首歌。

## 标准工作流（Claude Code 操作）

### Step 1：准备项目与 Storyboard

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --style ink-painting \
    --ratio 16:9 \
    --stage prepare
```

检查输出：

```
project.json
timeline.json
preflight_report.json
storyboard.html
visual_config.json
codex_image_requests.md
```

### Step 2A：Codex 内置生图接管关键帧（默认优先）

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --style ink-painting \
    --ratio 16:9 \
    --stage prepare
```

然后由 Codex 读取 `codex_image_requests.md` 逐张生成 `images/scene_XX.png`。完成后：

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --visual-config "/path/to/project/visual_config.json" \
    --stage compose
```

### Step 2B：即梦 fallback（仅 Codex 生图不可用时）

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --style ink-painting \
    --ratio 16:9 \
    --output ~/Videos/MTV/项目名/ \
    --skip-transcribe \
    --subtitle "/path/to/song.srt" \
    --visual-config "/path/to/project/visual_config.json" \
    --stage images \
    --image-provider jimeng \
    --workers 5
```

### Step 2C：HyperFrames / GSAP 动态歌词 MV（推荐模式）

适合用户明确要求“不像幻灯片”“歌词更酷”“画面随音乐动”“参考 HyperFrames”的任务。传统 `classic` 模式仍然保留；`hyper` 是更高表现力、更慢但更像 MV 的模式。

工作流：

1. 先用本 skill 的 `prepare` 生成 `timeline.json`、`visual_config.json`、关键帧生图计划。
2. 用 Codex 内置生图生成 `images/scene_XX.png`。
3. 运行 `--stage hyper` 自动生成 `hyper-mv/`：复制音频/关键帧，写入 `assets/mtv-data.js`，创建本地 `assets/gsap.min.js` 和 GSAP-rich `index.html`。
4. 先运行 `npm run check` 和 `npx hyperframes inspect --samples 24`，确认没有 console error、对比度问题、歌词越界。
5. 快速预览用 draft profile，最终版用 final profile。

生成 HyperFrames 工程：

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --subtitle "/path/to/song.srt" \
    --visual-config "/path/to/project/visual_config.json" \
    --stage hyper \
    --motion-profile cinematic
```

动效谱系：

| Profile | 适用 | 特点 |
|---------|------|------|
| `cinematic` | 流行、摇滚、叙事歌 | 慢推拉、稳重歌词入场、克制节拍脉冲 |
| `poster` | 复古、民谣、插画风 | 海报纸感、轻微错位、块面化歌词 |
| `glitch` | 电子、愤怒、赛博 | 扫描线、短促抖动、锐利切换 |
| `dream` | 氛围、怀旧、柔和歌曲 | 长溶解、漂浮粒子、柔和 blur-in |
| `minimal` | 细腻歌词、spoken 段落 | 少动效、安静淡入淡出 |

快速预览：

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/render_hyper_mtv.py \
    --project "/path/to/project/hyper-mv" \
    --profile review
```

最终渲染：

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/render_hyper_mtv.py \
    --project "/path/to/project/hyper-mv" \
    --profile final \
    --check
```

优先使用 `render_hyper_mtv.py` 而不是手写 `npx hyperframes render`。脚本会自动：

- 选择本机 Puppeteer `chrome-headless-shell`，避免系统 Chrome 版本/权限导致渲染不稳。
- 开启 streaming encode，长视频不先堆满帧缓存。
- 设置 Puppeteer 启动/协议超时、帧缓存上限和 `--sdr`。
- 按内存自动选择 worker；需要更快时先看 `--dry-run` 输出，再决定是否显式 `--workers 2/3`。

如果脚本提示 `LOW MEMORY`，先请用户清理内存或关闭重型应用，再重新渲染。只有用户明确接受“慢一点也行”时，才使用：

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/render_hyper_mtv.py \
    --project "/path/to/project/hyper-mv" \
    --profile final \
    --allow-low-memory
```

刚才实测教训：`hyperframes render --workers auto` 在 0.3GB immediate free memory 时会校准后尝试多 worker，随后多个浏览器进程同时启动失败；`--workers 1` 可以完成，但 220 秒 1080p 视频耗时约 7 分 39 秒。因此默认策略是：内存足够时多 worker 换速度，内存低时先问用户清理，而不是静默退到慢速。

## 参数说明

| 参数 | 短参数 | 默认值 | 说明 |
|------|--------|--------|------|
| `--audio` | `-a` | (必填) | 音频文件路径 |
| `--lyrics` | `-l` | 自动查找 | 歌词文件路径（.lyrics.json） |
| `--style` | `-s` | newyorker | 配图风格（见风格列表） |
| `--ratio` | `-r` | 9:16 | 视频比例（9:16/16:9/1:1） |
| `--output` | `-o` | ~/Videos/MTV/ | 输出目录 |
| `--workers` | `-w` | 3 | 并发生成配图数（推荐 5） |
| `--stage` | | all | 分阶段运行：preflight/prepare/storyboard/images/compose/hyper/all |
| `--image-provider` | | auto | 生图后端：auto/codex-plan/jimeng/none；auto 在 Codex 中优先 codex-plan，非 Codex 才回退 jimeng |
| `--motion-profile` | | cinematic | HyperFrames/GSAP 动效谱系：cinematic/poster/glitch/dream/minimal |
| `--hyper-dir` | | 项目目录/hyper-mv | HyperFrames 工程输出目录 |
| `--preflight-only` | | false | 只检查输入和时间轴 |
| `--storyboard-only` | | false | 只生成 storyboard 预览 |
| `--no-subtitle` | | false | 不烧录字幕 |
| `--skip-transcribe` | | false | 跳过转录（现在会自动优先使用 Suno SRT/LRC，通常不必手动指定） |
| `--skip-images` | | false | 跳过生图（已有图片时使用） |
| `--subtitle` | | 自动查找 | 指定 SRT/LRC 文件路径 |
| `--images-dir` | | 自动 | 指定已有图片目录 |
| `--visual-config` | | - | 指定配图配置文件 |

## 风格推荐

| 歌曲类型 | 推荐风格 |
|----------|----------|
| 摇滚/硬核 | `newyorker`, `pen-sketch`, `woodcut` |
| 民谣/抒情 | `watercolor`, `ink-painting`, `morandi` |
| 电子/流行 | `flat-illustration`, `isometric`, `low-poly` |
| 古风/中国风 | `ink-painting`, `woodcut`, `retro-poster` |
| 儿歌/轻松 | `children-book`, `cartoon`, `paper-cut` |

完整风格列表见 `qiaomu-image-generator` skill。

## 工作流详解

### Step 1: 字幕与时间轴

优先使用 Suno 同目录字幕：
- 精确匹配 `歌名.mp3` → `歌名.srt` / `歌名.lrc`
- 精确匹配 `歌名-1.mp3` → `歌名-1.srt` / `歌名-1.lrc`
- LRC 自动转换为项目内 SRT
- 只有找不到 Suno 字幕时才调用 `whisper-transcribe`
- 输出 `timeline.json` 和 `preflight_report.json`

### Step 2: 分析歌词生成配图描述

Claude 分析歌词，为每个段落生成视觉描述：
- 提取核心意象和情感
- 转换为纯视觉语言（无文字）
- 生成 `visual_config.json`

**示例**：
```
歌词: "午夜的终端闪烁着光，键盘就是我的战场"
描述: "深夜办公室，一个人影坐在发光的屏幕前，手指悬停在键盘上，周围是代码的光影"
```

### Step 3: 生成配图

默认优先 Codex 内置生图：
- `--image-provider auto` 在 Codex 环境中生成 `codex_image_requests.md`
- 审阅 `codex_image_requests.md`
- 用 Codex 内置生图生成 `images/scene_XX.png`

即梦只作为 fallback：
- Codex 生图不可用、用户明确接受 fallback，或非 Codex 环境中 `auto` 运行时，才调用 `qiaomu-image-generator`
- fallback 时显式使用 `--image-provider jimeng`

### Step 4: 合成视频

classic 模式调用内置 FFmpeg 合成：
- 音频 + 图片 + 字幕 → MP4
- 平滑转场效果
- 专业字幕烧录
- 自动修正 `xfade` 重叠造成的时长缩短

hyper 模式调用 `scripts/create_hyper_mtv.py`：
- 读取 `project.json`、`timeline.json`、`visual_config.json`
- 复制音频和 `images/scene_XX.*` 到 `hyper-mv/assets/`
- 安装并复制本地 `gsap.min.js`，避免 CDN 在渲染时失败
- 生成一个 paused GSAP master timeline：scene layers、kinetic lyrics、beat pulse、wave bars、particles、progress
- 后续用 `scripts/render_hyper_mtv.py` 做 review/final 渲染

## 输出结构

```
~/Videos/MTV/代码丛林_20260125/
├── 代码丛林.mp4           # 最终 MTV
├── project.json           # MTV 项目元数据
├── timeline.json          # 统一字幕/场景时间轴
├── preflight_report.json  # 输入、依赖、字幕覆盖率检查
├── storyboard.html        # 可审阅分镜预览
├── codex_image_requests.md # Codex 内置生图 prompt 清单
├── audio/
│   └── 代码丛林.mp3       # 原始音频
├── subtitles/
│   ├── 代码丛林.srt       # 字幕文件
│   └── 代码丛林.json      # 时间轴 JSON
├── images/
│   ├── scene_01.png       # 配图 1
│   ├── scene_02.png       # 配图 2
│   └── ...
├── visual_config.json     # 配图配置
├── metadata.json          # 项目元数据
└── hyper-mv/              # HyperFrames/GSAP 动态歌词工程（--stage hyper）
    ├── index.html
    ├── package.json
    └── assets/
        ├── mtv-data.js
        ├── gsap.min.js
        ├── song.mp3
        └── images/
```

## 与其他 Skills 的关系

| Skill | 角色 |
|-------|------|
| `suno-music-creator` | 上游：生成歌曲和歌词 |
| `whisper-transcribe` | 依赖：转录时间轴 |
| `qiaomu-image-generator` | 依赖：生成配图（即梦 API） |
| `ffmpeg` | 依赖：合成视频、烧录字幕、社交平台兼容编码 |
| `podcast-to-video` | 参考：字幕和合成风格最佳实践 |
| `gsap` / `greensock/gsap-skills` | Hyper 模式动效规则来源：timeline、stagger、plugins、utils、performance |

## GSAP / HyperFrames 动效规则

详细规则见 `references/gsap-mtv-motion.md`。做 Hyper MTV 时至少遵守：

- 用 `gsap.timeline({ paused: true })`，注册 `window.__timelines.main`。
- 用 labels 和 position parameter 编排场景、歌词、节拍，不用散乱 `delay`。
- 优先 transform aliases 和 `autoAlpha`；少动画 layout 属性。
- `gsap.utils.wrap()` / `clamp()` / `toArray()` 用于确定性映射，不用 `Math.random()`。
- 默认核心 GSAP 足够；SplitText、ScrambleText、MotionPath、DrawSVG、MorphSVG 等插件只在本地 asset 可用且显式注册时使用。

## 推荐工作流（Claude 生成描述）

**最佳实践**：让 Claude 分析歌词并生成视觉描述，而不是使用简单的关键词匹配。

### Step 1: 准备阶段

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio ~/乔木新知识库/04.素材/AI音乐/代码丛林.mp3 \
    --prepare-only \
    --scenes 8
```

这会输出每个场景的歌词，等待 Claude 生成视觉描述。

### Step 2: Claude 生成描述

在 Claude Code 对话中：

```
用户：为以下歌词场景生成视觉描述（纯视觉语言，不要文字）：

场景 1: "午夜的终端闪烁着光，键盘就是我的战场"
场景 2: "代码在眼前不停旋转，这个 Bug 藏得太深太远"
...

Claude：
场景 1: 深夜办公室，一个人影坐在发光的屏幕前，手指悬停在键盘上，周围是代码的光影
场景 2: 迷宫般的电路板，一个人在其中寻找出路，远处有微弱的光点
...
```

### Step 3: 更新配置并生成

将 Claude 生成的描述更新到 `visual_config.json`，然后：

```bash
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio ~/乔木新知识库/04.素材/AI音乐/代码丛林.mp3 \
    --visual-config ~/Videos/MTV/代码丛林_20260125/visual_config.json \
    --skip-transcribe
```

## 完整示例

### 从 Suno 歌曲到 MTV

```bash
# 1. 生成歌曲（suno-music-creator）
python /Users/joe/.agents/skills/suno-music-creator/scripts/generate_music.py \
    '{"title":"代码丛林","prompt":"[Verse 1]...","tags":"rock"}' \
    --download

# 2. 一键生成 MTV（本 skill）
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio ~/乔木新知识��/04.素材/AI音乐/代码丛林.mp3 \
    --style newyorker \
    --ratio 9:16
```

### 自定义配图数量

```bash
# 指定生成 6 张配图
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio song.mp3 \
    --scenes 6 \
    --style watercolor
```

### 使用已有素材

```bash
# 跳过转录，使用已有 SRT
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio song.mp3 \
    --skip-transcribe \
    --subtitle existing.srt

# 跳过生图，使用已有图片
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio song.mp3 \
    --skip-images \
    --images-dir ./my_images/
```

## 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 转录效果差 | 音乐人声混合 | 确保使用 `--no-vad` |
| 配图风格不对 | 描述包含风格词 | 检查 visual_config.json |
| 视频比例错误 | 图片比例不匹配 | 确保 `--ratio` 与图片一致 |
| 字幕不同步 | 时间轴不准 | 使用 `--auto-correct` |
| Twitter/X 上传失败 "宽高比太小" | 视频格式不兼容 | 已自动修复（yuv420p + High profile） |

## 字幕位置优化

根据各平台 UI 安全区域研究：

### 9:16 竖屏（TikTok/抖音）
- **底部安全区域**：250px（被 UI 按钮覆盖）
- **字幕位置**：距离底部 280px
- **字体大小**：32px
- **右侧边距**：120px（避开点赞/评论按钮）

### 16:9 横屏（YouTube/B站）
- **底部安全区域**：60px
- **字幕位置**：距离底部 60px
- **字体大小**：28px

## 视频格式兼容性

为确保社交媒体平台兼容，视频自动使用：
- **编码**：H.264 High Profile Level 4.0
- **像素格式**：yuv420p（不是 yuv444p）
- **宽高比**：SAR 1:1 + 正确的 DAR

## 依��安装

```bash
# Whisper
pip install faster-whisper

# FFmpeg (macOS)
brew install ffmpeg

# 图片处理
pip install Pillow
```

## 注意事项

1. **音乐转录**：必须禁用 VAD（`--no-vad`），否则唱歌会被过滤
2. **配图描述**：使用纯视觉语言，不要包含文字
3. **视频比例**：抖音/TikTok 用 9:16，B站/YouTube 用 16:9
4. **生成时间**：完整流程约 5-10 分钟（取决于配图数量）
5. **SRT 版本必须匹配**：Suno 为每个版本生成独立 SRT（`歌名.srt` 对应 `歌名.mp3`，`歌名-1.srt` 对应 `歌名-1.mp3`），两者时间轴不同，混用会导致画面和歌词错位约10秒。使用 `将进酒-1.mp3` 时必须用 `将进酒-1.srt`。
6. **Suno 可能生成重叠时间戳**：部分条目 start 时间相同（如同时演唱），脚本已自动去重，不影响效果。