hold space to record · release to save · b to browse recordings · ctrl+c to quit
saves timestamped files (2026-04-07_14-30-22.wav) to your current directory, or wherever you point it.
transcribes each recording automatically in the background (if faster-whisper is installed).
pipx install .with transcription support:
pipx install '.[transcribe]'buddy # wav to current dir, picks mic on first run
buddy -o ~/recordings # save to a specific folder
buddy -f mp3 # save as mp3 (also: flac, ogg)
buddy -f ogg -o ~/voice # combine flags
buddy --pick # re-select microphone
buddy --list # list available input devices
buddy --model small # use a larger whisper model (tiny/base/small/medium)
buddy --hook "cp {file} ~/dropbox/" # run a command after each save
buddy --hook "whisper {file}" # transcribe with an external tool insteadpress b to open the recording browser:
- UP / DOWN — navigate the list (stops playback)
- p — play or stop the selected file
- q — back to recording
transcripts (if available) are shown below each filename in gray.
after each recording, buddy queues it for local transcription via faster-whisper.
a spinner shows progress; .txt files are saved next to the audio.
if a transcription is in progress when you press Ctrl+C, buddy warns you. press Ctrl+C again within 2 seconds to force-quit.
--hook "cmd {file}" — buddy runs this after each successful save.
{file} is replaced with the full path to the new recording. runs in the background.
buddy --hook "say 'saved'"
buddy --hook "rsync {file} user@host:~/voice/"mic choice is remembered between runs (~/.config/buddy/config.json).
- python 3.9+
- a microphone
libportaudio—brew install portaudioon mac,apt install libportaudio2on linux, nothing on windowsfaster-whisper(optional) — for local transcription:pipx inject buddy-recorder faster-whisper
macos: grant accessibility permission on first run — system settings → privacy → accessibility
pipx uninstall buddy-recorder