Mimo Tts Asr 26 Free

SKILL.md

# MiMo TTS & ASR v2.99.92 Free For Now

语音合成（TTS）与语音识别（ASR）Skill。三款 TTS 模型限时免费，ASR 云端预留中。

> **关于作者** — 十五年老米粉，用龙虾编程，撸起袖子就是干。
>
> **ClawHub Skill vs 官方 MiMo V2.5 TTS 差异分析**
>
> 官方提供的是"模型能力"，本 Skill 提供的是"工程化产品"——防限流、长文本分句、edge-tts 兜底、缓存、重试，这些生产环境必须但官方不提供的东西，全在这了。官方是引擎，本 Skill 是整车。
>
> | 维度 | 本 Skill | 官方 |
> |------|---------|------|
> | 三合一封装 | 一个脚本统一调用 3 款 TTS 模型 | 只给 API，不给封装脚本 |
> | edge-tts 兜底 | 无 Key 自动降级到免费 TTS | 无降级方案 |
> | 防限流 | 随机延迟 + 并发控制 | 无客户端限流策略 |
> | 长文本分句 | 120 字/段自动切分 | 不处理长文本 |
> | 音频缓存 | 相同文本秒返，零消耗 | 无缓存 |
> | 异常重试 | 502/503/timeout 自动重试 | 不处理 |
> | 文本预处理 | 数字/符号/格式自动规范化 | 不处理 |
> | ASR 封装 | asr.py 封装（需 GPU 或等云端开放） | 只开源模型，不给脚本 |
> | 联合工作流 | TTS + ASR 串联示例 | 无工作流文档 |
> | 开源方案指南 | edge-tts/ChatTTS/GPT-SoVITS 等推荐 | 无 |
> | 批量合成 | `--file` 逐行读取批量处理 | 无 |
> | 格式自动检测 | 根据 `-o` 后缀推断格式 | 需手动指定 |
> | 默认预处理 | 数字/符号自动规范化（默认开启） | 无 |
> | 智能音色推荐 | `--recommend-voice` 根据情感/语言自动选音色 | 无 |
> | 质量自检 | 合成后自动检测空文件/静音/过短 | 无 |
> | 目录监听 | `--watch` 自动合成新增 .txt 文件 | 无 |

## 系统依赖

- **ffmpeg/ffprobe**：音频预处理、分片、格式转换必需
- **python3**：运行脚本

```bash
apt install ffmpeg  # Debian/Ubuntu
brew install ffmpeg  # macOS
```

## 配置

```bash
export MIMO_API_KEY="your-api-key"
```

或通过 OpenClaw 配置：
```bash
openclaw config set skills.entries.mimo-tts-asr.apiKey "your-key"
```

