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