digimata/quill

quill – Local macOS meeting recorder & transcriber

What it is – A single‑binary Swift app that lives in the macOS menu bar. With one click it records both your microphone and everything the computer plays, saves the two tracks as separate .caf files, and runs an on‑device speech‑to‑text model to produce a speaker‑tagged transcript. No data leaves the machine.

Key features

• One‑click start/stop from a menu‑bar icon.
• Two audio tracks (mic + system) so the transcription model works on clean, single‑source audio and you get a natural me vs. them diarisation without a separate speaker‑ID model.
• Fully local transcription using the Parakeet TDT 0.6B v2 Core ML model (≈20 s of compute per hour on Apple Silicon). A WhisperKit fallback is planned.
• Automatic queuing: each recording is transcribed in order; unfinished jobs resume on the next launch.
• Configurable output directory, optional transcription, optional mic echo‑cancellation, and a hook (on_stop) that runs a shell command after a session finishes.
• Simple CLI for launching the daemon, changing the recordings root, checking health (quill doctor), and installing/uninstalling a launch‑at‑login agent.

How it works

1. Recording – Uses macOS Core Audio process taps (AudioHardwareCreateProcessTap) to capture all system audio, and AVAudioEngine for the microphone. Audio is streamed directly to AAC‑encoded CAF files, which can be read even if the process crashes.
2. Transcription – Each track is fed to the Parakeet model via the FluidAudio Core ML wrapper. The two transcripts are time‑shifted according to the meta.json offsets and merged into a single, timestamped, speaker‑tagged transcript (transcript.json and a rendered transcript.md).
3. Queue & persistence – The presence of a meta.json without a transcript.json marks a pending job; the filesystem itself acts as the queue, so new recordings can start while previous ones are still being transcribed.

Installation & usage

# Build the Swift binary
cd quill
swift build -c release
sudo cp .build/release/quill /usr/local/bin/quill

# Optional: run at login
quill install --launch-at-login

• Run quill (or the LaunchAgent) to start the menu‑bar daemon.
• Click the feather icon → Start recording, click again → Stop.
• Transcription runs automatically; a macOS notification signals completion.
• Recordings are stored under ~/Recordings/<yyyy.MM.dd-HHmm>/ with:
  • mic.caf (your voice)
  • system.caf (other participants / system audio)
  • meta.json (timestamps)
  • transcript.json & transcript.md (machine‑readable and readable versions)
  • transcribe.log (progress / errors)

Configuration (optional ~/.config/quill/config.json)

{
  "recordings_dir": "~/Recordings",
  "transcription": {"enabled": true, "engine": "parakeet"},
  "on_stop": "my-hook"
}

• recordings_dir overrides the default location.
• Set transcription.enabled to false to only capture audio.
• mic_voice_processing toggles Apple’s echo‑cancellation (useful when recording via speakers).
• on_stop runs a shell command with the session folder as its argument after the transcript is written.

Limitations / Gotchas

• The system‑audio tap records everything the Mac plays; background music or notifications will appear in the system.caf track.
• Requires macOS 15+ (process‑tap API) and works best on Apple Silicon for reasonable transcription speed.
• Current model is English‑only; other languages will be supported once the Whisper fallback is added.
• Permissions for “Screen & System Audio Recording” must be granted, otherwise recordings are silent.

Tech stack

• Swift (Swift Package Manager single executable)
• Core Audio process tap for system audio capture
• AVAudioEngine & AVAudioFile for mic capture and streaming AAC encode
• FluidAudio / Parakeet Core ML model for on‑device transcription
• NSStatusItem for the menu‑bar UI

---

All details are taken directly from the repository’s README.