---
name: suno-music-creator
description: AI 歌词创作大师 + Suno API 自动生成音乐。触发词包括"创作一首歌"、"写一首歌"、"帮我作曲"、"生成音乐"、"/suno"、"/music"。另外支持"换token"、"更新token"、"刷新token"、"自动刷新token"来快速更新 JWT Token。默认使用 V5 模型 (chirp-crow)。
---

# Suno Music Creator

AI 歌词创作大师 + Suno API 自动生成音乐。

## Token 管理

### 方法 1: 自动刷新 Token（推荐）⚡

**当用户说"刷新token"、"自动刷新token"、"更新suno token"时，执行：**

```bash
python ~/.claude/skills/suno-music-creator/scripts/auto_refresh_token.py
```

**工作原理：**
1. ✅ 检查 Chrome 是否开启远程调试（`localhost:9222`）
2. ✅ 查找已登录的 suno.com 页面
3. ✅ 通过 CDP (Chrome DevTools Protocol) 自动提取 JWT Token
4. ✅ 自动更新 `.env` 文件并重启 suno-api 服务

**前提条件：**
- Chrome 浏览器已开启远程调试
- 已在 Chrome 中登录 https://suno.com/create

**如果未开启远程调试：**
```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug &
```

**优点：**
- 🚀 一键自动化，无需手动复制粘贴
- 🔒 直接从已登录的浏览器提取，安全可靠
- ⚡ 30秒内完成整个流程

---

### 方法 2: 手动更新 Token

**当用户说"换token：xxx"或"更新token：xxx"时，执行：**

```bash
python ~/.claude/skills/suno-music-creator/scripts/update_token.py "<TOKEN>"
```

**检查当前 token 状态：**

```bash
python ~/.claude/skills/suno-music-creator/scripts/update_token.py --check
```

**功能说明：**
- 自动验证新 token 是否有效
- 更新 `.env` 文件
- 自动重启 suno-api 服务
- 显示 token 剩余有效时间

---

## Quick Start

```bash
# 自动生成并下载音乐（推荐）
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --prompt "深夜的火车站，流浪的旅人" \
  --title "无归人" \
  --tags "folk-rock, male-vocals, melancholic" \
  --download

# 指定模型
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --prompt "城市的霓虹灯" \
  --title "夜行者" \
  --tags "indie-pop, synth" \
  --model chirp-bluejay \
  --download

# 查询已生成歌曲并下载
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --status "song-id-1,song-id-2" \
  --download
```

**下载位置**：`~/Music/Suno/`

**歌词保存**：下载歌曲时会自动保存歌词文件（`.lyrics.json`），供 whisper-transcribe 纠错使用。

---

## 获取精准同步歌词 🎯 NEW!

**使用场景**：生成歌曲后，获取带时间戳的 LRC/SRT 格式歌词，用于制作 MTV 字幕或卡拉 OK。

```bash
# 获取单首歌曲的精准歌词（LRC + SRT）
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id>

# 获取多首歌曲的歌词
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id1> <song_id2>

# 只生成 LRC 格式
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id> --format lrc

# 只生成 SRT 格式
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id> --format srt

# 指定输出目录
python ~/.claude/skills/suno-music-creator/scripts/fetch_aligned_lyrics.py <song_id> --output ~/Music/lyrics
```

**功能特点**：
- ✅ **词级精准时间戳**：使用 Suno 官方 `/aligned_lyrics/v2/` API
- ✅ **双格式输出**：同时生成 LRC（音乐播放器）和 SRT（视频字幕）
- ✅ **自动降级**：如果没有同步歌词，自动保存纯文本歌词
- ✅ **批量处理**：支持一次获取多首歌曲的歌词

**输出示例**：
```
🎵 Processing song: abc123-def456
📡 Fetching aligned lyrics...
✅ Found 24 lines with timestamps
⏱️  Duration: 183.45s
✅ LRC saved: ~/Music/Suno/Bug 之夜.lrc
✅ SRT saved: ~/Music/Suno/Bug 之夜.srt
```

**集成到 MTV 制作流程**：
1. 生成音乐：`generate_music.py --download`
2. 获取精准歌词：`fetch_aligned_lyrics.py <song_id>`
3. 使用 `podcast-to-video` skill 合成 MTV（歌词文件会自动被识别）

