Pi Voice

Local speech-to-text for Pi.

Press a keyboard shortcut, talk, and the resulting transcript will be put directly into your chat.

Install the npm package:

pi install npm:@earendil-works/pi-voice

If you prefer being on the development tip, you can install from GitHub:

pi install ssh://git@github.com/earendil-works/pi-voice

The extension registers:

• a configurable terminal shortcut (Ctrl+Alt+Z by default) to start and stop recording;
• /voice, which does the same as the shortcut. While recording, Space also stops and transcribes, and Escape discards;
• a transcribe_file tool that the agent can use to transcribe local audio or video files;
• /voice-settings for preferred languages, model, transcription language, microphone, and shortcut settings.

/transcribe remains available as a compatibility alias for /voice-settings.

It's recommended to install Pi Voice via NPM. If you have an older install of pi-transcribe uninstall it via:

pi remove git:github.com/earendil-works/pi-transcribe

If you installed it into a project with -l, run pi remove -l git:github.com/earendil-works/pi-transcribe from that project instead. Then install Pi Voice with:

pi install npm:@earendil-works/pi-voice

The agent can call transcribe_file for local audio or video files. Decoded audio is limited to 128 MiB (about 35 minutes). File decoding requires the ffmpeg executable. Install FFmpeg with your system package manager if you don't already have it installed

# macOS with Homebrew
brew install ffmpeg

# Debian or Ubuntu
sudo apt install ffmpeg

# Windows with winget
winget install Gyan.FFmpeg

If FFmpeg is installed outside PATH, point Pi Voice at it before starting Pi:

export PI_VOICE_FFMPEG_PATH=/path/to/ffmpeg

The legacy PI_TRANSCRIBE_FFMPEG_PATH variable remains supported when PI_VOICE_FFMPEG_PATH is not set.

When FFmpeg is unavailable, transcribe_file reports platform-specific guidance to the agent. The agent should ask before running a package-manager command. Model setup is still explicit: run /voice-settings once in the interactive TUI to choose and, after confirmation, download a local model.

To develop or run it from a checkout:

git clone git@github.com:earendil-works/pi-voice.git
cd pi-voice
npm install --ignore-scripts
pi -e .

If you want to be able to re-run onboarding you can enable the debug env var when starting Pi. This enables the /voice-onboarding command.

PI_VOICE_DEBUG=1 pi -e /absolute/path/to/pi-voice