digimata/quill

quill – 本地 macOS 会议录音与转录工具

是什么 – 一个驻留在 macOS 菜单栏的单二进制 Swift 应用。只需点击一次，即可同时录制麦克风和计算机播放的所有音频，将两条音轨分别保存为独立的 .caf 文件，并使用本地语音识别模型生成带说话人标签的转录文本。所有数据均不会离开设备。

主要功能

• 通过菜单栏图标一键开始/停止录音。
• 两条音频轨道（麦克风 + 系统音频），使语音识别模型在干净的单一音源上运行，无需额外的说话人识别模型即可实现自然的 我 vs 他们 的说话人分离。
• 使用 Parakeet TDT 0.6B v2 Core ML 模型进行完全本地化转录（在 Apple Silicon 上每小时约需 20 秒计算）。计划添加 WhisperKit 作为回退方案。
• 自动排队：每个录音按顺序转录；未完成的任务在下次启动时自动恢复。
• 可配置输出目录、可选转录、可选麦克风回声消除，以及一个在会话结束后运行 shell 命令的钩子（on_stop）。
• 简洁的 CLI，用于启动守护进程、更改录音根目录、检查健康状态（quill doctor），以及安装/卸载开机自启代理。

工作原理

1. 录音 – 使用 macOS Core Audio 进程钩子（AudioHardwareCreateProcessTap）捕获所有系统音频，使用 AVAudioEngine 捕获麦克风音频。音频直接流式传输到 AAC 编码的 CAF 文件，即使进程崩溃也能读取。
2. 转录 – 每条音轨通过 FluidAudio Core ML 包装器输入到 Parakeet 模型。根据 meta.json 中的时间偏移对两条转录文本进行时间对齐，并合并为一个带时间戳和说话人标签的单一转录文本（transcript.json 和渲染后的 transcript.md）。
3. 队列与持久化 – 存在 meta.json 但无 transcript.json 表示任务待处理；文件系统本身充当队列，因此在前一个录音仍在转录时，可启动新的录音。

安装与使用

# 构建 Swift 二进制文件
cd quill
swift build -c release
sudo cp .build/release/quill /usr/local/bin/quill

# 可选：开机自启
quill install --launch-at-login

• 运行 quill（或 LaunchAgent）以启动菜单栏守护进程。
• 点击羽毛图标 → 开始录音，再次点击 → 停止。
• 转录自动运行；macOS 通知将提示完成。
• 录音保存在 ~/Recordings/<yyyy.MM.dd-HHmm>/ 目录下，包含：
  • mic.caf（你的声音）
  • system.caf（其他参与者 / 系统音频）
  • meta.json（时间戳）
  • transcript.json 与 transcript.md（机器可读与人类可读版本）
  • transcribe.log（进度 / 错误）

配置（可选 ~/.config/quill/config.json）

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

• recordings_dir 可覆盖默认路径。
• 将 transcription.enabled 设为 false 可仅录制音频。
• mic_voice_processing 可切换 Apple 的回声消除（在通过扬声器录音时有用）。
• on_stop 在转录完成后，以会话文件夹为参数运行 shell 命令。

限制 / 注意事项

• 系统音频钩子会记录 Mac 播放的所有内容；背景音乐或通知将出现在 system.caf 轨道中。
• 需要 macOS 15+（进程钩子 API），在 Apple Silicon 上运行可获得合理转录速度。
• 当前模型仅支持英语；一旦添加 Whisper 回退方案，将支持其他语言。
• 必须授予“屏幕与系统音频录制”权限，否则录音将无声。

技术栈

• Swift（Swift Package Manager 单一可执行文件）
• Core Audio 进程钩子：系统音频捕获
• AVAudioEngine 与 AVAudioFile：麦克风捕获与 AAC 编码流式传输
• FluidAudio / Parakeet Core ML 模型：本地转录
• NSStatusItem：菜单栏 UI

---

所有细节均直接取自仓库的 README。