Mac System-Audio Transcriber

Free, private transcription of anything playing on your Mac — webinars, calls, podcasts, videos. It records the sound coming out of your speakers and turns it into a clean text file. Everything runs locally; nothing is ever uploaded, there's no account, and it costs nothing. No Homebrew, no Python required. Runs on macOS 12 (Monterey) and newer, Intel or Apple Silicon.

⚠️ As-is, unsupported. A friendly wrapper around free, open-source tools, shared in case it helps. It works well, but it's a small side project — no warranty, no support promises. The scripts are short and plain; read them before you run them.

🤖 Built with Claude Code (Anthropic).

---

What it does

macOS won't let an app record its own audio output directly. This wires up a free virtual audio cable (BlackHole) so a recorder (ffmpeg) can capture system sound, then transcribes it locally with Whisper — shipped as a single self-contained file via Mozilla's whisperfile, so there's no model to manage and no toolchain to build. You get a clean, no-timestamp .txt transcript.

Who this is (and isn't) for

• For you if: you can run a setup script and double-click a file, and you'd rather spend 15 minutes than money.
• Not for you if: you never want to see a Terminal window. Then MacWhisper Pro (~$69 one-time) does the same job with a polished GUI and native system-audio capture — honestly worth it if your time is worth more than the setup. (MacWhisper needs macOS 13+; this repo works back to macOS 12.) This is the $0 path for people who'd rather DIY.

What gets installed

All free and open-source — no package manager needed; the setup script downloads them directly:

Tool	Role	License
BlackHole 2ch	virtual audio cable (lets the Mac hear itself)	GPL-3.0
ffmpeg (static binary)	records the audio	LGPL / GPL
whisperfile (Mozilla)	transcribes it, offline, in one file	Apache-2.0 / MIT

We don't own any of these. All credit goes to their authors — this repo is just the glue and a guide.

Setup (about 15 minutes, once)

1. Get the files. Clone the repo, or download the ZIP and unzip it:

   git clone https://github.com/pottsy17/mac-system-audio-transcriber.git

2. Run the installer. Right-click install.command → Open → Open. (macOS blocks unsigned scripts on first run; right-click → Open is how you approve it. CLI equivalent: chmod +x install.command && ./install.command.) It downloads everything above and may ask for your Mac password.
3. Restart your Mac — the audio driver activates after a reboot (or run sudo killall coreaudiod).
4. Create the "Webinar Capture" device (see Audio setup) so you can hear and record at the same time.

Already use Homebrew? The only piece it meaningfully simplifies here is the audio driver — you can run brew install --cask blackhole-2ch instead of the bundled .pkg. ffmpeg and the transcriber are self-contained single files, so the installer stays the simplest path for the rest (and works with no package manager at all, including on macOS 12).

Audio setup

This one-time step lets you listen to a webinar and capture it. In Audio MIDI Setup (⌘ Space → type it):

1. Click the + (bottom-left) → Create Multi-Output Device.
2. In the right-hand list, tick both your normal speakers/headphones and BlackHole 2ch.
3. Tick Drift Correction on the BlackHole 2ch row (keeps audio in sync).
4. Double-click the new device on the left and rename it Webinar Capture.

Recording (the everyday part)

1. Set sound output to Webinar Capture (System Settings → Sound → Output).
2. Double-click Record Webinar on your Desktop (the installer puts it there) — or run ./grab.sh some-name inside ~/webinar-transcribe.
3. Play the audio, then press q + Enter to stop.
4. The clean transcript lands in ~/webinar-transcribe/recordings/.
5. Switch output back to your speakers — the volume keys are disabled while Webinar Capture is selected.

Note for older macOS (Monterey)

macOS 12 ships zsh 5.8, which can't launch the whisperfile directly (you'll see exec format error). The included scripts already avoid this by running under /bin/sh. If you ever run the transcriber by hand on Monterey, wrap it: sh -c "./whisper.llamafile -f file.wav -nt".

Privacy

100% local. The model runs on your Mac's own CPU/GPU. No audio or text leaves the machine. No account, no API key, no fees.

Troubleshooting

• "BlackHole not found" — did you restart (setup step 3)? Is output set to Webinar Capture?
• Empty transcript — the recording was silent; confirm output was on Webinar Capture and audio was playing. If prompted, grant Terminal microphone access (System Settings → Privacy & Security → Microphone).
• exec format error (Monterey) — see the note above; run the transcriber via sh -c "...".
• Rough on names/jargon — grab a bigger model from Mozilla/whisperfile (e.g. whisper-medium.en.llamafile), drop it in ~/webinar-transcribe, and point the ./whisper.llamafile line in grab.sh at it.

License

MIT — see LICENSE. The bundled tools each keep their own licenses (listed above).