pi-simple-voice

Give your Pi agent a voice — streaming and verbatim.

pi-simple-voice is a text-to-speech package for the Pi coding agent. It speaks the assistant's output as it streams, sentence by sentence, with no summarization — you hear exactly what the agent writes. It runs a local HTTP server powered by Kokoro ONNX and exposes a /voice settings UI.

This is a fork of s1m0n38/pi-voice (MIT). See What's different below. Huge thanks to the upstream author — the Kokoro server, /voice TUI, and model management started there.

How it works: A small local server loads a single Kokoro ONNX model into memory and exposes a REST API for synthesis. The pi extension talks to it over HTTP — it never loads the model itself. The extension spawns the server on demand; the server self-exits after an idle timeout (default 15 min) and is re-spawned when next needed, so one model lives in RAM and is shared across all your pi sessions.

What's different from upstream

	upstream pi-voice	this fork
Speech text	LLM summarizes each response	verbatim — speaks what the agent writes
Timing	one utterance at agent_end	streaming, on sentence boundaries as tokens arrive
Reasoning	—	thinking/reasoning content is never voiced
Interrupt	agent_end (could cut the final sentence)	turn_start / abort (clean)
tts tool	agent can call it	removed — speech is a side-effect of output, not a tool
Server lifetime	started/stopped via CLI	extension-managed; self-exits when idle, re-spawned on demand
Runtime	@mariozechner/*	@earendil-works/*

Installation

pi install npm:pi-simple-voice

The extension auto-spawns the server and downloads the default q4 model (~291 MB) the first time speech is enabled. The pi-simple-voice CLI is also available for manual control.

Requires bun on PATH — the extension spawns the server under bun.

Usage

/voice command

Open the interactive settings UI inside Pi:

Setting	Controls	Keys
TTS	Enable/disable speech	← →
Voice	Speaker voice (with language/gender hints)	← →
Speed	Speech rate (0.5×–3.0×)	← →
Model	Quantization dtype	← → (loads on close)

Navigate with ↑ ↓, change a value with ← →, Enter plays a sample, s saves the current selection as the default, r resets, Esc closes. Toggle speech quickly with alt+v. The ♪ status bar shows live download/load progress (e.g. ♪ ↓ q4 25%). The Voice row appears once a model is loaded and its voices are fetched.

Settings persist in ~/.pi/voice/config.json.

Configuration

{
  "enabled": true,
  "voice": "af_heart",
  "speed": 1.0,
  "host": "127.0.0.1",
  "port": 8181,
  "dtype": "q4",
  "idleMs": 900000
}

idleMs is how long the server sits idle before self-exiting (default 15 min). There is no summarization model and no per-event prompt config — speech is always the assistant's verbatim output.

CLI Reference

pi-simple-voice server status                # show server status
pi-simple-voice server start                 # start server, load default model
pi-simple-voice server stop                  # stop server (exits the process)
pi-simple-voice server restart               # restart
pi-simple-voice model list                   # list dtypes + download status
pi-simple-voice model load <dtype>           # load (downloads if needed)
pi-simple-voice model unload                 # unload the active model
pi-simple-voice model download <dtype>       # download without loading
pi-simple-voice model remove <dtype>         # unload (if active) + delete cached files

Options: --host <host> --port <port> (defaults 127.0.0.1:8181).

Model dtypes

Dtype	Size	Quality	Notes
q4	~291 MB	Good	4-bit matmul — recommended default
q4f16	~147 MB	Good	4-bit matmul + fp16 weights
q8	~88 MB	Great	8-bit quantized — best quality/size ratio
fp16	~156 MB	Excellent	Half-precision floats
fp32	~310 MB	Best	Full-precision floats

Only one model is loaded at a time. Files are cached at ~/.pi/voice/cache/.

API

The server exposes HTTP endpoints at http://127.0.0.1:8181:

Method	Path	Description
GET	/health	Status, active + last dtype, model loaded, download/load progress
GET	/voices	Available voice names
GET	/models	All dtypes with download status
POST	/models/download	Download (+ optionally activate) a dtype
POST	/models/delete	Delete cached model files
POST	/models/activate	Load a downloaded model
POST	/models/unload	Unload model, free memory
POST	/tts	Synthesize text → WAV audio
POST	/shutdown	Graceful shutdown

Events

The extension emits voice:config on the pi event bus (pi.events) whenever a setting changes via /voice:

pi.events.on("voice:config", ({ enabled, voice, speed }) => {
  // update status bar, toggle features, etc.
});

License

MIT — same as upstream. Forked from s1m0n38/pi-voice.