Quill 捕获自愈机制深剖1 秒看门狗、路由监听与分段重启如何救回断掉的录音【免费下载链接】quillUltra-minimalist macOS recording transcription.项目地址: https://gitcode.com/gh_mirrors/quill26/quillQuill 是一款极简的 macOS 本地会议录音转写工具它把麦克风与系统声音分成两条音轨录制并在本地转写成带说话人标记的纪要。但 macOS 的音频路由天生不稳定——一次蓝牙耳机切换就可能让录音悄悄断流。本文带你看懂 Quill 的捕获自愈机制1 秒看门狗、750 毫秒路由监听防抖、三次分段重启是如何在无人干预下救回一条断掉的录音的。一、为什么 macOS 录音容易悄悄断掉 问题根源写在 macos/README.md 里连接或断开 AirPods、更改默认音频设备都可能让捕获流静默停止——系统不会报错音频只是不再流入。对会议场景这是致命的你戴着耳机开会中途把 AirPods 放回盒里再戴上录音文件照常存在后半段却是一片空白。Quill 的对策不是检测到出错再修而是给每条音轨装上一台独立的健康状态机让录音自己复活。所有机制集中在 CaptureHealth.swift核心参数一目了然参数默认值作用staleThresholdMs3000 ms超过 3 秒没写入新音频 → 判定停滞routeDebounceMs750 ms路由事件防抖窗口过滤通知风暴retryDelaysMs0 / 500 / 2000 ms最多 3 次重启间隔递增stabilityWindowMs5000 ms新片段须连续写入 5 秒才算真正恢复startupGraceMs5000 ms启动宽限期防止误判冷启动这些阈值被刻意收拢在 CapturePolicy 一个结构体里——测试可以把它们换成毫秒级的短值全程无需真实硬件和睡眠等待。二、1 秒看门狗如何判定一条音轨死了 ⏱️看门狗由 RecordingSession.startWatchdog 创建每秒唤醒一次逐轨调用 tick()let timer Timer(timeInterval: 1, repeats: true) { _ in MainActor.assumeIsolated { [weak self] in self?.tick() } } RunLoop.main.add(timer, forMode: .common)这里有个容易忽略的细节定时器被显式加入.common运行模式。默认模式下的 Timer 在用户按住菜单栏展开菜单时会暂停触发——那看门狗就瞎了。注释里原话是which would blind the watchdog。看门狗本身不做 I/O它只读取一个轻量遥测快照TrackTelemetry 由实时音频回调写入上次写入时间、缓冲末端、帧数、静音长度看门狗加锁读取锁只持有纳秒级。判死的逻辑极其简洁见 isStale最后一次成功写入距今 3 秒→ 停滞。音频回调正常节奏约为 85 毫秒一次所以 3 秒既是远大于噪声、又是远小于一场会议的甜点位。判定原因还会区分两种遥测里有写错误 →write_failed否则 →callback_stalledtickLive。两条关键防误报规则启动宽限期片段刚启动的前 5 秒内引擎构建、权限检查都要花真实时间没有写入不算停滞精确静音 ≠ 故障连续 15 秒的数字零silenceWarningMs只会记录一条诊断警告——比如对方没在说话、扬声器没在放音是合法状态看门狗绝不会因为安静就重启捕获。三、路由监听750 毫秒防抖拒绝狼来了 光靠看门狗还要等 3 秒太慢。所以每条音轨都挂了路由观察者把危险信号提前送达麦克风轨MicRecorder.observeRoute监听引擎配置变更通知 系统默认输入设备属性系统音轨SystemAudioRecorder.observeRoute监听默认输出设备与设备列表变化。但一次物理切换会触发一连串路由通知而且——通知不代表失败。耳塞拔插的瞬间回调可能完好无损。因此路由事件只把音轨标记为suspect可疑并开启 750 ms 防抖窗口routeEvent窗口内如果写入持续正常 → 自动回归healthy全程无感事件成串到达时通知风暴每来一条就重置计时等风暴平息再评估窗口结束仍停滞 → 以route_change为由立即进入恢复流程。真正的硬故障引擎停止、写盘失败则走 fault()直接视为防抖已耗尽下一拍就裁决——该快时绝不等。四、分段重启已写下的音频永远不动 ✂️这是整个设计里最克制也最关键的一条铁律重启从不修补旧文件而是开新文件。看 performRestart 的流程关闭当前片段——它已经录下的内容原样封存片段编号 1在当前音频路由上重建整条录制链路新片段写入mic-002.caf、system-002.caf这样编号的文件命名规则见 segmentFile。重启不是一击即中而是带递增延迟的三次预算nextAttemptOrDegrade第 1 次立即 → 第 2 次500 ms → 第 3 次2 s。三次全败 → 轨道标记degraded只发一条通知不再骚扰用户。而且恢复成功有严格验收新片段必须连续写入满 5 秒稳定窗口才算真正恢复、重置重试预算tickRecovering恢复中途再次卡死消耗的是同一个事件的下一份预算。这一切都被确定性单测逐条钉死见 CaptureHealthTests.swift——测试用纯整数时间驱动状态机无需音频设备、无需真实等待。五、你在界面上会看到什么 自愈全程对用户近乎无感只有状态在变macOS 文档 红色羽毛● recording · 28:11—— 双轨健康 橙色羽毛◐ recovering microphone—— 某轨停滞正在自动重启至多三次尝试 橙色⚠ microphone capture lost—— 三次救不回来发一条通知该轨标记 incomplete△ system audio silent—— 次级诊断轨道活着但在输出精确静音可能只是没声音在放。六、事后验尸meta.json 不会撒谎 停止录音后meta.jsonschema v2会原子写入逐轨交代清楚segments[]每个片段文件在统一单调会话时钟上的起止偏移中途改系统时间也不会让片段错位interruptions[]何时检测到中断、何时恢复、几次尝试、失败原因statuscomplete/recovered/incomplete。会话状态取最差的轨道。设计哲学就一句话recovered 的录音可用但永远不会被伪装成从未断过。转写照常进行——各片段独立转写后按偏移拼回同一时钟中断造成的空档在时间戳里清晰可见。写在最后Quill 的捕获自愈没有魔法只有四层克制的设计看门狗管结果音频真的进来了吗、路由监听管征兆危险提前 3 秒上报、防抖管误报正常切换不惊动任何人、分段重启管善后旧数据不动、新文件续命。配合 quill doctor 可做前置体检更多架构契约见 docs/architecture.md。对任何做长时录音的工具这套监控 → 判定 → 重启 → 留痕的链路都值得直接抄走。【免费下载链接】quillUltra-minimalist macOS recording transcription.项目地址: https://gitcode.com/gh_mirrors/quill26/quill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
