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
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):
- Environment variables:
VOX_SPEED, VOX_VOICE, VOX_MODEL_DIR, VOX_LOG_LEVEL, VOX_PORT
- TOML file:
$XDG_CONFIG_HOME/vox/config.toml
- 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
- Make changes
cargo test — verify all 84 tests pass
cargo clippy -- -D warnings — zero warnings
cargo fmt --check — formatting
- If touching
audio.rs resampling: cargo bench -- resample
1---2name: vox3description: Lightweight voice MCP server with local Moonshine STT + Kokoro TTS4version: 0.1.05tags: [mcp, voice, tts, stt, rust]6metadata:7 source: https://skillmd.com/skills/diegosouzapw/vox8---910# Vox — Claude Code Skill1112## Project Overview1314Vox 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.1516## Build & Test1718```bash19cargo check # type-check only20cargo test # run all unit tests (84 tests across 10 modules)21cargo clippy -- -D warnings # lint — must pass with zero warnings22cargo build --release # optimized build (LTO + single codegen unit)23cargo bench -- resample # benchmark resampling24```2526All of `cargo test`, `cargo clippy -- -D warnings`, and `cargo fmt --check` must pass before submitting changes.2728## Architecture2930| Module | Purpose |31|--------|---------|32| `main.rs` | Entry point, config loading, model download, stdio/daemon startup |33| `cli.rs` | Clap CLI parser: daemon, config, download-models subcommands |34| `server.rs` | MCP tool handlers (`say`, `listen`, `converse`), streaming TTS pipeline |35| `tts.rs` | Kokoro TTS engine wrapper, voice name → speaker ID resolution, sentence splitting |36| `audio.rs` | cpal-based mic capture and speaker playback, Lanczos-3 sinc resampling |37| `stt.rs` | Moonshine Base STT engine wrapper |38| `vad.rs` | Voice activity detection (Silero ONNX) |39| `config.rs` | TOML config loading, env var overrides (`VOX_*` prefix), path resolution |40| `daemon.rs` | HTTP daemon lifecycle: daemonize, PID file, start/stop/status/log |41| `models.rs` | Model readiness checks and download/extraction |42| `lib.rs` | Public re-exports for benchmarks (`audio`, `config`, `error`, `tts`) |43| `error.rs` | `VoiceError` enum with `thiserror` derives |4445## Transport Modes4647- **Stdio** (default): `rmcp::transport::stdio()`. One process per MCP client.48- **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>>`.4950## Config System5152Precedence (highest wins):531. Environment variables: `VOX_SPEED`, `VOX_VOICE`, `VOX_MODEL_DIR`, `VOX_LOG_LEVEL`, `VOX_PORT`542. TOML file: `$XDG_CONFIG_HOME/vox/config.toml`553. Compiled defaults (`Config::default()`)5657CLI management: `vox config get [key]`, `vox config set <key> <value>`, `vox config path`5859## MCP Tools6061| Tool | Description |62|------|-------------|63| `say` | Speak text aloud through speakers (TTS only) |64| `listen` | Record from microphone and transcribe (STT only) |65| `converse` | Speak text then listen for response (TTS + STT round-trip) |6667## Available Voices6869American female (`af_*`): heart, alloy, aoede, bella, jessica, kore, nicole, nova, river, sarah, sky70American male (`am_*`): adam, echo, eric, liam, michael, onyx, puck, santa71British female (`bf_*`): alice, emma, lily72British male (`bm_*`): daniel, fable, george, lewis7374Default: `af_heart` (ID 0). Voices can be specified by name or numeric ID.7576## Code Conventions7778- **Edition 2024** — uses `let` chains (`if let Ok(x) = ... && let Ok(y) = ...`)79- **Visibility**: `pub(crate)` for test-only exposure, not fully `pub`80- **Clippy**: treat all warnings as errors (`-D warnings`)81- **Tests**: inline `#[cfg(test)] mod tests` per module, `tempfile` for filesystem tests82- **`unsafe impl Send`**: `TtsEngine` and `CaptureHandle` have manual `Send` impls due to non-Send cpal/sherpa internals confined to dedicated threads8384## Dev Workflow85861. Make changes872. `cargo test` — verify all 84 tests pass883. `cargo clippy -- -D warnings` — zero warnings894. `cargo fmt --check` — formatting905. If touching `audio.rs` resampling: `cargo bench -- resample`