声音
- 作者仓库星标 39
- 作者仓库 awesome-omni-skill
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 98 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @diegosouzapw · v0.1.0 · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 命令执行
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
# 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`
章节与文件索引
按说明文件中的顺序排列。
构建和测试
建筑
运输方式
配置系统
MCP 工具
文件/命令 -> cargo test · cargo clippy -- -D warnings · cargo fmt --check · main.rs · cli.rs · server.rs · say · listen
内容校验值 -> 248b48e816d1
当前原文的自动摘译,尚未人工审校。
构建和测试
在提交更改之前,所有
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]):通过 rmcpStreamableHttpService。单进程、模型加载一次、多个客户端通过 HTTP/SSE 连接。工厂关闭会为每个会话创建一个VoiceMcpServer,并共享Arc<Mutex<TtsEngine>>和Arc<Mutex<SttEngine>>。配置系统
优先级(最高获胜): 环境变量:
VOX_SPEED、VOX_VOICE、VOX_MODEL_DIR、VOX_LOG_LEVEL、VOX_PORTTOML 文件:$XDG_CONFIG_HOME/vox/config.toml编译默认值 (Config::default()) CLI 管理:vox config get [key]、vox config set <key> <value>、vox config pathMCP 工具
工具 · 说明
say· 通过扬声器大声说出文本(仅限 TTS)listen· 从麦克风录音并转录(仅限 STT)converse· 说出文本,然后聆听响应(TTS + STT 往返)