VoiceRouter

Author: Alessandro Valenti

VoiceRouter is a local-first Python framework that turns voice/audio messages into executable Python actions.

Pipeline:

audio → transcription → intent detection → parameter extraction → function routing

No paid APIs. Local by default.

Install

If your system Python is externally-managed (PEP 668), use a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -U pip

Base (interfaces only):

pip install -e .

Local STT + embeddings intent detection:

pip install -e ".[local,cli]"

Microphone live capture (optional):

pip install -e ".[audio]"

HTTP + WebSocket streaming server (optional):

pip install -e ".[server]"

If you want CPU-only PyTorch wheels (recommended for local-first CPU setups), install PyTorch from the CPU index first, then install VoiceRouter:

pip install --index-url https://download.pytorch.org/whl/cpu torch
pip install -e ".[local,cli]"

Optional NLP entities (spaCy):

pip install -e ".[nlp]"
python -m spacy download en_core_web_sm

Optional Ollama fallback:

pip install -e ".[ollama]"

Optional YAML intent config support:

pip install -e ".[yaml]"

Quickstart

Create a router, register intents, and route an audio file:

from voicerouter import VoiceRouter

router = VoiceRouter()


@router.intent(
    "create_ticket",
    examples=["open a ticket", "server is down", "I have a problem"],
)
def create_ticket(ctx):
    return {"status": "created", "params": ctx.params}


result = router.route("examples/server_down_en.wav")
print(result)

The first run may download open models from Hugging Face (e.g. the MiniLM embedding model). No paid APIs are used.

Return format:

{
  "transcript": "...",
  "intent": "...",
  "confidence": 0.0,
  "params": {},
  "used_llm": false,
  "action_result": {}
}

CLI

voicerouter intents
voicerouter route path/to/audio.wav
voicerouter listen
voicerouter serve --host 127.0.0.1 --port 8000

listen is best-effort and depends on optional local audio tooling (e.g. sounddevice, numpy, scipy).

Streaming (HTTP / WebSocket)

Start the server:

voicerouter serve --host 127.0.0.1 --port 8000

Or run the example server (lets you customize intents in code):

.venv/bin/python examples/server_runner.py --host 127.0.0.1 --port 8000

Endpoints:

• GET /health → {"status":"ok"}
• GET /intents → {"intents":[...]}
• POST /route (multipart upload: file=@audio.wav) → routing result JSON
• POST /route/bytes (raw body bytes; default assumes wav) → routing result JSON
• WS /ws/route (send binary audio chunks, then send text "end") → result JSON

HTTP Upload (curl)

curl -sS -X POST "http://127.0.0.1:8000/route" \
  -F "file=@examples/server_down_en.wav"

HTTP Upload (Python)

pip install httpx
.venv/bin/python examples/http_upload_client.py examples/server_down_en.wav

WebSocket Audio Stream (Python)

pip install websockets
.venv/bin/python examples/ws_audio_stream_client.py examples/server_down_en.wav

Example Script

Run the included example:

.venv/bin/python examples/basic_usage.py

Or pass your own audio file:

.venv/bin/python examples/basic_usage.py /path/to/audio.wav

Microphone Live Example

pip install -e ".[local,audio]"
.venv/bin/python examples/microphone_live.py --seconds 5

Design

• Transcription: faster-whisper backend (CPU-friendly int8 by default)
• Intent detection: sentence-transformers embeddings similarity against examples
• Parameter extraction: regex rules by default, optional spaCy entity extraction
• Routing: decorator-based handlers with a typed context object
• Optional fallback: local Ollama JSON intent+params when confidence is low

Extensibility

All major components are pluggable:

• Custom STT engines
• Custom intent detectors
• Custom parameter extractors
• Optional LLM fallback client

See voicerouter/router.py for the interfaces.

License

MIT