mimo-tts

MiMo-V2.5-TTS 语音合成

通过 OpenAI 兼容 API（/v1/chat/completions）调用语音合成模型。

执行规则

直接运行用户请求的命令，不要预先检查依赖项、环境变量或配置。如果出现问题，脚本会报出明确错误；只有在此时才检查并修复。

要求

• 必须设置环境变量 MIMO_APIKEY
• 流式输出：pip install numpy soundfile

API 基础信息

• 基础 URL：https://api.xiaomimimo.com/v1
• 身份验证：HTTP Header api-key
• 端点：/v1/chat/completions（OpenAI 兼容）
• 模型与功能对应关系：

模型	功能	歌唱	声音设计	声音克隆
mimo-v2.5-tts	预设声音合成	✅	❌	❌
mimo-v2.5-tts-voicedesign	文本转声音设计	❌	✅	❌
mimo-v2.5-tts-voiceclone	声音克隆	❌	❌	✅

⚠️ 文本输入：使用文件重定向

所有文本内容（合成文本、声音描述、风格提示词）都必须先写入 txt 文件，再通过 $(cat) 传入。

# Write text to file first
echo "Text to synthesize" > tts_text.txt
python scripts/tts.py synthesize "$(cat tts_text.txt)" --voice Bingtang

---

风格控制指南

MiMo-V2.5-TTS 提供两种互补的风格控制方法，可同时使用。

1. 自然语言控制（推荐）

在 user message 中加入风格描述，用一句话描述所需风格。

简单示例

Speak in a bright, uplifting tone as if reporting good news to a boss, slightly fast pace, with excitement and pride that can't be contained, voice bright and energetic.

Use a bright, lively teenage voice with the smugness of a successful prank, fast pace with light articulation.

导演模式（高级）

像指导演员一样撰写，涵盖角色、场景和指导方式。

[Character] The current head of a century-old distinguished family. Has lived in seclusion for years, with a strong sense of class alienation from others.
[Scene] In the shadow of the ancestral hall, watching the man who broke through security to find her.
[Direction] Cold, languid yet commanding low alto. Extremely slow speech, each word as if rolled on the tongue before release. Long silences between sentences. Heavy, solid voice with slight breathiness at tail ends.

用法

# Natural language style → --user-prompt parameter
python scripts/tts.py synthesize "$(cat text.txt)" --voice Bingtang --user-prompt "$(cat style.txt)"

2. 音频标签控制（精细控制）

标签直接放在 assistant content（合成文本）中。

风格标签（位于文本开头）

在文本开头添加 (style) 以设置整体风格。

格式：(style1 style2)text to synthesize

类型	选项
基本情绪	开心/悲伤/愤怒/恐惧/惊讶/兴奋/委屈/平静/冷漠
复合情绪	怅然/欣慰/无奈/愧疚/释然/嫉妒/厌倦/忐忑/动情
整体语气	温柔/高冷/活泼/严肃/慵懒/俏皮/深沉/干练/凌厉
声音特质	磁性/醇厚/清亮/空灵/稚嫩/苍老/甜美/沙哑/醇雅
人设	夹子音/御姐音/正太音/大叔音/台湾腔
方言	东北话/四川话/河南话/粤语
角色扮演	孙悟空/林黛玉
歌唱	唱歌/sing/singing（必须放在最开头）

示例：

(怅然)这么多年过去了，再走过那条街，心里一下子空了一块。
(慵懒)再让我睡五分钟……就五分钟，真的。
(磁性)夜已经深了，我是今晚陪你的人，欢迎收听《午夜电台》。
(东北话)哎呀妈呀，这天儿也忒冷了吧！
(粤语)呢个真係好正啊！食过一次就唔会忘记！
(singing)原谅我这一生不羁放纵爱自由

音频标签（可插入文本任意位置）

在文本中插入 [tag] 进行精细控制。

类型	选项
节奏与韵律	吸气/深呼吸/叹气/长叹一口气/喘息/屏息
情绪状态	紧张/害怕/激动/疲惫/委屈/撒娇/心虚/震惊/不耐烦
声音特征	颤抖/声音颤抖/变调/破音/鼻音/气声/沙哑
笑声与哭声	笑/轻笑/大笑/冷笑/抽泣/呜咽/哽咽/嚎啕大哭

示例：

（紧张，深呼吸）呼……冷静，冷静。不就是一个面试吗……（语速加快）自我介绍已经背了五十遍了。
（极其疲惫，有气无力）师傅……到地方了叫我一声……（长叹一口气）我先眯一会儿。
（提高音量喊话）大姐！这鱼新鲜着呢！早上刚捞上来的！

---

声音设计指南

如何撰写出色的声音描述

