VOICE · LOCAL-FIRST
voiceCLI
One CLI for speech synthesis and transcription, running entirely on local hardware. A single Markdown script format drives every engine — Qwen3-TTS, Chatterbox, Faster Whisper, Kyutai — and a built-in translator adapts it to each. No cloud keys, no rewrite when you switch models.
What it is
Local text-to-speech is scattered across incompatible APIs — each engine with its own parameter names, quirks, and input formats. Switching engines means rewriting your scripts. voiceCLI removes that: one command-line tool and one library, covering both synthesis (TTS) and transcription (STT) across several local engines.
Everything runs on your own GPU. No cloud API keys, no hosted inference, no per-character billing. It is built for developers and content creators who want expressive, multilingual speech on hardware they control.
The durable contract is the script, not the engine. Write it once; swap the backend without touching your input.
One script, every engine
A voiceCLI script is a Markdown file: YAML frontmatter for defaults, directives in the body for per-segment control. The same file plays on Qwen3-TTS, Chatterbox Multilingual, or Chatterbox Turbo — a built-in translator reads an engine capability matrix and adapts the script to whatever the target engine supports, remapping or dropping what it does not.
| Mode | Engines |
|---|---|
| Synthesis (TTS) | Qwen3-TTS · Chatterbox Multilingual · Chatterbox Turbo |
| Transcription (STT) | Faster Whisper · Kyutai |
The library mirrors the CLI: generate, clone, and transcribe each have sync and async forms, returning typed results (TTSResult, TranscriptionResult). The async variants are the ones an agent like Lyra calls.
The pipeline
Input flows through four stages before audio comes out. The translator is the load-bearing one — it is what lets a single universal script work everywhere without manual edits.
- Parse — read the Markdown frontmatter and inline directives.
- Config — backfill missing values from
voicecli.tomldefaults. - Translate — apply the engine capability matrix; adapt the script to the chosen backend.
- Synthesise — run the engine, write the WAV/MP3 to
voices_out/.
Cross-host over NATS
The GPU model and the caller need not be the same machine. With --via-nats, synthesis is routed to a remote TTS satellite over NATS — the model loads once on a GPU server, and a non-GPU laptop or workstation requests audio without loading anything locally. dictate nats is the mirror for transcription.
That is how voiceCLI plugs into roxabi-factory: it registers as a voice worker on the message bus, so any agent in the factory can speak or listen by publishing a request.
Run it
Requirements: Python 3.11–3.12, a CUDA GPU, and the uv package manager. Engine dependencies are opt-in, so you install only what you use.
uv sync --extra all # TTS + STT + NATS satellite
uv sync --extra tts # synthesis only (Qwen3, Chatterbox)
uv sync --extra stt # transcription only (Faster Whisper)
uv sync --extra nats # satellite / mock E2E — no heavy ML depsRead it from the source — engines, translator, and the NATS satellite are all in the open.
- The repo · github.com/Roxabi/voiceCLI →