Quill使用指南~/Recordings里的mic.caf、meta.json、transcript.md逐个文件讲明白【免费下载链接】quillUltra-minimalist macOS recording transcription.项目地址: https://gitcode.com/gh_mirrors/quill26/quillQuill 是一款完全本地化的 macOS 会议录音 语音转写工具它把麦克风你和系统声音对方录成两条独立音轨在设备上自动转写并生成带时间戳和me/them说话人标记的会议记录。所有数据都留在你自己的 Mac 上。这篇指南带你逐个看懂~/Recordings里生成的mic.caf、meta.json、transcript.md等文件。 录音存在哪里每次点击菜单栏羽毛图标开始录音Quill 就会在~/Recordings/下创建一个以时间戳命名的文件夹例如~/Recordings/2026.09.29-1430/命名格式为yyyy.MM.dd-HHmm年月日-时分撞名时自动追加-2、-3后缀。停录后转写自动开始完成后你会收到一条桌面通知。一个完整会话文件夹里通常有这些文件文件内容谁生成的mic.caf你的声音默认输入设备AAC 编码录音时实时写入system.cafMac 播放的一切声音——通话的另一方AAC 编码录音时实时写入mic-002.caf、system-002.caf…附加音频分段仅当录音中途需要恢复采集时出现录音时实时写入meta.json起止时间、时长、分段偏移、采集状态停止录音时原子写入transcript.json规范转写结果——引擎信息 带时间戳、说话人标记的段落转写完成时原子写入transcript.md同一份转写内容的人类可读版转写完成时原子写入transcribe.log本次会话的转写进度与错误日志转写过程中追加️ mic.caf 与 system.caf为什么是两条音轨分成两条轨是刻意为之有两个实际好处识别更准——语音模型对干净的单声源音频表现更好免费的说话人分离——mic轨天然就是mesystem轨天然就是them不需要任何说话人识别模型转写结果自动标记谁说了什么。为什么用 CAF 格式而不是常见的 m4a因为 CAF 写入时不需要收尾定稿步骤。即使录音中途进程崩溃已经写下的音频依然可读不会整段丢失。什么时候会出现mic-002.caf这样的文件macOS 的音频路由在长时间会议中并不稳定——连接/断开 AirPods、切换默认音频设备都可能让某条音轨悄悄停录。Quill 用 1 秒看门狗监控两条轨发现卡住就在当前路由上重开一段新文件mic-002.caf、mic-003.caf…已录好的分段绝不会被改写或覆盖。 所以如果你看到-002文件不必紧张说明中途有一次自动恢复转写时会按meta.json里的偏移量把各段拼回同一条时间轴中断造成的空隙会以时间戳跳变的形式保留在转写里。录音中菜单栏图标的颜色也是信号 红色 两轨健康 橙色◐ recovering 某轨正在恢复⚠ capture lost 恢复失败会话将被标记为incomplete。 meta.json会话的体检报告meta.json在停止录音时一次性原子写入结构定义见 SessionMeta.swift。当前为 schema v2长这样取自测试夹具的真实样例{ schema_version: 2, started: 2026-08-03T19:32:55Z, ended: 2026-08-03T20:09:35Z, duration_seconds: 2200, status: recovered, tracks: [ { kind: mic, speaker: me, status: recovered, segments: [ { file: mic.caf, start_offset_ms: 18, end_offset_ms: 1687869, frames_written: 81016832, sample_rate_hz: 48000, channels: 1 }, { file: mic-002.caf, start_offset_ms: 1691120, end_offset_ms: 2200014, frames_written: 24426720, sample_rate_hz: 48000, channels: 1 } ], interruptions: [ { detected_offset_ms: 1690869, recovered_offset_ms: 1691120, reason: callback_stalled, attempts: 1 } ], warnings: [] }, { kind: system, speaker: them, status: complete, segments: [ { file: system.caf, start_offset_ms: 0, end_offset_ms: 2200000, frames_written: 105600000, sample_rate_hz: 48000, channels: 2 } ], interruptions: [], warnings: [exact digital silence for 520s] } ] }关键字段一眼读懂started/ended/duration_seconds——会议起止ISO 8601仅用于展示与总时长status——整场会话的最终状态取各轨中最差的一个取值见下tracks[].speaker——memic 轨/themsystem 轨tracks[].segments[]——每个音频文件的start_offset_ms/end_offset_ms毫秒级会话时钟偏移、写入帧数、采样率、声道数tracks[].interruptions[]——每次中断的检出时刻、恢复时刻、原因和重试次数tracks[].warnings[]——非致命提醒例如exact digital silence for 520s系统轨全程数字静音可能只是当时没声音播放。三种状态complete / recovered / incomplete状态含义可用性complete从开始到停止没有检测到任何中断✅ 完整recovered出现过中断但已自动恢复缺口有界✅ 可用但不会被谎报为无中断incomplete采集无法恢复或停止时已失效⚠️ 尾部可能有缺口这套规则的定义在 docs/architecture.md 中有完整说明状态枚举定义见 CaptureHealth.swift。排查技巧如果停录后收到会话非 complete的通知直接打开该文件夹的meta.json看interruptions和status就能知道中断发生在哪一刻、恢复了没有。 transcript.md 与 transcript.json转写成果停止录音后 Quill 自动转写默认引擎Parakeet TDT 0.6B v2纯设备端 Core MLApple Silicon 上约每小时音频 20 秒。每段音频独立转写后按start_offset_ms平移到同一条会话时钟上再按时间戳合并。transcript.json是规范格式机器可读引擎/模型信息 created_at 段落数组每段含speaker、start_ms、end_ms、text结构定义在 TranscriptionCoordinator.swift。transcript.md是给人读的渲染版同一份数据的另一种呈现格式如下# 2026.09.29-1430 engine: parakeet (TDT 0.6B v2) capture: recovered **[00:03] me:** 喂能听到我吗 **[00:05] them:** 可以可以我们开始吧。 **[12:41] me:** 那这个方案我周五前给你初稿。渲染逻辑见 TranscriptionCoordinator.swift。注意两点capture: recovered这一行——仅当会话状态不是complete时出现让录音有缺口这件事在通知消失后依然肉眼可见时间戳是相对会话起点的秒数m:ss超 1 小时为h:mm:ss。如果中间发生过采集中断你会看到时间戳跳了一段——这正是中断留下的可见空隙而不会被悄悄抹平。关于文件系统即队列转写任务的排障全靠文件夹本身有meta.json但没有transcript.json 待转写。Quill 每次启动都会扫描~/Recordings把未完成的会话按文件夹名时间戳序从旧到新重新排入队列——即使上次转写中途崩溃或退出重新打开应用就会自动续上。单个会话转写失败只会把错误追加进它自己的transcribe.log绝不阻塞后面的任务。 快速上手与常用命令./scripts/build-macos # 构建 sudo ./scripts/install-macos # 安装到 /usr/local/bin见 scripts/install-macos quill # 启动菜单栏守护进程 quill doctor # 检查权限、录音目录、模型缓存 quill install --launch-at-login # 可选登录时后台自启可选配置放在~/.config/quill/config.json比如改录音目录、关闭转写transcription.enabled: false、或设置on_stop钩子在转写写完后自动跑你的命令摘要、归档、索引都行。完整说明见 macos/README.md。❓ 常见问题速查录音是静音的检查 系统设置 → 隐私与安全性 → 屏幕与系统音频录制 是否授权。转写支持中文吗默认 Parakeet v2 仅支持英文Whisper 引擎多语言在路线图上。想只看结论直接打开transcript.md想核对音频完整性看meta.json的status。 相关文件索引平台文档与文件表macos/README.md会话生命周期分轨、恢复、写 meta.jsonmacos/Sources/quill/RecordingSession.swift元数据契约v1/v2 兼容读取macos/Sources/quill/SessionMeta.swift转写队列与 transcript 渲染macos/Sources/quill/Transcription/TranscriptionCoordinator.swift跨平台共享契约说明docs/architecture.md菜单栏图标实现macos/Sources/quill/UI/MenuBarController.swift一句话总结mic.caf/system.caf是原始声音meta.json是完整性档案transcript.md是你最终要读的东西——三者放在同一个时间戳文件夹里构成了 Quill录音—体检—转写的完整闭环。【免费下载链接】quillUltra-minimalist macOS recording transcription.项目地址: https://gitcode.com/gh_mirrors/quill26/quill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
