minimax-music-gen

Name: minimax-music-gen
Author: minimax-ai

github.com/minimax-ai创意与媒体13.7k1.6k 次安装28 周前更新

代码仓库

关于 minimax-music-gen

minimax-music-gen 是通过 mmx 命令行调用 MiniMax Music API，创作人声、纯音乐和翻唱的技能。它提供一句话生成的基础模式，以及可编辑歌词和细化音乐参数的高级流程，并支持播放与迭代。

主要功能

01生成有人声或纯音乐的作品
02根据参考音频制作翻唱
03提供基础和高级创作流程
04调整歌词与结构化音乐参数
05保存、播放并修改生成作品

适用场景

01将简短描述转为歌曲
02按指定风格生成纯音乐
03根据音频和目标风格制作翻唱
04修改歌词或风格后重新生成

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/minimax-ai/skills --skill minimax-music-gen

安装后在 Claude Code 中输入/minimax-music-gen确认已加载。

附带文件references/prompt_guide.md

详细介绍

MiniMax 音乐生成技能

使用 MiniMax Music API 生成歌曲（人声或纯音乐）。支持两种创作模式：基础模式（一句描述即可生成歌曲）和高级控制（编辑歌词、优化提示词、生成前规划）。

前提条件

mmx CLI（必需）：音乐生成需要使用 mmx 命令行工具。

检查是否已安装：
```
command -v mmx && mmx --version || echo "mmx not found"
```
安装（需要 Node.js）：
```
npm install -g mmx-cli
```
进行身份验证（仅首次需要）：
```
mmx auth login --api-key <your-minimax-api-key>
```
API 密钥可从 MiniMax Platform 获取。凭据会保存到 ~/.mmx/credentials.json，并在不同会话间保留。

验证：
```
mmx quota show
```
音频播放器（推荐）：使用 mpv、ffplay 或 afplay（macOS 内置）进行本地播放。mpv 因支持交互式控制而优先推荐。

CLI 工具

此技能使用 mmx CLI 进行所有音乐生成：

音乐生成：mmx music generate — 模型：music-2.6-free
- 支持 --lyrics-optimizer，可根据提示词自动生成歌词
- 支持 --instrumental，用于生成纯音乐曲目
- 支持 --lyrics，用于提供用户自写歌词
- 结构化参数：--genre、--mood、--vocals、--instruments、--bpm、--key、--tempo、--structure、--references
翻唱：mmx music cover — 模型：music-cover-free
- 通过 --audio-file <path> 或 --audio <url> 指定参考音频
- --prompt 用于描述目标翻唱风格

Agent 标志：Agent 调用 mmx 时始终添加 --quiet --non-interactive。

流程：

人声歌曲：用户描述 -> mmx music generate --lyrics-optimizer -> MP3
纯音乐：用户描述 -> mmx music generate --instrumental -> MP3
翻唱：源音频 + 风格 -> mmx music cover -> MP3

存储

所有生成的音乐都会保存到 ~/Music/minimax-gen/。如果该目录不存在，请先创建。文件名由时间戳和根据提示词生成的简短标识组成： YYYYMMDD_HHMMSS_<slug>.mp3

语言与交互

根据用户的第一条消息识别其语言，并在整个会话中使用该语言进行回复。此规则适用于所有交互文本、问题、确认信息和反馈提示。

面向用户的文本本地化规则：

向用户显示的所有文本——包括预览标签、字段名称、确认信息、状态消息、播放信息、反馈提示，以及提示词／描述预览——都必须完整翻译成用户所用的语言。
发送给模型的 API 提示词应始终使用英文，以获得最佳生成质量。不过，向用户预览提示词时，应显示本地化的描述，而非原始英文提示词。英文提示词属于内部实现细节，用户无需查看。
以下模板以英文编写，仅供参考。运行时，请将所有标签和消息翻译成检测到的用户语言。

歌词语言规则：

歌词默认使用用户的语言。使用中文的用户会得到中文歌词；使用英文的用户会得到英文歌词。
只有用户明确提出要求时，才生成其他语言的歌词。
需要使用其他语言的歌词时，应将其自然地融入提示词中的人声或曲风描述。例如，不要直接追加“with Korean lyrics”，而应使用“featuring a Korean female vocalist”，或指定能体现该语言的曲风（如“K-pop”、“J-rock”、“Mandopop”、“Latin pop”）。

工作流

步骤 0：检测意图

解析用户的消息，确定：

