声音

人工智能 社区 v0.1.0

技能解读

当前原文的自动摘译,尚未人工审校。

构建和测试

在提交更改之前,所有cargo test、cargo clippy -- -D warnings和cargo fmt --check都必须通过。

建筑

模块 · 用途 main.rs · 入口点、配置加载、模型下载、stdio/守护进程启动 cli.rs · Clap CLI 解析器:守护进程、配置、下载模型子命令 server.rs · MCP 工具处理程序(say、listen、converse)、流式 TTS 管道tts.rs·Kokoro TTS引擎封装,语音名称→说话人ID解析,句子分割

运输方式

Stdio(默认):rmcp::transport::stdio()。每个 MCP 客户端一个进程。守护进程 (vox daemon start [--port PORT]):通过 rmcp StreamableHttpService。单进程、模型加载一次、多个客户端通过 HTTP/SSE 连接。工厂关闭会为每个会话创建一个VoiceMcpServer,并共享Arc<Mutex<TtsEngine>>和Arc<Mutex<SttEngine>>。

配置系统

优先级(最高获胜): 环境变量:VOX_SPEED、VOX_VOICE、VOX_MODEL_DIR、VOX_LOG_LEVEL、VOX_PORT TOML 文件:$XDG_CONFIG_HOME/vox/config.toml 编译默认值 (Config::default()) CLI 管理:vox config get [key]、 vox config set <key> <value>、vox config path

MCP 工具

工具 · 说明 say · 通过扬声器大声说出文本(仅限 TTS) listen · 从麦克风录音并转录(仅限 STT) converse · 说出文本,然后聆听响应(TTS + STT 往返)

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
98 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@diegosouzapw · v0.1.0 · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 命令执行
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)
作者说明文件(原文) SKILL.md

# Vox — Claude Code Skill

## Project Overview

Vox is a lightweight voice MCP server (~1,500 lines of Rust) providing local text-to-speech (Kokoro) and speech-to-text (Moonshine Base) via the MCP protocol. It runs as a stdio subprocess per MCP client, or as a shared HTTP daemon.

## Build & Test

```bash
cargo check                    # type-check only
cargo test                     # run all unit tests (84 tests across 10 modules)
cargo clippy -- -D warnings    # lint — must pass with zero warnings
cargo build --release          # optimized build (LTO + single codegen unit)
cargo bench -- resample        # benchmark resampling
```

All of `cargo test`, `cargo clippy -- -D warnings`, and `cargo fmt --check` must pass before submitting changes.

## Architecture

| Module | Purpose |
|--------|---------|
| `main.rs` | Entry point, config loading, model download, stdio/daemon startup |
| `cli.rs` | Clap CLI parser: daemon, config, download-models subcommands |
| `server.rs` | MCP tool handlers (`say`, `listen`, `converse`), streaming TTS pipeline |
| `tts.rs` | Kokoro TTS engine wrapper, voice name → speaker ID resolution, sentence splitting |
| `audio.rs` | cpal-based mic capture and speaker playback, Lanczos-3 sinc resampling |
| `stt.rs` | Moonshine Base STT engine wrapper |
| `vad.rs` | Voice activity detection (Silero ONNX) |
| `config.rs` | TOML config loading, env var overrides (`VOX_*` prefix), path resolution |
| `daemon.rs` | HTTP daemon lifecycle: daemonize, PID file, start/stop/status/log |
| `models.rs` | Model readiness checks and download/extraction |
| `lib.rs` | Public re-exports for benchmarks (`audio`, `config`, `error`, `tts`) |
| `error.rs` | `VoiceError` enum with `thiserror` derives |

## Transport Modes

- **Stdio** (default): `rmcp::transport::stdio()`. One process per MCP client.
- **Daemon** (`vox daemon start [--port PORT]`): `StreamableHttpService` via rmcp. Single process, models loaded once, multiple clients connect over HTTP/SSE. Factory closure creates a `VoiceMcpServer` per session with shared `Arc<Mutex<TtsEngine>>` and `Arc<Mutex<SttEngine>>`.

## Config System

Precedence (highest wins):
1. Environment variables: `VOX_SPEED`, `VOX_VOICE`, `VOX_MODEL_DIR`, `VOX_LOG_LEVEL`, `VOX_PORT`
2. TOML file: `$XDG_CONFIG_HOME/vox/config.toml`
3. Compiled defaults (`Config::default()`)

CLI management: `vox config get [key]`, `vox config set <key> <value>`, `vox config path`

## MCP Tools

| Tool | Description |
|------|-------------|
| `say` | Speak text aloud through speakers (TTS only) |
| `listen` | Record from microphone and transcribe (STT only) |
| `converse` | Speak text then listen for response (TTS + STT round-trip) |

## Available Voices

American female (`af_*`): heart, alloy, aoede, bella, jessica, kore, nicole, nova, river, sarah, sky
American male (`am_*`): adam, echo, eric, liam, michael, onyx, puck, santa
British female (`bf_*`): alice, emma, lily
British male (`bm_*`): daniel, fable, george, lewis

Default: `af_heart` (ID 0). Voices can be specified by name or numeric ID.

## Code Conventions

- **Edition 2024** — uses `let` chains (`if let Ok(x) = ... && let Ok(y) = ...`)
- **Visibility**: `pub(crate)` for test-only exposure, not fully `pub`
- **Clippy**: treat all warnings as errors (`-D warnings`)
- **Tests**: inline `#[cfg(test)] mod tests` per module, `tempfile` for filesystem tests
- **`unsafe impl Send`**: `TtsEngine` and `CaptureHandle` have manual `Send` impls due to non-Send cpal/sherpa internals confined to dedicated threads

## Dev Workflow

1. Make changes
2. `cargo test` — verify all 84 tests pass
3. `cargo clippy -- -D warnings` — zero warnings
4. `cargo fmt --check` — formatting
5. If touching `audio.rs` resampling: `cargo bench -- resample`

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。