Skill: aaroncxxx/mimo-tts-asr-26-free (version 2.99.92)

# 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 - ⚠️ 避坑要点


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)