歌曲类别：人声（有歌词）、器乐（无人声）或翻唱
创作模式偏好：用户是否提供了详细要求（高级模式），还是随口一句话（基础模式）？

如果不明确，请按照以下决策树提问：

Q1: What type of music?
  - Vocal (with lyrics)
  - Instrumental (no vocals)
  - Cover

Q2: Creation mode?
  - Basic — one-line description, auto-generate
  - Advanced — edit lyrics, refine prompt, plan

如果用户给出了明确的一句话描述，例如“给我写一段悲伤的钢琴曲”，就跳过提问——推断为器乐 + 基础模式并继续。

步骤 1：基础模式

目标：用户提供简短描述，由技能自动生成所有内容，然后调用 API。

扩展描述，生成提示词：将用户的一句话扩展为丰富的音乐提示词。请参考本文末尾的提示词编写指南附录，了解风格词汇、流派／乐器参考和提示词结构。 为了获得最佳生成效果，API 提示词应始终使用英语编写，无论用户使用何种语言。

遵循以下模式：
```
A [mood] [BPM optional] [genre] song, featuring [vocal description],
about [narrative/theme], [atmosphere], [key instruments and production].
```
生成前向用户展示预览。将所有标签和提示词描述翻译成用户的语言。调用 API 时仅在内部使用英文提示词——绝不能让用户看到。示例模板（英文参考——运行时将所有内容本地化）：
```
About to generate:
Type: Vocal / Instrumental
Description: indie folk, melancholy, acoustic guitar, gentle female voice
Lyrics: Auto-generated (--lyrics-optimizer)

Confirm? (press enter to confirm, or tell me what to change)
```
调用 mmx：直接生成音乐。

步骤 2：高级控制模式

目标：用户可在生成前完全控制每个参数。

歌词阶段：
- 如果用户提供了歌词：按段落标记格式化并展示，询问是否需要修改。最终歌词将通过 --lyrics 传递给 mmx。
- 如果用户有主题但没有歌词：使用 --lyrics-optimizer 自动生成歌词。
- 支持迭代编辑：“修改第二段副歌” -> 只重写该段。
- 用户也可以自行创作歌词并通过 --lyrics 传递。
提示词阶段：
- 根据歌词的情绪和内容生成推荐提示词。
- 以可编辑标签的形式呈现，用户可添加／移除／修改。
- 完整词汇表请参考提示词编写指南附录。
高级规划（可选，提供此选项但不要强求）：
- 歌曲结构：主歌-副歌-主歌-副歌-桥段-副歌，或自定义结构
- BPM 建议（在提示词中以速度描述词表示）
- 参考风格：“类似 X 风格” -> 映射为提示词标签
- 人声特征描述
最终确认：展示完整的参数摘要，然后生成。

步骤 3：调用 mmx

使用 mmx CLI 生成音乐：

人声，自动生成歌词：

mmx music generate \
  --prompt "<prompt>" \
  --lyrics-optimizer \
  --genre "<genre>" --mood "<mood>" --vocals "<vocal style>" \
  --instruments "<instruments>" --bpm <bpm> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

人声，使用用户提供的歌词：

mmx music generate \
  --prompt "<prompt>" \
  --lyrics "<lyrics with section markers>" \
  --genre "<genre>" --mood "<mood>" --vocals "<vocal style>" \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

器乐（无人声）：

mmx music generate \
  --prompt "<prompt>" \
  --instrumental \
  --genre "<genre>" --mood "<mood>" --instruments "<instruments>" \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

使用结构化标志（--genre、--mood、--vocals、--instruments、--bpm、--key、 --tempo、--structure、--references、--avoid、--use-case）对 API 进行精细控制，而不要把所有内容都塞进 --prompt。

等待时显示进度指示器。通常需要 30-120 秒才能生成。

步骤 4：播放

生成完成后，检测可用的音频播放器并播放文件。

检测播放器：

command -v mpv || command -v ffplay || command -v afplay

根据检测到的播放器播放（按优先级排序）：

播放器	命令	控制方式
`mpv`（首选）	`mpv --no-video ~/Music/minimax-gen/<filename>.mp3`	空格 = 暂停／继续，q = 退出，左／右 = 搜索
`ffplay`	`ffplay -nodisp -autoexit ~/Music/minimax-gen/<filename>.mp3`	q = 退出
`afplay`（macOS）	`afplay ~/Music/minimax-gen/<filename>.mp3`	Ctrl+C = 停止
未找到	不要尝试播放	仅显示文件路径

