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
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://[email protected]/earendil-works/pi-voice
Usage
The extension registers:
- a configurable terminal shortcut (
Ctrl+Alt+Zby default) to start and stop recording; /voice, which does the same as the shortcut. While recording,Spacealso stops and transcribes, andEscapediscards;- a
transcribe_filetool that the agent can use to transcribe local audio or video files; /voice-settingsfor preferred languages, model, transcription language, microphone, and shortcut settings.
/transcribe remains available as a compatibility alias for /voice-settings.
Upgrading from pi-transcribe
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
File transcription and FFmpeg
The agent can call transcribe_file for local audio or video files. Decoded audio is limited to 512 MiB (about 2.3 hours). 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.
Developing & Building Pi Voice
To develop or run it from a checkout:
git clone [email protected]: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