初始发布: 21 个 skills (Claude Code / Codex / DSH)

2026-08-14 01:51:44 +08:00
commit ea0857bedb
129 changed files with 35566 additions and 0 deletions
@@ -0,0 +1,146 @@
+---
+name: minimax-music
+description: 调用 MiniMax music-3.0 生成音乐（带唱歌曲/纯音乐/自动作词/翻唱），并可裁成定长无缝循环 BGM。触发关键词：「生成音乐」「做首歌」「写首歌」「AI 作曲」「生成 BGM」「背景音乐」「配乐」「纯音乐」「器乐」「MiniMax 音乐」「music-3.0」「翻唱」「循环 BGM」「游戏配乐」「短片配乐」。适用场景：游戏/短片/播客的背景音乐、Demo 小样、根据歌词谱曲、按参考音频翻唱。
+version: 1.0.0
+author: william
+---
+
+# MiniMax 音乐生成 Skill
+
+调用 MiniMax **music-3.0** 生成音乐并下载到本地；需要定长循环 BGM 时再用 `loopify.py` 做后期。
+
+## 触发判断
+
+用户说"生成一段音乐/BGM/配乐"、"做首歌"、"写首纯音乐"、"给这个视频配个乐"、"游戏循环 BGM"等 → 按下方流程执行。
+
+## 两个脚本
+
+| 脚本 | 作用 | 依赖 |
+|------|------|------|
+| `generate.py` | 调 API 生成音乐 | Python 3 标准库 |
+| `loopify.py` | 裁成定长无缝循环 + 客观验收 | ffmpeg + numpy |
+
+## API Key
+
+优先读环境变量 `MINIMAX_API_KEY`，否则读 `~/.claude/skills/minimax-music/key.txt`（权限 600）。切换用 `export MINIMAX_API_KEY=<新key>`。
+
+⚠️ **区域必须匹配**：国内 key 配 `api.minimaxi.com`（脚本内置），海外 key 要改成 `api.minimax.io`，否则报鉴权失败。
+
+## 计费
+
+| 模型 | 价格 | RPM |
+|------|------|-----|
+| `music-3.0` / `music-2.6` / `music-cover` | **¥1.0 / 首** | 120 |
+| `music-3.0-free` / `music-2.6-free` / `music-cover-free` | **免费** | 3 |
+
+**按"首"计费，不按秒。** 试风格、调 prompt 一律先用 `--free`（免费且不限次数，只限速率），定稿再跑付费模型。
+
+## 四种模式
+
+```bash
+S=~/.claude/skills/minimax-music
+
+# 1. 带唱：lyrics 必填，prompt 可选
+python3 $S/generate.py "独立民谣，忧郁内省，木吉他分解和弦+弦乐铺底" -l @lyrics.txt -o song.mp3
+
+# 2. 纯音乐：反过来，prompt 必填，lyrics 可省
+python3 $S/generate.py "中世纪奇幻大地图探索，鲁特琴+竖琴+木笛，中慢速，无鼓" --instrumental -o bgm.mp3
+
+# 3. 自动作词：不用自己写词
+python3 $S/generate.py "抒情流行，夏夜告别，遗憾但释然" --auto-lyrics -o auto.mp3
+
+# 4. 翻唱：参考音频 6s-6min、<=50MB
+python3 $S/generate.py "" --cover ref.mp3 -l "[Verse]\n新歌词..." -o cover.mp3
+
+# 免费试跑（任何模式加 --free）
+python3 $S/generate.py "..." --instrumental --free -o test.mp3
+```
+
+### 常用参数
+
+| 参数 | 说明 | 默认 |
+|------|------|------|
+| `prompt`（位置） | 曲风/情绪/场景，≤2000 字 | 纯音乐时必填 |
+| `-l, --lyrics` | 歌词 ≤3500 字，`\n` 分行，支持 `@文件` | 带唱时必填 |
+| `--instrumental` | 纯音乐 | 否 |
+| `--auto-lyrics` | 模型自动作词 | 否 |
+| `--cover` | 翻唱参考音频（路径或 URL）| — |
+| `-m, --model` | 模型 | `music-3.0` |
+| `--free` | 换成对应免费模型 | 否 |
+| `-o, --output` | 输出路径 | 时间戳命名 |
+| `--sample-rate` / `--bitrate` / `--format` | 16000/24000/32000/**44100**、32000/64000/128000/**256000**、**mp3**/wav/pcm | 见粗体 |
+| `--hex` | 用 hex 返回而非 url | 否 |
+
+## 歌词格式
+
+用 `[Intro]` `[Verse]` `[Chorus]` `[Bridge]` `[Outro]` 分段，段间空行：
+
+```
+[Verse]
+雨把街灯揉成一片橙黄
+玻璃门后面有人在张望
+
+[Chorus]
+你转身的那一秒
+雨就轻了一点点
+```
+
+## 定长无缝循环 BGM
+
+**接口没有 duration 参数**，时长完全不可控（实测：带唱 61s、纯音乐 97-126s，纯音乐普遍更长因为没有歌词框住它）。游戏/短片要定长循环，必须后期处理：
+
+```bash
+python3 $S/loopify.py raw.mp3 -o bgm_loop.mp3 -L 45 --preview 3
+```
+
+它做四件事：
+
+1. **测实际速度，把循环长度对齐到整数小节**。只对齐电平不对齐节奏的话，循环起来会丢拍——这是最容易翻车的地方。`-L 45 --tol 1.0` 表示在 44-46s 里找整小节长度。
+2. **扫描起点**，比较首尾 2 秒的 RMS + 频谱质心 + 低频占比，选最接近的窗口，并避开渐入、渐出、能量凹陷。
+3. **qsin 等功率曲线做尾→头交叉淡化**（默认 2.0s），并自动把峰值压到 `--peak`（默认 -1.0 dBFS）留余量。
+4. **客观验收**：峰值削波、异常静音、接缝逐样本跳变 vs 曲内 99.9 分位跳变、接缝前后 RMS 差、立体声宽度。
+
+`--preview 3` 会额外导出连播三遍的文件——**循环 BGM 一定要循环着听至少 3 分钟**，单听一遍听不出接缝和"听腻"的问题。
+
+## 写 prompt 的要点
+
+**先想清楚这段音乐会不会被循环播放，两种写法是相反的：**
+
+| | 一次性配乐（短片/过场）| 循环 BGM（游戏/等待画面）|
+|---|---|---|
+| 情绪 | 写**情绪曲线**："开头克制，中段弦乐推起，结尾回落渐弱" | 写**稳定**："全曲同调性、同速度、同织体密度，平稳流动" |
+| 结构 | 可以有前奏尾奏 | **明确不要前奏尾奏、不要渐强、不要淡出结尾** |
+| 旋律 | 可以抓耳 | **克制、留白多、听十分钟不腻** |
+
+其余通用要点：
+
+- **写死速度和拍号**："中慢速约 80 BPM，6/8 摇曳律动，自然小调"
+- **逐件点名配器**："鲁特琴分解和弦作骨架，竖琴琶音点缀，木笛吹主旋律，柔和弦乐铺底"
+- **一定要写否定项**。不写它很容易自己加鼓、加合成器、加人声，配画面就吵了：
+  "严格不要：人声、歌词、吟唱、现代流行元素、电子合成器、重鼓组、密集打击乐"
+- 中英混写没问题；有必须命中的风格关键词就直接用英文写进去（`medieval fantasy, orchestral, instrumental, loopable, game soundtrack`）
+
+## 工作流
+
+1. 明确用途（配画面？循环 BGM？独立歌曲？）和时长要求
+2. 按上表写 prompt，**先用 `--free` 试 1-2 版**确认方向
+3. 方向对了跑付费 `music-3.0` 定稿（¥1）
+4. 要定长循环就接 `loopify.py`，看验收输出是否全项通过
+5. 把成品路径告诉用户；循环 BGM 一并给 `--preview` 的试听文件
+
+## 坑
+
+1. **HTTP 200 不代表成功**。一律看 `base_resp.status_code`：`0` 成功、`1002` 限流、`1004` 鉴权失败、`1008` 余额不足、`1026` 敏感内容、`2013` 参数错。脚本已处理并翻译成人话。
+2. **`output_format` 接口默认是 `hex`**（一大串十六进制塞在 JSON 里）。脚本默认改成了 `url` 并自动下载，两种都兼容。**url 链接 24 小时过期**，别只存链接。
+3. **`extra_info` 里没有计费字段**（不像视频接口有 `usage`），没法从响应对账，只能自己按"首"数。
+4. **必填是条件性的**：纯音乐要 prompt、带唱要 lyrics，反了会 2013。脚本在发请求前就本地拦截，不会白花钱。
+5. **翻唱三个参数互斥**：`audio_url` / `audio_base64` / `cover_feature_id` 只能给一个；`cover_feature_id` 24 小时过期。
+6. **两份官方文档的歌词长度打架**：API 参考写 1-3500 字，指南写 10-1000 字。后者只适用于带 `cover_feature_id` 的翻唱。
+7. **free 模型限 RPM 3**，串行调用够用，别并发。
+8. **输出电平不稳定**：实测同样参数，有的曲子峰值 -2.3 dBFS，有的直接 0.0 dBFS 顶格。顶格素材做交叉淡化时两路叠加必然削波，`loopify.py` 已自动衰减留余量；如果你自己用 ffmpeg 拼接，记得先量峰值。
+
+## 参考
+
+- [音乐生成 API](https://platform.minimaxi.com/docs/api-reference/music-generation)
+- [音乐生成指南](https://platform.minimaxi.com/docs/guides/music-generation)
+- [按量付费定价](https://platform.minimaxi.com/docs/guides/pricing-paygo)