pi-voice README

The project's README from github.com/earendil-works/pi-voice. As one markdown file: README.md.

pi-transcribe

Local speech-to-text dictation for Pi.

Install

Install directly from GitHub:

pi install ssh://[email protected]/earendil-works/pi-transcribe

After the first npm release, it can also be installed with:

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

Usage

The extension registers:

To develop or run it from a checkout:

npm install --ignore-scripts
pi -e /absolute/path/to/pi-transcribe

While iterating on setup, enable the debug-only onboarding command when starting Pi:

PI_TRANSCRIBE_DEBUG=1 pi -e /absolute/path/to/pi-transcribe

Then run /transcribe-onboarding to replay the complete onboarding flow. The command is not registered unless PI_TRANSCRIBE_DEBUG=1. Canceling before selecting a model leaves the current configuration unchanged; model selections are applied immediately.

Press the shortcut while Pi has focus, speak, then press it again. A live level meter appears above the editor while recording. Esc cancels. Audio is transcribed locally and inserted at the editor cursor. Streaming-capable models process roughly 500 ms audio chunks while recording; other models use the complete recording after it stops. The shortcut is a Pi terminal binding, not a global OS hotkey.

File transcription and FFmpeg

The agent can call transcribe_file for local audio or video files. Transcription jobs share one loaded model; queued files reuse it, while microphone dictation runs before waiting file jobs after any active job finishes. To bound memory use, at most two file operations are admitted at once, only one FFmpeg decoder runs at a time, and decoded audio is limited to 128 MiB (about 35 minutes). File decoding requires the ffmpeg executable; microphone dictation does not. Install FFmpeg with your system package manager:

# 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-transcribe at it before starting Pi:

export PI_TRANSCRIBE_FFMPEG_PATH=/path/to/ffmpeg

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 /transcribe once in the interactive TUI to choose and, after confirmation, download a local model.

pi-voice (earendil-works/pi-voice)

Searching Database…

301 ·GitHub
Pi-voice
What is this?A speech-to-text extension for the Pi coding agent: you hit a shortcut, speak, and the transcript is inserted at your editor cursor. Everything is transcribed locally on your machine.
Is this a separate app, or does it plug into something?It plugs into Pi as an extension, not a standalone app. It adds a recording shortcut, a /transcribe command for settings, and a transcribefile tool the agent can call on local audio or video files.
How do I set it up?Install it directly from GitHub (an npm release is planned), then run /transcribe once in Pi's interactive TUI to pick a model and download it after your confirmation.
What do I need installed besides the extension itself?Node.js 22 or newer. FFmpeg is only needed for transcribing audio and video files — microphone dictation works without it; if FFmpeg sits outside PATH, you can point pi-transcribe at it before starting Pi.
Can I start recording from any app on my system?No — the shortcut is a Pi terminal binding, not a global OS hotkey, so recording only starts while Pi has focus.
Does my voice leave my machine?No: audio is transcribed locally with a model you downloaded after confirming in the TUI. The only network step is that one-time model download.
Can the agent transcribe audio files by itself?Yes, through its transcribefile tool. Jobs share one loaded model, mic dictation is prioritized after any active job finishes, and at most two file jobs run at once with a single FFmpeg decoder and a 128 MiB (about 35 minutes) decode cap.
Do all models transcribe while you are still speaking?No — streaming-capable models process roughly 500 ms chunks during recording, while other models transcribe the complete recording only after you stop.
Is there a way to replay the setup flow if something goes wrong?Yes, but it is debug-only: start Pi with PITRANSCRIBEDEBUG=1 and run /transcribe-onboarding. Canceling before selecting a model leaves your current configuration unchanged.
What are similar projects?DeepSpeech, lipflow, jot-gemini-transcribe-macOS, yapsnap, omarchy-meeting-recorder, murmur-youtube, openless, sherpa-onnx
Which topics is it in?dictation, pi-coding-agent, asr, on-device, transcription, voice, speech-to-text, speech-recognition, ffmpeg, audio, local-first, coding-agent
Creator
earendil-works
Size
1.5 MB
Stars
301
Updated
CommitOct 16
Age
2mo
Commits · 90 Days