pi-vo

Voice-over summaries for the pi coding agent.

pi-vo speaks short status narration about what pi is doing, so you can follow progress without watching the terminal constantly.

It is intentionally not a screen reader and does not read the model response verbatim. It speaks compact summaries such as:

• “Starting on your request.”
• “I'm reading project files.”
• “I'm editing package and README and running tests.”
• “The command failed; checking what went wrong.”
• “Done — updated two files, ran tests.”

Current status

Working MVP implemented:

• pi extension package scaffold
• /vo command suite
• config at ~/.config/pi-vo.json
• event-based deterministic summaries
• OpenAI-compatible TTS provider
• local piper provider support
• system TTS fallback (say, spd-say, espeak, termux-tts-speak)
• sequential playback queue
• playback discovery (mpv, ffplay, afplay, paplay, aplay)
• mute/stop/dedupe/debounce
• shutdown cleanup

Install / test locally

From this checkout:

pi -e /home/nikita/dev/pi-vo

Or install as a local pi package:

pi install /home/nikita/dev/pi-vo

Once published:

pi install npm:pi-vo

Commands

Command	Purpose
/vo	Show status and diagnostics
/vo help	Show help
/vo on / /vo off	Enable or disable voice-over
/vo test [text]	Speak a test phrase
/vo stop	Stop current playback and clear queued speech
/vo mute [seconds]	Temporarily mute narration, or mute indefinitely when no seconds are given
/vo unmute	Unmute
/vo provider <auto|openai|piper|system>	Select TTS provider
/vo voice <name>	Select voice
/vo model <name>	Select OpenAI-compatible TTS model
/vo config	Show redacted effective configuration
/vo summary minimal|normal|verbose	Tune verbosity

Default OpenAI-compatible TTS

Set:

export OPENAI_API_KEY=...

Defaults:

• provider: auto → OpenAI first when OPENAI_API_KEY exists
• model: gpt-4o-mini-tts
• voice: alloy
• base URL: https://api.openai.com/v1
• max utterance length: 180 characters

If you use an OpenAI-compatible endpoint:

export OPENAI_BASE_URL=https://your-provider.example/v1

Local providers

Piper

Install piper, then configure a model path:

export PI_VO_PROVIDER=piper
export PI_VO_PIPER_MODEL=/path/to/voice.onnx

or write piperModelPath to ~/.config/pi-vo.json.

System fallback

provider: auto also tries available system TTS commands:

• termux-tts-speak
• say
• spd-say
• espeak

System fallback speaks directly and does not require a separate audio player.

Playback

For OpenAI and Piper audio files, install at least one player:

# Recommended
mpv
# or
ffplay
# or platform-specific
afplay / paplay / aplay

Override with:

export PI_VO_PLAYER='mpv --no-terminal --really-quiet'
# or include the file placeholder explicitly
export PI_VO_PLAYER='my-player --file {file}'

Config

Config path:

~/.config/pi-vo.json

Effective config defaults:

{
  "enabled": true,
  "provider": "auto",
  "model": "gpt-4o-mini-tts",
  "voice": "alloy",
  "speed": 1,
  "summaryLevel": "normal",
  "maxChars": 180,
  "minIntervalMs": 2500,
  "toolDebounceMs": 1200,
  "speakAgentStart": true,
  "speakToolProgress": true,
  "speakErrors": true,
  "speakFinal": true,
  "modes": ["tui"],
  "openaiBaseUrl": "https://api.openai.com/v1",
  "maxQueueLength": 3
}

Environment overrides:

Env var	Meaning
PI_VO_ENABLED=0|1	Force enable/disable
PI_VO_PROVIDER=auto|openai|piper|system	Provider choice
PI_VO_VOICE=<voice>	Voice name
PI_VO_MODEL=<model>	TTS model
PI_VO_PLAYER=<cmd>	Playback command
PI_VO_FORCE=1	Allow non-TUI modes
PI_VO_PIPER_MODEL=<path>	Piper model path
OPENAI_API_KEY	OpenAI-compatible TTS API key
OPENAI_BASE_URL	OpenAI-compatible base URL

Privacy model

pi-vo only sends the short generated narration string to the TTS provider.

It does not send:

• full user prompts
• tool output
• diffs
• raw bash command lines with possible secrets
• full assistant responses

Summaries are generated locally from event metadata and sanitized before speech.

Development

cd /home/nikita/dev/pi-vo
npm install
npx tsc --noEmit

Package shape follows pi-idea: package.json declares pi.extensions: ["./extensions"].

Detailed design notes are in docs/IMPLEMENTATION_PLAN.md.