pi-say

Spoken output for pi: a say tool that speaks short sentences through local TTS (Kokoro/Piper HTTP server, macOS say, or espeak-ng).

Packages

Package details

extension

Install pi-say from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-say
Package
pi-say
Version
1.1.1
Published
Sep 10, 2026
Downloads
251/mo · 251/wk
Author
matifema
License
MIT
Types
extension
Size
29 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-say

Spoken output for pi: a say tool that turns short sentences into speech.

Give pi a voice. The model calls say for acks before slow work and for the final result:

"Checking the logs now." … "Found three failed requests."

Google Cloud TTS is used when credentials are available, with local fallback (Kokoro/Piper server, macOS say, or espeak-ng) so speech keeps working offline.

Install

pi install npm:pi-say
# or from git
pi install git:github.com/matifema/pi-say
# or try without installing
pi -e npm:pi-say

Restart pi (or start a new session) after installing.

Google Cloud TTS

Provide credentials in one of these ways:

  • API key: set PI_SAY_GOOGLE_API_KEY (or VOICECTL_GOOGLE_API_KEY, or GOOGLE_API_KEY)
  • Service account JSON: set GOOGLE_APPLICATION_CREDENTIALS, or drop the file at ~/.config/pi-say/google-sa.json (voicectl's ~/.config/voicectl/google-sa.json is also picked up)

The Cloud Text-to-Speech API must be enabled on the project. Without credentials, pi-say silently falls back to the local engines below.

Voice

Change the voice from pi in two ways:

  • Ask pi in plain language — the model calls say_voice for you
  • Type /voice <name> in the pi prompt (/voice shows the current settings, /voice list lists Google voices)

Examples:

/voice en-US-Chirp3-HD-Aoede
/voice en-US-Journey-O
/voice local
/voice speed 1.15

Settings persist in ~/.config/pi-say/config.json:

{
  "engine": "auto",
  "voice": "en-US-Chirp3-HD-Charon",
  "speed": 1.0
}

engine is one of auto (Google, then local, then espeak), google, local, or espeak.

Local fallback

auto mode tries these in order:

  1. Google Cloud TTS — when credentials are configured
  2. Local HTTP TTS — any server exposing POST /tts with { text, voice, speed } returning audio (Kokoro, Piper, voicectl, …); default http://127.0.0.1:8181
  3. macOS say — built in
  4. espeak-ng / espeak — install with your package manager

Playback uses a voicectl-style HUD unix socket when present, otherwise pw-play, paplay, aplay, or ffplay (afplay on macOS).

Environment variables

Everything is optional; values in ~/.config/pi-say/config.json (written by /voice and say_voice) take precedence. VOICECTL_* aliases remain supported for compatibility with voicectl.

Variable Default Description
PI_SAY_GOOGLE_API_KEY — Google Cloud TTS API key.
PI_SAY_GOOGLE_SA / GOOGLE_APPLICATION_CREDENTIALS auto-discovered Service account JSON path.
PI_SAY_ENGINE auto auto, google, local, or espeak.
PI_SAY_VOICE en-US-Chirp3-HD-Charon Voice name.
PI_SAY_SPEED 1.0 Speaking rate.
PI_SAY_TTS_URL http://127.0.0.1:8181 Local TTS server. Set to off to skip it.
PI_SAY_HUD_SOCKET $XDG_RUNTIME_DIR/voicectl.sock HUD socket that accepts {"cmd":"speak","file":…,"interrupt":…}.
PI_SAY_PLAYER auto Force a player command, e.g. aplay.
PI_SAY_TIMING_LOG $XDG_RUNTIME_DIR/pi-say-timing.jsonl JSONL latency log; failures are silent.

How it works

  1. Text is clipped to twelve words.
  2. Synthesis: Google Cloud TTS → local HTTP TTS → macOS say → espeak-ng.
  3. Playback: HUD socket → pw-play / paplay / aplay / ffplay (afplay on macOS).

Generated WAVs are cached under ~/.cache/pi-say/.

License

MIT