申请 Key：[platform.xiaomimimo.com](https://platform.xiaomimimo.com)（当前限时免费）

> 🎧 **在线体验**：[MiMo Studio](https://aistudio.xiaomimimo.com/#/c) 可快速试听各模型效果，无需配置。

> 💡 **无 Key 也能用**：不设 `MIMO_API_KEY` 时自动走 edge-tts 免费通道（仅支持预置音色模式）

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `MIMO_API_KEY` | — | MiMo TTS API Key（必填，或走 edge-tts 兜底） |
| `MIMO_ASR_KEY` | — | ASR API Key（可与 TTS 相同） |
| `MIMO_API_ENDPOINT` | `https://api.xiaomimimo.com/v1` | API 端点（可自定义） |
| `MIMO_TTS_MODEL` | `mimo-v2-audio-tts` | 默认 TTS 模型名 |
| `MIMO_VOICE_SAMPLE` | — | 默认声音克隆参考音频路径 |
| `USE_CLOUD_TTS` | `1` | 设为 `0` 切换到 edge-tts 兜底 |

## TTS — 语音合成

### 基础用法

```bash
python3 "{baseDir}/scripts/tts.py" "要合成的文本" -o output.wav
```

### 三款模型

| 模型 | 用途 | 关键参数 |
|------|------|---------|
| `tts`（默认） | 内置音色 + 情感/语速控制 | `-v` 音色, `-s` 风格 |
| `voice-design` | 自然语言描述生成新音色 | `--voice-desc` |
| `voice-clone` | 参考音频克隆音色 | `--ref-audio` |

### 预置音色

| 音色 | 语言 | 性别 | 风格 |
|------|------|------|------|
| 冰糖 | 中文 | 女 | 活泼少女，清脆甜美 |
| 茉莉 | 中文 | 女 | 知性女声，温柔稳重 |
| 苏打 | 中文 | 男 | 阳光少年，活力朝气 |
| 白桦 | 中文 | 男 | 成熟男声，沉稳大气 |
| Mia | English | Female | Lively girl |
| Chloe | English | Female | Witty Grace |
| Milo | English | Male | Sunny boy |
| Dean | English | Male | Steady Gentle |

> 💡 不设 `MIMO_API_KEY` 时自动走 **edge-tts** 免费通道（音色自动匹配）

### TTS 参数速查

### 行内音频标签

在文本中插入精细控制：
`(停顿) (叹气) (笑声) (清嗓子) (耳语) (紧张) (小声) (语速加快) (深呼吸) (沉默片刻)`

> 💡 **多标签组合**：`开心 变快` 放在文本开头设置整体风格。支持任意自然语言风格短语，无固定值限制。

### 导演剧本级结构化输入

对于有声剧、游戏角色、角色化对话等高一致性场景，支持分层描述：

```bash
python3 "{baseDir}/scripts/tts.py" "
【人物】林黛玉，柔弱敏感，语速偏慢
【场景】葬花，暮春时节，落花满地
【指导】声音带哽咽感，气息不稳，尾音渐弱
花谢花飞花满天，红消香断有谁怜？
" -o lin_daiyu.wav
```

模型会将人物、场景、指导三层独立理解，保持角色音色贯穿，同时每句话的表演单独控制。

### 文本理解能力

无需任何 prompt 或标签——纯文本也能自动表现出韵律与情感：

- **标点停顿**：句号、逗号、省略号自动对应自然停顿
- **情感弧线**：从平静到激烈的情感转折自动捕捉
- **说话人身份**：字里行间的年龄、气质、角色类型自动落入声音

```bash
# 零 prompt，模型自动理解文本情感
python3 "{baseDir}/scripts/tts.py" "他沉默了很久，终于开口：算了，就这样吧。" -o auto_emotion.wav
```

### 唱歌模式

传入歌词即可合成歌声：

```bash
# 直接传歌词
python3 "{baseDir}/scripts/tts.py" "两只老虎，两只老虎，跑得快" -s "唱歌" -o song.wav

# 歌名字典查找（需 sing0301_dict.json）
python3 "{baseDir}/scripts/tts.py" "两只老虎" -s "唱歌" -o song.wav

# 英文歌词
python3 "{baseDir}/scripts/tts.py" "Yesterday, all my troubles seemed so far away" -s "唱歌" -o song_en.wav
```

### 文本规范化指南

合成前建议对输入文本做预处理，确保数字、符号、格式渲染为自然口语：

**数字**
| 输入 | 口语化 |
|------|--------|
| `3.14` | 三点一四 |
| `1/3` | 三分之一 |
| `14:30` | 下午两点半 |
| `95%` | 百分之九十五 |
| `2024`（年份） | 二零二四年 |

**符号**
| 符号 | 口语化 |
|------|--------|
| `+` `-` `×` `÷` | 加 减 乘以 除以 |
| `=` `>` `<` | 等于 大于 小于 |
| `~` | 大约 |
| `...` `…` | 等等 |

**格式清理**
- 去掉 markdown 标记（`**bold**`、`# heading`、`` `code` ``）
- 编号列表转口语：「有三点，第一……第二……第三……」
- 表格转描述句

> 💡 开启 `--preprocess` 参数可自动完成上述大部分预处理。

> **📝 v3.0 变更**：预处理现在默认开启，无需手动加 `--preprocess`。如需关闭，使用 `--no-preprocess`。

### 核心示例

```bash
# 基础
python3 "{baseDir}/scripts/tts.py" "你好，今天天气真好" -o hello.wav

# 方言
python3 "{baseDir}/scripts/tts.py" "哎呀妈呀，这天儿也忒冷了吧" -s "东北话" -o dongbei.wav

# 情感 + 语速
python3 "{baseDir}/scripts/tts.py" "明天就是周五了！" -s "开心 变快" -o happy.wav

# 男声 / 童声 / 粤语
python3 "{baseDir}/scripts/tts.py" "大家好" -v 苏打 -o male.wav

# VoiceDesign — 生成新音色
python3 "{baseDir}/scripts/tts.py" "欢迎" -m voice-design \
  --voice-desc "元气少女，声线清脆，语尾上扬" -o genki.wav

# VoiceClone — 克隆音色
python3 "{baseDir}/scripts/tts.py" "克隆后的声音" -m voice-clone \
  --ref-audio reference.wav -o cloned.wav

# 推荐组合：预处理 + 归一化 + 微调
python3 "{baseDir}/scripts/tts.py" "长文本..." --normalize -o output.wav
```

### 批量合成

从文件逐行读取文本，批量生成音频：

```bash
# 准备文本文件（每行一段）
cat > lines.txt << 'EOF'
欢迎收听今天的节目
接下来为您播报天气预报
感谢您的收听，下次再见
EOF

# 批量合成
python3 "{baseDir}/scripts/tts.py" --file lines.txt -o output.wav

# 输出：output_001.wav, output_002.wav, output_003.wav
```

### 智能音色推荐

根据文本内容自动选择最佳音色（情感检测 + 语言判断）：

```bash
python3 "{baseDir}/scripts/tts.py" "恭喜你获得了一等奖！" --recommend-voice -o output.wav
# [智能推荐] 音色: 冰糖（检测到开心情感）

python3 "{baseDir}/scripts/tts.py" "Important meeting tomorrow" --recommend-voice -o output.wav
# [智能推荐] 音色: Mia（检测到英文内容）
```

**推荐逻辑：**
| 情感/语言 | 中文推荐 | 英文推荐 |
|-----------|---------|---------|
| 开心/欢快 | 冰糖 | Mia |
| 悲伤/温柔 | 茉莉 | Chloe |
| 生气/激动 | 苏打 | Milo |
| 严肃/正式 | 白桦 | Dean |
| 默认 | 冰糖 | Mia |

### 格式自动检测

根据 `-o` 输出路径后缀自动推断格式，无需手动指定 `-f`：

```bash
python3 "{baseDir}/scripts/tts.py" "你好" -o output.wav    # → WAV
python3 "{baseDir}/scripts/tts.py" "你好" -o output.mp3    # → MP3
python3 "{baseDir}/scripts/tts.py" "你好" -o output.ogg    # → OGG
```

### 目录监听模式

监听目录，自动合成新增的 `.txt` 文件：

```bash
# 启动监听（Ctrl+C 退出）
python3 "{baseDir}/scripts/tts.py" --watch /path/to/watch

# 往目录里放 .txt 文件，自动生成同名音频
echo "新的一段文本" > /path/to/watch/news.txt
# → 自动生成 /path/to/watch/news.wav
```

### 质量自检

合成后自动检测输出质量：
- ❌ 文件不存在 → 报错
- ❌ 文件为空 → 报错
- ⚠️ 文件过小 (<1KB) → 警告（可能静音）
- ⚠️ WAV 头异常 → 警告

## ASR — 语音识别（云端预留）

> ⚠️ ASR 云端 API 暂未开放，以下为预留文档。本地部署需 GPU（CUDA），详见 [GitHub](https://github.com/XiaomiMiMo/MiMo-V2.5-ASR)。

### 基础用法

```bash
python3 "{baseDir}/scripts/asr.py" audio.wav
```

### 参数速查

| 参数 | 默认 | 说明 |
|------|------|------|
| `-o` | stdout | 输出路径 |
| `--lang` | auto | 语言：auto / zh / en / ja / ko |
| `--format` | text | 输出：text / json / srt |
| `--preprocess` | 关 | 音频预处理（采样率/静音裁剪） |
| `--chunk` | 0 | 长音频分片秒数（0=不分片） |
| `--max-retries` | 3 | 最大重试次数 |

### 核心示例

```bash
# 基础转录
python3 "{baseDir}/scripts/asr.py" recording.wav

# 保存到文件
python3 "{baseDir}/scripts/asr.py" meeting.mp3 -o meeting.txt

# SRT 字幕
python3 "{baseDir}/scripts/asr.py" video_audio.wav --format srt -o subtitles.srt
```

## TTS + ASR 联合工作流（云端预留）

```bash
# 1. 识别（需本地 GPU 或云端 API 开放后使用）
python3 "{baseDir}/scripts/asr.py" input.wav -o transcript.txt

# 2. 修改后用不同音色重新合成
python3 "{baseDir}/scripts/tts.py" "$(cat transcript.txt)" -v 苏打 -o output.wav
```

## 交付格式

- **TTS**：`MEDIA:output.wav`（或指定的 `-o` 路径）
- **ASR**：直接回复转录文本，或回复 `-o` 指定的文件路径

### 输出格式保证

| 属性 | 值 |
|------|-----|
| 格式 | WAV (RIFF) / MP3 / OGG（通过 `-f` 切换） |
| 采样率 | 24,000 Hz |
| 位深 | 16-bit PCM |
| 声道 | Mono |

- API 返回 PCM 时自动补 RIFF WAV 头
- 输出文件写入失败时返回非零退出码 + 错误信息
- 支持 `--denoise` 后置降噪、`--normalize` 音量归一化
- 支持 `--cache` 相同文本秒返（缓存持久化到 `{baseDir}/cache`）

## 故障排查

| 错误 | 原因 | 解决 |
|------|------|------|
| 401 Invalid API Key | Key 未配置或格式错误 | 确认已配置 `MIMO_API_KEY`，检查是否为平台申请的正确 Key |
| 429 Too Many Requests | 触发限流 | 等几秒重试（脚本自动重试，最大 3 次） |
| 502/503 Bad Gateway | 服务端临时异常 | 脚本自动重试，连续失败则检查服务状态 |
| Timeout | 网络超时 | 检查网络连接，脚本自动重试 |
| 文件不存在 | 路径错误 | 检查音频文件路径，确认父目录存在 |
| ffmpeg 未找到 | 缺系统依赖 | `apt install ffmpeg` 或 `brew install ffmpeg` |
| edge-tts 未安装 | 兜底方案缺失 | `pip install edge-tts` |
| 输出文件为空 | API 返回异常 | 检查 Key 余额、文本长度，查看 stderr 原始响应 |

## 进阶优化

推理性能优化（GPU/CPU）、模型剪枝、TensorRT/OpenVINO 加速、FastAPI 封装等高级用法，详见 `docs/advanced.md`。

## 性能基准

典型延迟数据（仅供参考，实际受网络和文本长度影响）：

| 场景 | 文本长度 | 延迟 | 说明 |
|------|---------|------|------|
| 短句 | <20 字 | ~1-2s | 最常见场景 |
| 中等段落 | 20-80 字 | ~2-4s | 正常语速 |
| 长文本 | 80-200 字 | ~4-8s | 自动分句 |
| 超长文本 | >200 字 | ~8-15s | 多段拼接 |
| edge-tts 兜底 | 任意 | ~1-3s | 不经过 MiMo API |
| 缓存命中 | 任意 | <0.1s | 零消耗 |

> 💡 首次合成较慢（冷启动），后续相同文本走缓存秒返。

## 费用说明

| 项目 | 当前 | 正式价格（参考） |
|------|------|----------------|
| MiMo TTS | **限时免费** | 未公布，预计按字符计费 |
| MiMo VoiceDesign | **限时免费** | 未公布 |
| MiMo VoiceClone | **限时免费** | 未公布 |
| edge-tts | **永久免费** | — |

**Token 消耗估算（MiMo API）：**
- 短句（20 字）≈ 20-30 tokens
- 中等段落（100 字）≈ 100-150 tokens
- 长文本（500 字）≈ 500-750 tokens

> ⚠️ 限时免费期间无消耗，正式计费后建议开启 `--cache` 减少重复合成。

## 质量对比

| 维度 | MiMo TTS v2.5 | edge-tts | ChatTTS | GPT-SoVITS |
|------|---------------|----------|---------|------------|
| 音质 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 中文支持 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 情感控制 | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| 声音克隆 | ⭐⭐⭐⭐⭐ | ❌ | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| 延迟 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| 部署难度 | 云端免费 | 云端免费 | 需 GPU | 需 GPU |
| 适合场景 | 通用/专业 | 简单播报 | 对话/闲聊 | 专业配音 |

## 开源免费 TTS 备选方案

以下为可替代或补充 MiMo TTS 的开源方案，按是否需要 GPU / 免费 API 分类：

### 免费云端（无需 GPU、无需 API Key）

| 项目 | ⭐ | 说明 | 安装 |
|------|-----|------|------|
| **edge-tts** | 10.7k | 微软 Edge 在线 TTS，中文音色丰富，完全免费 | `pip install edge-tts` |

### 需自建部署（需 GPU）

| 项目 | ⭐ | 说明 |
|------|-----|------|
| **ChatTTS** | 39.2k | 日常对话语音生成，效果自然 |
| **CosyVoice** | 20.7k | 阿里多语言大模型，支持中英日韩 |
| **fish-speech** | 29.9k | SOTA 开源 TTS，音质极高 |

### GitHub TTS 项目星数 Top 5

| # | 项目 | ⭐ | 说明 |
|---|------|-----|------|
| 1 | **Real-Time-Voice-Cloning** | 59.6k | 5秒实时语音克隆 |
| 2 | **GPT-SoVITS** | 56.9k | 1分钟数据训练 TTS（少样本克隆） |
| 3 | **coqui-ai/TTS** | 45.2k | 生产级深度学习 TTS 工具包 |
| 4 | **ChatTTS** | 39.2k | 日常对话语音生成 |
| 5 | **MockingBird** | 36.9k | 5秒实时语音克隆 |

> 💡 **推荐组合**：MiMo TTS（云端免费）+ edge-tts（备用免费）+ GPT-SoVITS（自建克隆）

## 版本历史

### v2.99.92 (2026-04-24)
- 🚀 **批量合成**：`--file` 逐行读取文本文件批量处理
- 🧠 **智能音色推荐**：`--recommend-voice` 根据情感/语言自动选音色
- 📐 **格式自动检测**：根据 `-o` 后缀推断 wav/mp3/ogg
- ⚡ **默认预处理**：数字/符号自动规范化（`--no-preprocess` 关闭）
- 🔍 **质量自检**：合成后自动检测空文件/静音/过短
- 👀 **目录监听**：`--watch` 自动合成新增 .txt 文件
- 📊 新增性能基准、费用说明、质量对比表
- 🎤 `--list-voices` 增加推荐场景信息

### v2.99.3 (2026-04-24)
- ✨ 新增导演剧本级结构化输入文档与示例
- ✨ 新增文本理解能力说明（零 prompt 自动情感表达）
- 🔗 新增 MiMo Studio 在线体验链接

### v2.99.2 (2026-04-24)
- ✨ 新增声音克隆详细文档与示例
- ✨ 新增唱歌模式文档（歌词直传 + 歌名字典）
- ✨ 新增完整文本规范化指南（数字/符号/格式）
- ✨ 新增环境变量覆盖表（6 项可配置）
- ✨ 新增输出格式保证说明（格式/采样率/位深/声道）
- 📋 故障排查扩展至 8 项（新增 502/503/Timeout/edge-tts/空文件）

### v2.99 (2026-04-24)
- 🛡️ 防限流：随机延迟 0.3~0.6s + 最大并发限制 (MAX_CONCURRENT=2)
- 📝 长文本自动分句分段合成（120字/段，按标点切分）
- 🔁 异常捕获：502/503/timeout 自动重试，不闪退
- 🔒 隐私：不打印 Key，临时文件自动清理
- ⚡ 开关：USE_CLOUD_TTS 一键切本地/edge-tts
- 🎤 音色表增加风格描述
- 📂 缓存目录改为 `{baseDir}/cache`（持久化）
- ⚠️ ffmpeg 缺失时给出明确提示
- 🔧 scripts 添加执行权限

### v2.95 (2026-04-24)
- 📝 标题更新为 MiMo TTS & ASR v2.95 Free For Now
- 🔧 修复默认音色（`mimo_default` → `冰糖`）
- ⚡ `--speed` / `--pitch` 标注为预留参数
- ☁️ ASR 部分标注云端预留
- 📋 示例修正为实际可用音色

### v2.92 (2026-04-24)
- ✅ 新增 `scripts/tts.py` — 三合一 TTS 脚本（预置音色/音色设计/音色克隆）
- ✅ 新增 `scripts/asr.py` — ASR 语音识别脚本（需本地 GPU）
- 🔗 API 对接 `https://api.xiaomimimo.com/v1`

### v2.9 (2026-04-24)
- 📐 SKILL.md 精简重构，聚焦用法，进阶内容拆至 docs/
- 🔧 修复 `--preprocess` 参数语义矛盾（改为显式开启）
- 📋 参数表统一格式，示例精简到核心场景

### v2.81 (2026-04-24)
- 📦 声明系统依赖 ffmpeg/ffprobe
- 🔑 明确 API Key 要求

### v2.8 (2026-04-24)
- 🚀 进阶优化：剪枝 / TensorRT / OpenVINO / FastAPI
- ⚠️ 避坑要点