Transcribe audio (local, free, Metal-accelerated)

Automatic pipeline (watch folder)

There is also a fully automated path, for when you just want to drop a file somewhere and get an email back — no need to invoke this skill manually for those files.

• Root folder: ~/Documents/Transcribe Inbox/ (override with TRANSCRIBE_INBOX_DIR)
  • inbox/ — drop audio/video files here
  • processing/ — transient, in-flight (don't touch)
  • processed/ — done: audio file + its .txt transcript, side by side
  • failed/ — errored: audio file + a .err log explaining why
• Supported extensions: .m4a .mp3 .wav .mp4 .mov .aac .flac .ogg (case-insensitive)
• A LaunchAgent (label com.example.transcribe-watch — rename to your own reverse-DNS identifier, e.g. com.<yourname>.transcribe-watch; ~/Library/LaunchAgents/com.example.transcribe-watch.plist) watches inbox/ and runs ~/.claude/skills/transcribe-audio/scripts/watch_and_transcribe.sh on any change. That script: waits for the file's size to stabilize (skips files still mid-copy), moves it into processing/, runs ffmpeg + whisper-cli directly (same steps as the manual flow below), then moves the result into processed/ (or failed/ on error) and shells out to claude -p once to send an email alert via the Gmail MCP connector to whatever address is set in NOTIFY_EMAIL (see Setup below) — notification-only (file paths, not the transcript text) on success; failure emails include the error log.
• Logs: ~/.claude/skills/transcribe-audio/logs/watch.{out,err}.log
• Lock: ~/.claude/skills/transcribe-audio/state/watch.lock (a directory; serializes overlapping launchd triggers — safe to rmdir if a run ever gets stuck and the log confirms nothing is actually running)
• To pause/resume the watcher:

  launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.example.transcribe-watch.plist   # pause
  launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.transcribe-watch.plist  # resume

Setup

Before enabling the watcher, set your own values:

• NOTIFY_EMAIL — the address success/failure alerts get sent to. Set this as an env var, or edit it directly in watch_and_transcribe.sh.
• Rename the LaunchAgent label and plist filename from com.example.* to your own reverse-DNS identifier, and update the Label key inside the plist to match.
• Requires the Gmail MCP connector (or swap in whatever mail-sending tool you use) to be configured for the account you want alerts sent from/to.

Manual, one-off transcription

Runs Whisper locally via whisper.cpp (Homebrew formula whisper-cpp, binary whisper-cli), which uses Metal GPU acceleration on Apple Silicon. Much faster than the plain openai-whisper Python package on Mac hardware. No network upload of the audio — everything happens on your own machine.

Steps

1. Check dependencies (do this every time, cheap):

   command -v ffmpeg >/dev/null || echo "MISSING: ffmpeg"
   command -v whisper-cli >/dev/null || echo "MISSING: whisper-cli"
   ls ~/whisper-models/ggml-medium.bin >/dev/null 2>&1 || echo "MISSING: model weights"

   • If ffmpeg is missing: brew install ffmpeg
   • If whisper-cli is missing: brew install whisper-cpp
   • If model weights are missing, download to a fixed cache dir:

     mkdir -p ~/whisper-models
     curl -L -o ~/whisper-models/ggml-medium.bin \
       https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin

     (Use ggml-small.bin for a faster/lower-accuracy model, or ggml-large-v3.bin for max accuracy — swap the URL filename accordingly.)
2. Confirm the input file path with the user if not already given. Verify it exists before running anything.
3. Convert to 16kHz mono WAV. whisper.cpp requires this input format — most source files (m4a, mp3, etc.) need conversion first:

   ffmpeg -y -i "/path/to/input.m4a" -ar 16000 -ac 1 -c:a pcm_s16le "/path/to/input.wav"

4. Run the transcription. Output goes next to the source file:

   whisper-cli -m ~/whisper-models/ggml-medium.bin -f "/path/to/input.wav" \
     -otxt -of "/path/to/input"

   • -otxt writes plain text (.txt); use -osrt or -ovtt for subtitle formats if the user wants timestamps.
   • For long or sensitive files, run this in the background and check back — it can still take several minutes even with Metal acceleration.
   • Long-running: run in the background (background shell / run_in_background) rather than blocking, and report back when it completes.
5. Report the output file path(s) back to the user rather than dumping the full transcript inline, unless it's short or they ask to see it directly.

Notes

• Model weights are cached in ~/whisper-models/ (fixed path, not ~/.cache/whisper — that's the old openai-whisper cache location).
• First run needs brew install whisper-cpp (compiles/installs several binaries, can take a few minutes) plus the one-time model download (~1.5GB for medium). After that, transcription itself is fast — often close to or faster than realtime on an M-series Mac thanks to Metal.
• The intermediate WAV file is not cleaned up automatically; leave it unless you want to delete it (may be large for long recordings).
• Never upload the audio to a third-party API unless you explicitly want that route instead of the local one.