开始播放后，告知用户（将所有文本本地化）：

Now playing: <filename>.mp3
Saved to: ~/Music/minimax-gen/<filename>.mp3

不要显示播放控制方式（例如键盘快捷键）——播放器在后台运行，因此这些控制在此环境中不起作用。

如果未找到播放器（将所有文本本地化）：

No audio player detected.
File saved to: ~/Music/minimax-gen/<filename>.mp3
Tip: Install mpv for the best playback experience (brew install mpv).

第 5 步：反馈与迭代

播放后，询问用户的反馈：

How was this song?
  1. Love it, keep it!
  2. Not quite, adjust and regenerate
  3. Fine-tune lyrics/style then regenerate
  4. Don't want it, start over

根据反馈：

满意：完成。再次告知文件路径。
调整并重新生成：询问需要修改什么（提示词？歌词？风格？），应用修改后重新生成。保留旧文件，并添加 _v1 后缀以供比较。
微调：进入高级控制模式，并预填当前参数。
删除并重新开始：删除文件，返回第 0 步。

翻唱模式

基于参考音频生成歌曲的翻唱版本。模型：music-cover-free。

参考音频要求：mp3、wav、flac——时长为 6s 至 6min，最大 50MB。如果未提供歌词，将自动通过 ASR 提取原歌词。

工作流

用户选择翻唱模式时：

询问源音频——本地文件路径或 URL
询问目标翻唱风格（例如，“原声翻唱、简约编曲、亲密感人声”）
可选：询问自定义歌词或歌词文件

命令

翻唱本地文件：

mmx music cover \
  --prompt "<cover style description>" \
  --audio-file <source.mp3> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

翻唱 URL：

mmx music cover \
  --prompt "<cover style description>" \
  --audio <source_url> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

使用自定义歌词（文本）：

mmx music cover \
  --prompt "<style>" \
  --audio-file <source.mp3> \
  --lyrics "<custom lyrics>" \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

使用自定义歌词（文件）：

mmx music cover \
  --prompt "<style>" \
  --audio-file <source.mp3> \
  --lyrics-file <lyrics.txt> \
  --out ~/Music/minimax-gen/<filename>.mp3 \
  --quiet --non-interactive

可选标志

标志	说明
`--seed <number>`	用于获得可复现结果的随机种子，取值范围为 0-1000000
`--channel <n>`	`1`（单声道）或 `2`（立体声，默认）
`--format <fmt>`	`mp3`（默认）、`wav`、`pcm`
`--sample-rate <hz>`	采样率（默认：44100）
`--bitrate <bps>`	比特率（默认：256000）

生成后

按常规播放和反馈流程继续（第 4 步和第 5 步）。

错误处理

错误	操作
未找到 mmx	`npm install -g mmx-cli`
mmx 身份验证错误（退出代码 3）	`mmx auth login`
超出配额（退出代码 4）	告知配额限制，建议等待或升级
API 超时（退出代码 5）	重试一次，然后报告失败
内容过滤器（退出代码 10）	调整提示词以避免触发内容过滤
歌词格式无效	自动修复段落标记，并提醒用户
未找到音频播放器	保存文件并告知用户路径，建议安装 mpv
网络错误	显示错误详情，建议检查连接

重要说明

切勿复现受版权保护的歌词。 翻唱时，始终创作受歌曲主题启发的原创歌词。向用户说明这一点。
提示词语言：API 提示词使用英文标签效果最佳。也可以使用中文标签。混合使用也没问题。
歌词中的段落标记：API 可识别 [verse]、[chorus]、[bridge]、 [outro]、[intro]。提供 --lyrics 时务必包含这些标记。
文件管理：如果 ~/Music/minimax-gen/ 中的文件超过 50 个，在开始新会话时建议清理。
结构化参数：优先使用 --genre、--mood、--vocals、--instruments、 --bpm 等参数，而不是把所有内容都写进 --prompt。这样 API 能更好地控制生成效果。
通过风格指定歌词语言：用户希望歌词使用特定语言时，应通过人声描述或流派来表达（例如，“Japanese female vocalist”、“Mandopop ballad”），而不是在提示词后追加语言指令。

附录：提示词撰写指南

完整的提示词撰写指南（包括流派、人声、乐器参考和 BPM 表）请参阅 references/prompt_guide.md。

支持 Markdown

登录后评论

基本信息

作者: minimax-ai
仓库: minimax-ai/skills
分类: 创意与媒体
安装次数: 1,608
GitHub Stars: 13,735

报告问题