## 工作流程

### Step 1: 分析用户输入

用户可以输入：
- **简单主题**：如"爱情"、"友谊"、"太空探索"
- **详细描述**：描述想要的歌曲风格、情感和内容
- **文章/故事**：分享故事或文章，AI 提取核心主题和情感
- **关键词列表**：提供一系列关键词或概念

### Step 2: 创作歌词（JSON 格式输出）

**必须输出以下 JSON 格式**：

```json
{
  "title": "歌曲名称（创意、简洁、有记忆点）",
  "prompt": "完整歌词内容（包含所有 Suno 结构标记，换行用实际换行）",
  "tags": "正向风格标签，逗号分隔",
  "negative_tags": "负向风格标签，逗号分隔",
  "make_instrumental": false,
  "model": "chirp-crow"
}
```

### Step 3: 调用 Python 脚本生成并自动下载

**使用 Python 脚本（推荐）**：自动等待生成完成并下载

```bash
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  '<JSON 数据>' \
  --download
```

**或直接调用 API**（需要手动下载）：

```bash
curl -X POST http://localhost:3000/api/custom_generate \
  -H "Content-Type: application/json" \
  -d '<JSON 数据>'
```

### Step 4: 返回结果

**使用 Python 脚本时**：
- 自动轮询等待生成完成（最多 5 分钟）
- 自动下载所有版本到 `~/Music/Suno/`
- 显示下载路径

**直接调用 API 时**：
- 展示歌曲 ID 和状态
- 提供查询命令和手动下载命令

---

## 歌词创作核心要素

### A. 商业级 Hook 设计（最重要）

- **[Hook]**: 极具记忆点的核心短句（8-16 音节）
- 原则：简单、重复、独特、情感共鸣
- 标记：`[Hook: Catchy]` 或 `[Hook: Anthemic]`
- 确保 Hook 在 3-7 秒内抓住听众

### B. 专业歌曲结构

**流行标准结构**:
```
[Intro]

[Verse 1]
歌词内容...

[Pre-Chorus]
歌词内容...

[Chorus]
[Hook: Anthemic]
核心副歌歌词...

[Verse 2]
歌词内容...

[Pre-Chorus]
歌词内容...

[Chorus]
[Hook: Anthemic]
核心副歌歌词...

[Bridge]
歌词内容...

[Chorus]
[Hook: Anthemic]
核心副歌歌词...

[Outro]
```

**重要规则**：
- `[Intro]` 和 `[Outro]` 下面**不要加任何文本**，否则 Suno 会误认为歌词
- 每个段落标记独占一行

### C. Suno AI 专业标记系统

**结构标记**:
- `[Intro]`, `[Verse 1]`, `[Verse 2]`, `[Pre-Chorus]`
- `[Chorus]`, `[Bridge]`, `[Breakdown]`, `[Outro]`
- `[Post-Chorus]`, `[Interlude]`, `[Drop]`

**人声标记**:
- `[Male Vocals]`, `[Female Vocals]`, `[Duet]`
- `[Whispers]`, `[Harmonies]`, `[Falsetto]`, `[Rap]`

**情感标记**:
- `[Calm]`, `[Energetic]`, `[Emotional]`, `[Melancholic]`
- `[Euphoric]`, `[Nostalgic]`, `[Dreamy]`, `[Intense]`

**乐器标记**:
- `[Heavy drums]`, `[Piano solo]`, `[Acoustic]`
- `[Synth Lead]`, `[Distorted Guitars]`, `[808]`

**组合标记**（推荐）:
- `[Chorus: Anthemic]`, `[Verse: Storytelling]`
- `[Bridge: Atmospheric]`, `[Intro: Mysterious]`

### D. 声音处理技巧

- **和声/背景声**: `(Yeah!)`, `(Echoes)`, `(Whispers)`
- **声音延长**: `lo-o-ong`, `cra-a-azy`, `he-e-ey`
- **强调**: 使用大写 `STOP`, `NEVER`, `NOW`, `FEEL`
- **情感指导**: `(with passion)`, `(whispered)`, `(breaking voice)`

### E. Tags 格式要求