使用 mimo-v2.5-tts-voicedesign 时，user message 中的文本就是声音设计描述。描述越生动、具体，效果越好。

关键维度

维度	示例
性别与年龄	"二十多岁的年轻女性"、"五十多岁的中年男性"
音色／质感	"低沉沙哑"、"丝滑醇厚、带着磁性"
情绪／语气	"温暖而自信"、"温柔但带着一丝疲惫"
语速／节奏	"缓慢而从容"、"语速极快，像连珠炮"

其他丰富描述的维度

• 角色／人设：叙述者、播客主持人、评书先生、深夜电台 DJ
• 说话风格：随意口语化、一本正经、压低嗓音像在密谋
• 场景描述：讲述自然纪录片、在给投资人路演
• 时代参考：1940 年代黑色电影、八十年代译制片配音

撰写风格

简洁描述：

Heavy Russian accent, gruff middle-aged male, blunt and matter-of-fact.

专业描述：

一位年迈的老先生，说带北方口音的普通话，语速缓慢而沉稳，嗓音略带沙哑和沧桑感，仿佛一位饱经风霜的老爷爷在讲故事，充满岁月的智慧。

注意事项

1. 长度：1-4 句话——核心特征比面面俱到更重要
2. 避免冲突：不要提出互相矛盾的特征（例如“童声 + CEO 气场”）
3. 避免 DSP 术语：不要提及混响、回声、EQ、压缩等
4. 避免模糊词语：不要使用“正常”“普通”等词语
5. 中文或英文：选择最能准确表达想法的语言
6. 文本与声音相匹配：assistant 中的合成文本应与声音描述相符

---

命令与用法

1. 预设语音合成（synthesize）

python scripts/tts.py synthesize "$(cat text.txt)" --voice <voice_id> [--output <path>]

使用自然语言控制风格：

python scripts/tts.py synthesize "$(cat text.txt)" --voice Bingtang --user-prompt "$(cat style.txt)"

使用音频标签控制（直接在 text.txt 中添加标签）：

# text.txt content: (温柔)夜已经深了，欢迎收听我的节目。
python scripts/tts.py synthesize "$(cat text.txt)" --voice Bingtang

歌唱模式（需要 mimo-v2.5-tts 模型）：

# text.txt content: (singing)原谅我这一生不羁放纵爱自由
python scripts/tts.py synthesize "$(cat text.txt)" --voice Bingtang

2. 根据文本设计语音（design）

python scripts/tts.py design "$(cat voice_desc.txt)" --text "$(cat speech.txt)"

不使用 --text 时，会自动生成匹配的文本：

python scripts/tts.py design "$(cat voice_desc.txt)"

3. 语音克隆（clone）

python scripts/tts.py clone <sample.wav> "$(cat text.txt)"

使用风格控制：

python scripts/tts.py clone <sample.wav> "$(cat text.txt)" --user-prompt "$(cat style.txt)"

4. 流式输出

在任意合成命令中添加 --stream。流式输出需要使用 --format pcm16：

python scripts/tts.py synthesize "$(cat text.txt)" --voice Bingtang --stream --format pcm16
python scripts/tts.py design "$(cat voice_desc.txt)" --text "$(cat speech.txt)" --stream --format pcm16
python scripts/tts.py clone sample.wav "$(cat text.txt)" --stream --format pcm16

5. 列出可用语音

# Default JSON output
python scripts/tts.py voices

# Plain text output
python scripts/tts.py voices --format text

# Also available via the "tts" alias:
python scripts/tts.py tts "$(cat text.txt)" --voice Bingtang

预设语音列表

Voice ID	名称	语言	性别
mimo_default	MiMo-Default	自动（zh-CN=Bingtang，否则=Mia）	—
冰糖	Bingtang	中文	女性
茉莉	Moli	中文	女性
苏打	Soda	中文	男性
白桦	Birch	中文	男性
Mia	Mia	英语	女性
Chloe	Chloe	英语	女性
Milo	Milo	英语	男性
Dean	Dean	英语	男性

输出

• 音频默认保存到 ~/.wmyskills/mimo-tts/outputs/（使用 --output / -o 指定自定义路径或目录）
• 非流式：JSON {"status":"ok","path":"...","size_bytes":N}
• 流式：JSON {"status":"ok","path":"...","samples":N}（使用 samples 而非 size_bytes）
• 错误：JSON {"error": true, "status": 4XX, "message": "..."}
• 所有命令均输出 JSON

环境

• MIMO_APIKEY — API Key，必填。脚本会自动从 ~/.wmyskills/.env（多个技能共用）或 scripts/.env（优先级更高）加载该变量。使用 scripts/.env.example 作为模板——将该变量添加到 ~/.wmyskills/.env，切勿覆盖已有文件。