内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/audio-mcp</h1>
<p align="center"><strong>为3D AI代理赋予声音和面容 — 文本转语音、语音转文本、音频转面部唇形同步，以及动作捕捉剪辑库，均可从任意MCP客户端访问。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/audio-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/audio-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/audio-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/audio-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，通过标准输入输出暴露了 three.ws 的 **语音和动画管道**。使头像说话，让用户回应，将语音转换为每帧的唇形同步轨道，并浏览录制的动作捕捉库 — 所有这些都是驱动 3D 代理口部和动作所需的。
语音识别和唇形同步通道运行在 **免费 NVIDIA NIM** 模型（Magpie TTS、Riva ASR、Audio2Face-3D）上，OpenAI 作为付费 TTS 备用服务 — 与 three.ws 平台相同的提供商策略。无需密钥即可启动；将 `THREE_WS_BASE` 指向部署并启动。
## 安装
```bash
npm install @three-ws/audio-mcp
```
或使用 `npx` 运行（无需安装）：
```bash
npx @three-ws/audio-mcp
```
## 快速开始
**Claude Code**，一行命令：
```bash
claude mcp add audio -- npx -y @three-ws/audio-mcp
```
**Claude Desktop / Cursor**（`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"audio": {
"command": "npx",
"args": ["-y", "@three-ws/audio-mcp"]
}
}
}
```
使用 MCP Inspector 检查表面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/audio-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| --- | --- | --- |
| `text_to_speech` | 只读 | 将文本合成语音；返回 base64 音频数据 URL 以及实际语音/格式/ MIME。免费 Magpie，OpenAI 备用。 |
| `speech_to_text` | 只读 | 使用免费 NVIDIA Riva 识别器转录语音音频（base64 wav/pcm/flac/ogg）；返回文本、置信度、时长。 |
| `audio_to_face` | 只读 | 将语音（您传递的文本或您拥有的音频）转换为每帧 ARKit 混合形状唇形同步轨道，通过 Audio2Face-3D。 |
| `motion_capture_clips` | 只读 | 浏览动作捕捉剪辑库 — 记录的面部/姿势/手/VMC 轨道 — 具有类别筛选和光标分页。 |
| `motion_capture_clip` | 只读 | 按 ID 获取一个剪辑，包括其完整的每帧动画轨道，以在头像上播放。 |
所有五个工具都是只读的：它们转换输入（合成/识别/动画）或读取实时库数据，从不改变平台状态。无幂等性 — 音频字节、转录和目录在调用之间移动。
### 输入参数
**`text_to_speech`** — `text`（必填，1–4096 个字符），`voice`（默认 `nova`），`format`（`mp3`|`opus`|`aac`|`flac`|`wav`|`pcm`，默认 `mp3`），`model`（仅 OpenAI 备用），`language`（BCP-47，默认 `en-US`），`speed`（0.5–2.0，仅 OpenAI 通道）。
**`speech_to_text`** — `audio`（必填，base64 或 `data:` URL），`format`（`wav`|`pcm`|`flac`|`ogg`，默认 `wav`），`language`（BCP-47，默认 `en-US`），`sampleRate`（Hz，仅 PCM），`words`（bool），`model`（高级）。
**`audio_to_face`** — `text` **或** `audio`（必填），`format`（`wav`|`pcm`，音频路径），`sampleRate`（仅 PCM），`voice` / `language`（文本路径）。
**`motion_capture_clips`** — `kind`（`face`|`pose`|`hand`|`vmc`），`include_public`（bool，仅认证用户），`limit`（1–100，默认 50），`cursor`。
**`motion_capture_clip`** — `id`（必填，剪辑 UUID）。
## 示例
```jsonc
// text_to_speech
> { "text": "你好 — 我是你的 three.ws 代理。"， "voice": "nova" }
{
"ok": true,
"voice": "Magpie-Nova",
"model": "magpie-tts-multilingual",
"format": "wav",
"mime": "audio/wav",
"sizeBytes": 84210,
"audio": "data:audio/wav;base64,UklGR…"
}
```
```jsonc
// audio_to_face（文本路径 — 返回音频和唇形同步轨道）
> { "text": "看着我的嘴唇动。" }
{
"ok": true,
"audio": { "base64": "UklGR…", "contentType": "audio/wav", "format": "wav" },
"animation": {
"fps": 30,
"blendShapeNames": ["jawOpen", "mouthClose", "…"],
"durationSec": 1.9,
"frames": [ { "t": 0.0, "w": [0.0, 0.1, /* … */] } ]
}
}
```
面部帧为 `{ t, w }`：`t` = 秒数从剪辑开始，`w` = 按 `blendShapeNames` 顺序排列的权重（ARKit-52 命名）。播放音频并按音频元素的 `currentTime` 采样轨道。
## 有效载体说明
音频通过 base64 跨线传输（TTS 返回它，ASR/A2F 接受它）。合成输入（`text`）和识别输入（`audio`，~8 MB 限制）都受平台限制 — 保持剪辑为口语语句而不是长录音。对于您已经拥有的音频，直接传递 `wav`/`pcm`；浏览器录制的 WebM/Opus 必须先解码为 WAV 或 PCM（Riva 和 Audio2Face 不接受 WebM 容器）。
## 要求
- **Node.js >= 20.**
- 访问 `https://three.ws` 的网络权限（或您自己的 `THREE_WS_BASE`）。
### 环境变量
| 变量 | 是否必填 | 默认值 | 用途 |
| --- | --- | --- | --- |
| `THREE_WS_BASE` | 否 | `https://three.ws` | 要连接的部署。 |
| `THREE_WS_API_KEY` | 否 | — | Bearer token。提高计量 TTS/ASR/A2F 速率限制并解锁您自己的私有动作捕捉剪辑。 |
| `THREE_WS_TIMEOUT_MS` | 否 | `60000` | 实时模型调用的每个请求超时。 |
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件为专有软件 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
