three.ws Audio

@three-ws/audio-mcp

为 3D AI Agent 添加声音和面容——通过任意 MCP 客户端使用文本转语音、语音转文本、音频到面部口型同步，以及动作捕捉片段库。

---

一个通过标准输入输出公开 three.ws 语音与动画处理流程的 Model Context Protocol 服务。让虚拟形象开口说话，让用户回应，再将语音转换为逐帧口型同步轨迹，并浏览录制的动作捕捉库——驱动 3D Agent 的嘴部和动作所需的一切功能。

语音合成、识别和口型同步均使用免费的 NVIDIA NIM 模型（Magpie TTS、Riva ASR、Audio2Face-3D），并以 OpenAI 作为付费语音合成备用方案——与 three.ws 平台采用相同的服务商策略。无需密钥即可开始；将 THREE_WS_BASE 指向一个部署即可使用。

安装

npm install @three-ws/audio-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/audio-mcp

快速开始

Claude Code，一行配置：

claude mcp add audio -- npx -y @three-ws/audio-mcp

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"audio": {
			"command": "npx",
			"args": ["-y", "@three-ws/audio-mcp"]
		}
	}
}

使用 MCP Inspector 检查功能：

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	只读	通过 Audio2Face-3D 将语音（传入的文本或已有音频）转换为逐帧 ARKit 混合形状口型同步轨迹。
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（布尔值），model（高级选项）。

audio_to_face — text 或 audio（必填其一），format（wav|pcm，音频路径），sampleRate（仅 PCM 格式适用），voice / language（文本路径）。

motion_capture_clips — kind（face|pose|hand|vmc），include_public（布尔值，仅限已认证用户），limit（1–100，默认 50），cursor。

motion_capture_clip — id（必填，片段 UUID）。

示例

// text_to_speech
> { "text": "Hello, I'm your three.ws agent.", "voice": "nova" }
{
  "ok": true,
  "voice": "Magpie-Multilingual.EN-US.Aria",
  "model": "magpie-tts-multilingual",
  "format": "wav",
  "mime": "audio/wav",
  "sizeBytes": 274476,
  "audio": "data:audio/wav;base64,UklGR…"
}

// audio_to_face (text path — returns audio + the lipsync track together)
> { "text": "Watch my lips move." }
{
  "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 令牌。提高按量计费的 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

---

_{属于 three.ws SDK 套件 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}