# MiMo V2.5 TTS — Hermes Agent Plugin

Xiaomi MiMo V2.5 语音合成插件，为 Hermes Agent 提供高质量中英文 TTS 能力。

## 功能

- 9 个内置音色（4 中文 + 4 英文 + 1 自动）
- 3 种模型：内置音色 / 语音设计 / 声音克隆
- 自然语言风格控制（播音员、讲故事、方言、情绪等）
- 流式输出支持
- 兼容 Hermes 语音气泡投递（Telegram 等）

## 音色列表

| ID | 名称 | 语言 | 性别 |
|----|------|------|------|
| `mimo_default` | 默认 | 自动 | - |
| `冰糖` | Bingtang | 中文 | 女 |
| `茉莉` | Moli | 中文 | 女 |
| `苏打` | Suda | 中文 | 男 |
| `白桦` | Baihua | 中文 | 男 |
| `Mia` | Mia | 英文 | 女 |
| `Chloe` | Chloe | 英文 | 女 |
| `Milo` | Milo | 英文 | 男 |
| `Dean` | Dean | 英文 | 男 |

## 前置条件

- Hermes Agent 已安装并可运行
- Xiaomi MiMo API Key（获取地址：https://mimo.mi.com）

## 安装步骤

运行安装脚本：

```bash
bash ~/mimo-tts-hermes-plugin/setup.sh
```

脚本会自动完成：
1. 将插件文件复制到 `~/.hermes/plugins/tts/mimo/`
2. 在 Hermes 中启用插件（`hermes plugins enable tts/mimo`）
3. 将独立脚本复制到 `~/mimo_tts.py`

安装后需要手动配置（脚本会提示）：

```bash
# 设置 TTS provider
hermes config set tts.provider mimo

# 设置默认音色（可选，不设则用 mimo_default）
hermes config set tts.voice Mia

# 重启 session 生效
# 在 Hermes 中执行 /reset
```

## 使用方式

### Hermes 内置调用

配置完成后，Hermes 的 `text_to_speech` 工具会自动走 MiMo：

```
text_to_speech(text="你好世界")
```

### 独立脚本调用（不依赖 Hermes）

```bash
# 基本用法
python3 ~/mimo_tts.py "你好世界" --voice 冰糖

# 英文
python3 ~/mimo_tts.py "Hello world" --voice Mia

# 指定输出路径
python3 ~/mimo_tts.py "测试" --voice 茉莉 -o output.wav

# 语音设计模型（通过文字描述生成音色）
python3 ~/mimo_tts.py "Once upon a time" --model voicedesign \
    --style "A warm storyteller voice with British accent"

# 流式模式
python3 ~/mimo_tts.py "你好" --stream -o output.wav

# 列出音色
python3 ~/mimo_tts.py --list-voices

# 列出模型
python3 ~/mimo_tts.py --list-models
```

### Python API 调用

```python
import sys, os
sys.path.insert(0, os.path.expanduser("~/.hermes/hermes-agent"))
os.environ.setdefault("XIAOMI_API_KEY", "your_key")
os.environ.setdefault("XIAOMI_BASE_URL", "https://token-plan-cn.xiaomimimo.com/v1")

# 加载插件
import importlib.util
spec = importlib.util.spec_from_file_location(
    "mimo_tts", os.path.expanduser("~/.hermes/plugins/tts/mimo/__init__.py")
)
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)

provider = mod.MiMoTTSProvider()
provider.synthesize("你好世界", "output.wav", voice="冰糖")
```

## 环境变量

| 变量 | 必需 | 说明 |
|------|------|------|
| `XIAOMI_API_KEY` | ✅ | MiMo API Key |
| `XIAOMI_BASE_URL` | 可选 | API 端点（默认 `https://api.xiaomimimo.com/v1`，国内用户可能需要设为 `https://token-plan-cn.xiaomimimo.com/v1`） |

这些变量应配置在 `~/.hermes/.env` 中。

## 卸载

```bash
bash ~/mimo-tts-hermes-plugin/setup.sh --uninstall
```

或手动：

```bash
hermes plugins disable tts/mimo
rm -rf ~/.hermes/plugins/tts/mimo
rm -f ~/mimo_tts.py
```

## 文件说明

```
mimo-tts-hermes-plugin/
├── INSTALLATION.md   # 本文档
├── setup.sh          # 安装/卸载脚本
├── plugin.yaml       # Hermes 插件清单
├── __init__.py       # Hermes TTS Provider 实现
└── mimo_tts.py       # 独立命令行脚本
```