quill README

The project's README from github.com/humanitas-labs/quill. As one markdown file: README.md.

quill

A minimal, fully local macOS meeting recorder + transcriber. One menu-bar click records your mic and all system audio as two separate tracks; when you stop, quill transcribes both on-device and writes a speaker-tagged transcript. Nothing ever leaves the machine.

Named for the feather. Sibling of parrot, same skeleton: single Swift binary, menu-bar tray, no app bundle.

Install

cd quill
swift build -c release
sudo cp .build/release/quill /usr/local/bin/quill
quill install --launch-at-login   # optional — runs in the background on login

Requires: macOS 15+ (Core Audio process taps for system audio — no virtual device, no kernel extension). Apple Silicon recommended for transcription speed.

How to use

  1. Run it (quill in a terminal, or the LaunchAgent).
  2. Click the feather in the menu bar → Start recording. First use prompts for microphone and System Audio Recording permissions. While recording, the icon turns red with a running elapsed counter, and macOS shows the purple recording indicator.
  3. Click → Stop recording when the meeting ends. Transcription starts automatically (the menu shows progress); a notification fires when the transcript is ready.

Each session lands in ~/Recordings/<yyyy.MM.dd-HHmm>/:

File Contents
mic.caf your side (default input device, AAC)
system.caf everything the Mac played — the other side of the call (AAC)
meta.json start/end timestamps, duration, per-track start offsets
transcript.json canonical transcript — engine provenance + timed, speaker-tagged segments
transcript.md the same transcript rendered for reading
transcribe.log transcription progress/errors for this session

Two tracks on purpose: speech models do better on clean single-source audio, and mic-vs-system is free two-party diarization — me vs them with no speaker-identification model. CAF on purpose: unlike m4a, it needs no finalization pass — if the process dies mid-meeting, everything already written is still readable.

Transcription

Built in, on-device, automatic. The default engine is Parakeet TDT 0.6B v2 (English) via FluidAudio's Core ML port — roughly 20 seconds per hour of audio on Apple Silicon. Models (~600 MB) download once on first transcription; quill doctor tells you whether they're already cached so you're never downloading after an important meeting.

Each track is transcribed separately, shifted by its start offset so both share one clock, and merged by timestamp. Jobs run in a serial queue — you can start a new recording while the last one transcribes. Unfinished jobs resume on next launch (the filesystem is the queue: a session with meta.json but no transcript.json is pending). Failures append to the session's transcribe.log and never block later jobs.

The engine sits behind a small protocol; a Whisper engine (WhisperKit large-v3-turbo) is planned as the fallback / re-transcription option.

Config

Optional, at ~/.config/quill/config.json:

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

CLI

quill                        # run the menu-bar daemon (^C to quit)
quill run --out <dir>        # custom recordings root (default ~/Recordings)
quill doctor                 # check permissions, recordings folder, models
quill install --launch-at-login
quill install --uninstall

Stack

Gotchas

quill (humanitas-labs/quill)

Searching Database…

3.9K ·GitHub
这是什么?quill 是一个极简、完全本地运行的 macOS 会议录音和转录工具。点击一下菜单栏图标,它就能录制你的麦克风和全部系统声音;停止录音后,它会在本机上把两条音轨都转录成带说话人标注的文字记录。
这是菜单栏应用还是命令行工具?它是一个单独的 Swift 可执行文件,没有应用包,全部界面就是菜单栏上的托盘图标。你可以从终端或通过 LaunchAgent 启动它,然后点击羽毛图标来操作。
我该怎么录制第一场会议?在终端中运行 quill,或通过 LaunchAgent 启动,点击羽毛图标并选择 Start recording(开始录音)——首次使用时会请求麦克风和系统音频录制权限。会议结束后停止录音;转录会自动开始,文字记录准备好后会弹出通知。
我的 Mac 需要什么条件才能运行它?需要 macOS 15 或更新版本,因为系统声音是通过 Core Audio 进程抽头(process taps)捕获的——不需要虚拟设备或内核扩展。推荐使用 Apple Silicon 芯片,另外首次使用时会一次性下载约 600 MB 的转录模型;用 quill doctor 命令可以查看这些模型是否已经缓存。
在正式会议中使用之前,有什么需要注意的地方?系统声音的录制是全局的:它会录下 Mac 播放的所有声音,所以开会期间不要运行 Spotify 或其他会发出声音的应用。如果录出来的音频没有声音,通常是因为屏幕与系统音频录制权限没有开启。
我的录音会不会离开我的电脑?不会——录音、存储和转录全部在本机完成。唯一的联网下载就是首次获取转录模型。
一次录音会留下哪些文件?每次录音都保存在 ~/Recordings 目录下:mic.caf、system.caf、meta.json、transcript.json(带时间戳和说话人标注的分段)、供阅读用的 transcript.md,以及 transcribe.log。音频采用 CAF 格式,不需要收尾写入步骤——即使进程在会议中途崩溃,已经写好的部分依然可以正常读取。
为什么要把麦克风和系统声音录成两条单独的音轨?语音模型在干净的单源音频上效果更好,而且麦克风对比系统声音天然就是免费的双人说话人分离——不用任何说话人识别模型就能区分“我”和“对方”。每条音轨分别转录,再按时间戳合并到同一条时间线上。
转录速度有多快?转录进行时我还能继续录音吗?在 Apple Silicon 上使用默认的 Parakeet 引擎,大约每小时音频只需 20 秒。转录任务按串行队列依次执行,所以上一个录音还在转录时你就可以开始新录音,未完成的任务会在下次启动时自动继续。
它支持英语以外的语言吗?暂时不支持——内置的 Parakeet 引擎只支持英语。后续计划加入 WhisperKit large-v3-turbo 引擎作为备用和重新转录的选项,其他语言预计会随它一起提供。
Size
0.2 MB
Stars
3.9K
Updated
CommitSep 27
Age
2mo
Commits · 90 Days