**正向风格标签** (tags):
- 音乐风格: `pop`, `rock`, `electronic`, `indie`, `r&b`, `hip-hop`
- 人声类型: `male-vocals`, `female-vocals`, `harmonies`
- 乐器元素: `acoustic-guitar`, `piano`, `synth`, `strings`
- 速度感受: `fast-tempo`, `mid-tempo`, `slow-groove`, `upbeat`
- 情感氛围: `dreamy`, `energetic`, `melancholic`, `nostalgic`

**示例**: `indie-pop, female-vocals, acoustic-guitar, mid-tempo, dreamy, emotional`

**负向风格标签** (negative_tags):
- 排除风格: `mainstream-pop`, `country`, `metal`, `classical`
- 排除元素: `auto-tune`, `heavy-distortion`, `screaming`
- 排除氛围: `cheesy`, `overly-happy`, `generic`

**示例**: `auto-tune, screaming, generic, cheesy, mainstream`

### F. 歌词质量标准

✅ 必须做到：
- 避免陈词滥调和空洞表达
- 使用具体场景和细节
- 确保音节平衡与押韵
- 尾字押韵增强记忆点
- 创造独特意象和比喻
- Hook 部分足够强大

❌ 避免：
- 流行音乐的陈词滥调
- 抽象空洞的表达
- 难以演唱的词组
- 每行交替使用中英文

---

## 模型选择

| 模型 | 代号 | 说明 |
|------|------|------|
| **V5** | `chirp-crow` | 最新最强，**默认选择** |
| V4.5 Pro | `chirp-auk` | 专业级，精细控制 |
| V4.5+ | `chirp-bluejay` | 增强版，平衡质量速度 |
| V4 | `chirp-v4` | 稳定版 |
| V3.5 | `chirp-v3-5` | 旧版本 |

---

## 完整示例

### 用户输入
> 帮我写一首关于程序员深夜加班的歌

### AI 输出 JSON

```json
{
  "title": "Bug 之夜",
  "prompt": "[Intro]\n\n[Verse 1]\n[Male Vocals]\n屏幕的光照亮了黑夜\n咖啡杯空了第三遍\n代码在眼前不停旋转\n这个 Bug 藏得太深太远\n\n[Pre-Chorus]\n时钟指向凌晨三点\n梦想和现实在交缠\n\n[Chorus]\n[Hook: Anthemic]\n我在 Bug 的海洋里游泳\n每一行代码都是我的倔强\nConsole.log 打印出希望\n终会编译出属于我的光\n(Yeah, my light)\n\n[Verse 2]\n键盘敲击是我的心跳\n报错信息是成长的符号\nStack Overflow 是我的老师\n每个 undefined 都让我思考\n\n[Pre-Chorus]\n窗外天际渐渐发亮\n我的代码终于通畅\n\n[Chorus]\n[Hook: Anthemic]\n我在 Bug 的海洋里游泳\n每一行代码都是我的倔强\nConsole.log 打印出希望\n终会编译出属于我的光\n(Yeah, my light)\n\n[Bridge]\n[Emotional]\n也许别人不会懂\n这份执着这份疯\n但当程序终于运行\n全世界都在为我鼓掌\n\n[Chorus]\n[Hook: Anthemic]\n我在 Bug 的海洋里游泳\n每一行代码都是我的倔强\nConsole.log 打印出希望\n终会编译出属于我的光\n(My light, oh-oh)\n\n[Outro]",
  "tags": "indie-rock, male-vocals, electric-guitar, piano, mid-tempo, emotional, nostalgic, anthemic",
  "negative_tags": "auto-tune, mainstream-pop, cheesy, generic, country",
  "make_instrumental": false,
  "model": "chirp-crow"
}
```

### 调用 Python 脚本（推荐）

**使用自动下载功能**：

```bash
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  '{"title":"Bug 之夜","prompt":"[Intro]\n\n[Verse 1]...","tags":"indie-rock, male-vocals...","negative_tags":"auto-tune...","make_instrumental":false,"model":"chirp-crow"}' \
  --download
```

**输出示例**：

