Mod³——模态调制器
  
给你的AI代理一个声音。
Mod³是一个Python MCP服务器，为Claude Code、Cursor和其他MCP兼容的AI工具提供文本到语音转换。它在Apple Silicon上本地运行四个TTS引擎，比实时更快地生成语音，并立即返回，因此代理在播放音频时仍能继续工作。
它做什么
- 非阻塞语音 --
speak()立即返回作业ID。音频在后台播放。代理在说话的同时编写代码。 - 队列感知输出 --每一个
speak()返回包括队列位置、估计等待时间和活动作业状态。代理人知道正在进行什么，而无需单独进行状态呼叫。 - 驳船探测 --VAD（语音活动检测）监控麦克风。如果用户开始讲话，播放将停止，并通知代理。不要谈论别人。
- 轮换 --双向意识到谁在说话。代理可以在决定发言或等待之前检查用户状态。
- 多模型路由 --一个接口后面有四个TTS引擎。语音名称决定了哪个引擎处理请求。
- 自适应缓冲 --基于EMA的到达率跟踪，具有动态启动阈值。正常负载下无缝播放，GPU争用下优雅降级。
- 结构化指标 --每次调用都会返回TTFA、RTF、每个块的计时、缓冲区健康状况、欠载计数和内存使用情况。代理可以诊断自己的音频质量。
发动机
| 发动机 | 型号 | 尺寸 | TTFA | 控制面 |
|---|---|---|---|---|
| 心 | Kokoro-82M-bf16 | 82M | ~60ms | 速度、重点（全大写）、起搏（标点符号） |
| 沃克斯塔尔 | Voxtral-4B-TTS-mlx-4bit | 4B | ~500ms | 20个语音预设，多语言 |
| 话匣子 | 喋喋不休-4位 | ~1B | ~60ms | 情感/夸张（0-1），语音克隆 |
| 火花 | 火花-TTS-0.5B-bf16 | 0.5B | ~1s | 音高（5级）、速度、性别 |
模型在首次使用时通过HuggingFace Hub下载。
快速开始
git clone https://github.com/cogos-dev/mod3.git
cd mod3
./setup.shHTTP-MCP（推荐）
将mod3作为持久守护进程启动，并通过HTTP-MCP连接。这是未来的规范传输。守护进程在代理会话之间保持活动状态，因此TTS引擎保持温暖，多个客户端可以共享一个实例。
# Start the server (or configure as a launchd service)
python server.py --http然后将MCP客户端指向HTTP-MCP端点：
{
"mcpServers": {
"mod3": {
"type": "http",
"url": "http://localhost:7860/mcp"
}
}
}stdio MCP（已弃用）
已弃用。 stdio MCP仍在运行，但正在逐步淘汰。每个客户端会话都会生成一个新的mod3进程，这意味着TTS引擎在每个连接上都会冷启动（Kokoro约为60秒），并且状态不会在会话之间共享。更喜欢上面的HTTP-MCP。A. DeprecationWarning 当此路径处于活动状态时，将在启动时打印到stderr。删除记录在 问题#11.对于尚未迁移的用户，stdio路径仍然可用。添加到您的项目 .mcp.json:
{
"mcpServers": {
"mod3": {
"command": "/path/to/mod3/.venv/bin/python",
"args": ["/path/to/mod3/server.py"]
}
}
}MCP工具
speak(text, voice?, stream?, speed?, emotion?)
合成文本并通过扬声器播放。立即返回作业ID、队列状态和估计等待时间。
speak("Hello world") → default voice (bm_lewis @ 1.25x)
speak("Hello world", voice="casual_male") → Voxtral
speak("Hello world", voice="chatterbox", emotion=0.8) → Chatterbox with high emotion
speak("Hello world", voice="am_michael", speed=1.4) → Kokoro fastspeech_status(job_id?, verbose?)
检查语音是否仍在播放，或从上次完成的作业中获取指标。通过 verbose=True 用于每个块的详细信息。
stop()
立即中断当前讲话。
vad_check()
检查麦克风是否有语音活动。返回用户当前是否正在讲话，使代理能够在响应之前等待自然暂停。
list_voices()
列出按引擎分组的所有可用语音，并带有控制面标签。
set_output_device(device?)
列出音频输出设备，或在会话中期切换活动设备。
diagnostics()
显示加载的引擎、活动作业、输出设备和上一代指标。
建筑
两个文件：
server.py--MCP工具定义、多模型注册表、句子分块、非阻塞作业管理、队列感知返回adaptive_player.py--基于回调的音频播放，具有EMA到达率跟踪、自适应启动阈值和结构化指标收集功能
自适应玩家与模型无关。任何产生音频块的TTS引擎都会向同一管道馈送。
需求
- 带苹果硅（M1/M2/M3/M4）的macOS
- Python 3.10+
- 具体(
brew install espeak-ng)--Kokoro的电话听筒需要
使用语音作为模态
看 skills/voice/SKILL.md 关于双模交流的完整指南——何时说与何时写、非阻塞模式、阅读指标和反模式。
声音承载着短暂的（语境、意图、语调）。文本携带持久性（代码、数据、决策）。两个通道同时激活。
生态系统
Mod³是语音层 科戈斯 生态系统。它集成为一个模态通道——当语音输出合适时，内核会将意图路由到Mod³。无需CogOS即可独立工作。
许可证
麻省理工学院