MiMo TTS Course Assignment

A small Python CLI and course assignment demonstrating Xiaomi MiMo V2.5 TTS API integration.

这是一个通过 Xiaomi MiMo V2.5 TTS API 将文本转换为语音的小型命令行 Demo。 项目定位为 Course Assignment / Python CLI / TTS API Integration Demo，不是自研语音模型或完整的有声书平台。

Features

• 支持 UTF-8 TXT 文件或命令行直接文本输入
• 支持 8 个 MiMo V2.5 TTS 预置音色：冰糖、茉莉、苏打、白桦、Mia、Chloe、Milo、Dean
• 支持用自然语言描述朗读语气、情绪和语速
• 支持 MP3 与 WAV 输出
• 对 API 返回的 Base64 音频进行严格解码
• 写入前检查 MP3 / WAV 文件头
• 使用临时文件和原子替换，降低输出文件损坏风险
• 对身份验证、限流、网络和 API 状态错误提供可读提示

Demo

Demo 输入文件：sample_text.txt

夜色渐渐笼罩山谷，远处的灯火一盏接一盏亮起。林间的风轻轻吹过树梢，带来潮湿泥土和青草的气息。年轻的旅人停下脚步，望着山路尽头微弱的光，重新整理行囊，继续向前走去。

示例输出：sample_output.mp3

sample_text.txt 是 demo input；sample_output.mp3 是由该示例输入通过 MiMo TTS 生成的 example output。音频仅用于展示大致效果，不是程序运行依赖，也不代表本项目训练或拥有语音模型。

Requirements

• Python 3.10+
• Internet connection
• Xiaomi MiMo API account
• 有效的 MIMO_API_KEY
• 可用的 API quota；实际调用可能产生费用

Installation

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Linux / macOS 激活虚拟环境时使用：

source .venv/bin/activate

API Key Configuration

在当前 Windows PowerShell 会话中设置：

$env:MIMO_API_KEY="YOUR_API_KEY"

该设置只对当前 PowerShell 会话生效。Never commit API keys or .env files to Git.

Usage

查看完整参数：

python mimo_tts.py --help

从文件生成

python mimo_tts.py --input sample_text.txt --output output_audio.mp3

直接文本

python mimo_tts.py --text "你好，这是一个 MiMo TTS 演示。" --output output_audio.mp3

选择声音

python mimo_tts.py --input sample_text.txt --voice 茉莉 --output output_audio.mp3

风格控制

python mimo_tts.py --input sample_text.txt --style "温柔、平静、自然，语速稍慢，停顿清晰" --output output_audio.mp3

WAV / MP3

输出格式通常由文件扩展名决定：

python mimo_tts.py --input sample_text.txt --output output_audio.wav
python mimo_tts.py --input sample_text.txt --output output_audio.mp3

也可以显式指定格式；若扩展名不一致，程序会按 --format 调整扩展名：

python mimo_tts.py --input sample_text.txt --output output_audio.mp3 --format wav

Project Structure

mimo-tts-course-assignment/
├── README.md
├── LICENSE
├── .gitignore
├── requirements.txt
├── mimo_tts.py
├── sample_text.txt
└── sample_output.mp3

How It Works

text → MiMo API → Base64 audio → decode → validate → MP3/WAV

程序读取并验证文本，通过固定的 Xiaomi MiMo 官方 API endpoint 请求语音；收到 Base64 音频后进行解码和文件头检查，最后原子写入目标文件。

Limitations

• 依赖云端 API 和 Internet connection
• API 使用可能产生费用
• 不是离线 TTS 模型，不包含模型训练
• 不自动拆分长篇书籍章节
• 不提供批量有声书管理
• 不包含音频拼接 pipeline

Course Assignment

这是一个课程小作业，重点展示 Python CLI、第三方 TTS API 集成、输入验证和安全文件写入。它被整理为可公开阅读和运行的小型作品集项目。

Attribution / AI Assistance

项目开发过程中使用了 AI 辅助进行代码审阅与文档整理。API 交互设计与实现参考并修改自 XiaomiMiMo/MiMo-Skills 中的 MiMo V2.5 TTS 官方示例；上游代码采用 MIT License。

Xiaomi、MiMo 及相关名称归其各自权利人所有。本项目是独立课程作业 Demo，不代表 Xiaomi 官方项目或认可。

License

本项目采用 MIT License。许可证中同时保留了本项目与所参考 XiaomiMiMo MIT 示例的版权声明。