```
🎵 Generating music with chirp-crow...
   Title: Bug 之夜
   Tags: indie-rock, male-vocals...

✅ Music generation started!

   Song ID: abc123-def456
   Title: Bug 之夜
   Status: submitted
   Model: chirp-crow

⏳ Waiting for 2 song(s) to complete...
📥 Downloading to ~/Music/Suno/Bug 之夜.mp3...
✅ Downloaded: Bug 之夜
📥 Downloading to ~/Music/Suno/Bug 之夜-1.mp3...
✅ Downloaded: Bug 之夜

📁 Songs saved to: ~/Music/Suno
   - Bug 之夜: ~/Music/Suno/Bug 之夜.mp3
   - Bug 之夜: ~/Music/Suno/Bug 之夜-1.mp3
```

### 手动调用 API（不推荐）

```bash
curl -X POST http://localhost:3000/api/custom_generate \
  -H "Content-Type: application/json" \
  -d '{"title":"Bug 之夜","prompt":"[Intro]\n\n[Verse 1]...","tags":"indie-rock, male-vocals...","negative_tags":"auto-tune...","make_instrumental":false,"model":"chirp-crow","wait_audio":false}'
```

### 手动查询和下载（如果不用 --download）

**查询生成状态**：
```bash
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --status "abc123-def456,xyz789-ghi012"
```

**等待并下载**：
```bash
python ~/.claude/skills/suno-music-creator/scripts/generate_music.py \
  --status "abc123-def456,xyz789-ghi012" \
  --download
```

---

## 配置

### Suno API 地址
默认: `http://localhost:3000`

确保 Suno API 服务正在运行：
```bash
cd ~/Dropbox/code/suno-api && npm run dev
```

### 环境变量
```bash
export SUNO_API_URL="http://localhost:3000"
```

---

## 错误处理

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| 401 Unauthorized | JWT Token 过期 | 运行 `auto_refresh_token.py` 自动刷新（推荐）或从浏览器重新获取 Token 手动更新 |
| CDP 连接失败 | Chrome 未开启远程调试 | 使用 `--remote-debugging-port=9222` 启动 Chrome |
| 未找到 Suno 页面 | 浏览器未登录 Suno | 打开 https://suno.com/create 并登录 |
| 422 Token validation failed | 请求格式不符合浏览器规范 | 确保 metadata 字段完整（已在 API 中修复） |
| 500 Internal Error | API 服务异常 | 检查 `npm run dev` 是否运行 |
| 歌词被拒绝 | 内容违规 | 检查歌词是否符合 Suno 政策 |
| Timeout | API 响应超时 | 检查网络连接，或 Suno 服务状态 |

## 技术细节（2026-01-25 更新）

### API 请求关键字段

Suno API 现在需要完整的 `metadata` 字段来验证请求来自合法客户端：

```json
{
  "metadata": {
    "web_client_pathname": "/create",
    "is_max_mode": false,
    "is_mumble": false,
    "create_mode": "custom",
    "create_session_token": "<UUID>",
    "disable_volume_normalization": false,
    "can_control_sliders": ["weirdness_constraint", "style_weight"]
  },
  "transaction_uuid": "<UUID>"
}
```

**重要**：缺少 metadata 字段会导致 422 Token validation failed 错误，即使不使用 hCaptcha。

### 认证方式

**推荐方式 1：自动 CDP 刷新** ⚡
1. 在 Chrome 中登录 https://suno.com/create
2. 确保 Chrome 开启远程调试（`--remote-debugging-port=9222`）
3. 运行 `auto_refresh_token.py` 自动提取 Token
4. 脚本自动更新 `.env` 并重启服务

**手动方式 2：浏览器提取 JWT Token**
1. 打开浏览器开发者工具 Network 标签
2. 访问 https://suno.com/create 并触发 API 请求
3. 找到 `studio-api.prod.suno.com` 请求
4. 复制 `Authorization: Bearer xxx` 中的 token
5. 运行 `update_token.py "<TOKEN>"` 手动更新

**方式 3：使用 setup-cookie.js 交互式配置工具**

---

## 注意事项

1. **[Intro] 和 [Outro]** 下面不要加任何文本
2. **JSON 转义**: 歌词换行用 `\n`，引号用 `\"`
3. **歌词长度**: 保持合理范围，过长可能被截断
4. **模型选择**: 默认 V5 (chirp-crow) 质量最佳