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。