fix: tolerate macOS microphone deep idle

Author: Leonardlsa

.github/release-notes/v5.0.8.md

@@ -1,6 +1,6 @@
 # VoCoType-linux v5.0.8
 
-VoCoType-linux v5.0.8 是 V5 稳定线的 macOS 输入法更新可靠性热修复版本。它修复了更新后旧 InputMethod 进程可能继续驻留、导致麦克风 TCC 身份与磁盘中新 bundle 不一致的问题。
+VoCoType-linux v5.0.8 是 V5 稳定线的 macOS 麦克风恢复与输入法更新可靠性热修复版本。它同时修复“长时间不用电脑后第一次 F9 开不了麦克风”的 CoreAudio 启动竞态，以及更新后旧 InputMethod 进程可能继续驻留、导致 TCC 身份与磁盘中新 bundle 不一致的问题。
 
 发布日期：2026-09-12。
 
@@ -9,11 +9,21 @@ VoCoType-linux v5.0.8 是 V5 稳定线的 macOS 输入法更新可靠性热修
 - **更新前先禁用旧输入源**：DMG 安装脚本在替换 `~/Library/Input Methods/VoCoType-linux.app` 前先禁用旧 VoCoType 输入源，再终止旧 InputMethod 和录音相关进程，避免 InputMethodKit 在文件复制过程中自动重新拉起旧进程。
 - **最终安装后强制建立新的进程边界**：新 bundle 完整复制、LaunchServices 注册和输入源安装完成后，再终止一次 InputMethod 并重新激活，确保最终常驻进程一定从最终安装、最终签名的 bundle 启动。
 - **Settings App 自动更新采用同样策略**：嵌入式 InputMethod 更新完成并激活后，也会做最终进程重启，DMG 安装与应用内更新行为保持一致。
-- **保留 v5.0.7 的录音启动 watchdog**：本次没有放宽或移除 CoreAudio 5 秒启动保护；现场验证表明当前问题不是 watchdog 阈值，而是更新后遗留的进程身份错位。
+- **修正休眠/长时间闲置后的启动 watchdog 竞态**：macOS 26.5 真机日志显示，内建麦克风长时间未使用后，从 CoreAudio `idle` 唤醒到 `_StartIO succeeded` 实测约需 **5.004 秒**。v5.0.7 的 5 秒 watchdog 会在 HAL 刚进入 Running 的瞬间 `_Exit(2)`，导致第一次 F9 必然失败。v5.0.8 将阈值提高到 **8 秒**，保留卡死保护的同时给深度 idle 唤醒留出余量。
+- **Playground 的“录制 3 秒”从真实 PCM 开始计时**：macOS Settings 不再直接在自身进程里阻塞式打开 CoreAudio，而是调用隔离的 recorder helper；只有第一块真实音频到达后才开始 3 秒计时，并通过 `level` 事件继续驱动波形。Playground helper 禁用流式 ASR preview，避免麦克风测试额外启动识别链路。若 CoreAudio 真正卡死，8 秒 watchdog 只终止 recorder 子进程，不会让 Settings App 永久卡住。
 
 ## 真机证据
 
-受影响机器上，磁盘中的 `VoCoType-linux.app` 能通过 `codesign --verify --deep --strict`，但常驻 InputMethod 进程仍是前一天更新前启动的旧进程。真实 F9 录音时，TCC 日志出现：
+受影响机器上抓到了两类独立但会叠加的问题。
+
+第一类是长时间闲置后的 CoreAudio 深度 idle 唤醒：
+
+- 18:35:19.865：`BuiltInMicrophoneDevice` 开始 `IOWorkLoopInit`；
+- 18:35:24.869：`Digital Mic` 进入 `runn`，`HALS_IOEngine2::_StartIO succeeded`；
+- 总耗时约 **5.004 秒**；
+- 旧 5 秒 watchdog 正好在这一边界杀掉 recorder，随后 CoreAudio 立即 stop，用户看到 F9 一直无法开始采音。
+
+第二类是更新后进程身份错位。磁盘中的 `VoCoType-linux.app` 能通过 `codesign --verify --deep --strict`，但常驻 InputMethod 进程仍可能是前一天更新前启动的旧进程。真实 F9 录音时，TCC 日志出现：
 
 `IDENTITY_ATTRIBUTION: Failed to copy signing info ... -67034`
 
@@ -29,6 +39,9 @@ VoCoType-linux v5.0.8 是 V5 稳定线的 macOS 输入法更新可靠性热修
 
 验证结果：
 
+- 修复前，长时间闲置后第一次真实 F9 在 5.015 秒处被 watchdog 终止，且 CoreAudio 日志显示硬件刚在 5.004 秒左右进入 Running；
+- 修复后 watchdog 固定为 8 秒，并新增 source contract 禁止回退到 5 秒；
+- Playground timed capture 改为从第一块真实 PCM 计时，并通过隔离 helper 提供波形 level 事件；
 - macOS CTest：10/10 PASS；
 - native source contracts：PASS；
 - `packaging/macos/install.command` shell syntax：PASS。

CHANGELOG.md

@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- macOS microphone startup watchdog now allows 8 seconds instead of 5 seconds for the first PCM block. On macOS 26.5, a built-in microphone left unused for a long period was observed taking about 5.004 seconds to transition from CoreAudio `idle` to `Running`; the previous 5-second watchdog killed the recorder at the exact moment the HAL finished waking, making the first F9 after inactivity fail deterministically.
+- macOS timed recorder sessions now start their requested duration from the first real PCM block instead of process launch. The Settings Playground records through the isolated recorder helper with waveform level events and no streaming-ASR preview, so a cold microphone can finish waking before the 3-second capture window begins and a genuine CoreAudio hang cannot wedge the Settings process.
 - macOS upgrades now disable the old input source before replacing its bundle and force a final InputMethod process restart only after the new bundle is fully installed and registered. This prevents a stale in-memory input-method executable from remaining responsible for a newly signed on-disk bundle, which can make TCC microphone identity attribution fail intermittently even though the replacement bundle passes `codesign` verification.
 - The Settings App embedded-input-method updater now enforces the same final process boundary after activation, so both DMG installs and in-app upgrades converge on a fresh process loaded from the final installed bundle.
 

scripts/test/contracts.sh

@@ -239,6 +239,19 @@ rg -Fq 'prewarm_offline_asr(socket, config, asr_lease)' src/integrations/macos/V
   fail "macOS does not prewarm final ASR at recording start"
 rg -Fq 'wait_for_asr_prepare(asr_lease' src/integrations/macos/VocoTypeInputController.mm || \
   fail "macOS final ASR does not wait for recording-time preparation"
+rg -Fq 'kMicrophoneStartupTimeout = std::chrono::seconds(8)' src/desktop/src/audio_recorder_main.cpp || \
+  fail "macOS microphone startup watchdog must allow the observed >5s deep-idle wakeup"
+if rg -Fq 'kMicrophoneStartupTimeout = std::chrono::seconds(5)' src/desktop/src/audio_recorder_main.cpp; then
+  fail "macOS microphone startup watchdog regressed to the post-idle 5s race"
+fi
+for token in 'first_audio_started_ns' '--emit-levels' '--no-preview'; do
+  rg -Fq -- "$token" src/desktop/src/audio_recorder_main.cpp || \
+    fail "macOS timed recorder no longer measures from real PCM or exposes isolated Playground capture: $token"
+done
+for token in 'capture_recording_via_helper' '"--emit-levels"' '"--no-preview"'; do
+  rg -Fq -- "$token" src/desktop/src/settings_backend.cpp || \
+    fail "macOS Playground capture no longer uses the watchdog-protected recorder helper: $token"
+done
 mac_install=packaging/macos/install.command
 rg -Fq '"$OLD_TOOL" --disable "$IDENTIFIER"' "$mac_install" || \
   fail "macOS installer does not disable the old input source before replacement"

src/desktop/src/audio_recorder_main.cpp

@@ -3,6 +3,7 @@
 #include "vocotype/desktop/ipc.hpp"
 #include "vocotype/desktop/streaming_preview.hpp"
 #include "vocotype/desktop/wav.hpp"
+#include <algorithm>
 #include <atomic>
 #include <chrono>
 #include <condition_variable>
@@ -33,6 +34,8 @@ void emit(const Json &value) {
 struct Options {
   bool list_devices = false;
   bool probe = false;
+  bool emit_levels = false;
+  bool preview = true;
   int duration_ms = 0;
   std::filesystem::path config;
   std::string socket = backend_socket_path();
@@ -45,6 +48,10 @@ Options parse(int argc, char **argv) {
       options.list_devices = true;
     else if (arg == "--probe")
       options.probe = true;
+    else if (arg == "--emit-levels")
+      options.emit_levels = true;
+    else if (arg == "--no-preview")
+      options.preview = false;
     else if (arg == "--duration-ms" && i + 1 < argc)
       options.duration_ms = std::stoi(argv[++i]);
     else if (arg == "--config" && i + 1 < argc)
@@ -53,7 +60,8 @@ Options parse(int argc, char **argv) {
       options.socket = argv[++i];
     else if (arg == "--help") {
       std::cout << "Usage: vocotype-audio-recorder [--list-devices|--probe] "
-                   "[--duration-ms N] [--config PATH] [--socket PATH]\n";
+                   "[--emit-levels] [--no-preview] [--duration-ms N] "
+                   "[--config PATH] [--socket PATH]\n";
       std::exit(0);
     } else
       throw std::runtime_error("unknown argument: " + arg);
@@ -97,7 +105,9 @@ int main(int argc, char **argv) {
     std::atomic_bool preview_accepting{true};
     int preview_chunk_samples = 9600;
 
-    std::thread preview_thread([&] {
+    std::thread preview_thread;
+    if (options.preview) {
+      preview_thread = std::thread([&] {
       StreamingPreviewTranscript transcript;
       std::deque<std::vector<std::int16_t>> recent_chunks;
       constexpr std::size_t kRecentChunkLimit = 3;
@@ -264,12 +274,16 @@ int main(int argc, char **argv) {
         }
       }
       preview_accepting.store(false);
-    });
+      });
+    } else {
+      preview_accepting.store(false);
+    }
 
     AudioCapture capture(device, sample_rate, config.block_ms,
                          input.native_capture_name);
     std::string capture_error;
     std::atomic_bool first_audio_block{false};
+    std::atomic_int64_t first_audio_started_ns{0};
     std::atomic_bool capture_finished{false};
 #ifdef __APPLE__
     // CoreAudio can occasionally wedge inside AudioDeviceStart without
@@ -278,28 +292,45 @@ int main(int argc, char **argv) {
     // not sufficient here: a timed recording may request stop while the
     // capture thread is still blocked inside AudioDeviceStart.
     std::thread([&first_audio_block, &capture_finished] {
-      constexpr auto kMicrophoneStartupTimeout = std::chrono::seconds(5);
+      // A built-in microphone that has been idle for a long time can take just
+      // over five seconds to leave its deep CoreAudio power state on macOS 26.
+      // Keep enough margin to avoid killing the recorder exactly as the HAL
+      // reports the device Running, while still bounding genuine startup hangs.
+      constexpr auto kMicrophoneStartupTimeout = std::chrono::seconds(8);
       std::this_thread::sleep_for(kMicrophoneStartupTimeout);
       if (!first_audio_block.load(std::memory_order_acquire) &&
           !capture_finished.load(std::memory_order_acquire)) {
         emit({{"type", "error"},
-              {"error", "麦克风启动超时（CoreAudio 未返回音频）；请重试，必要时重启系统音频服务"}});
+              {"error", "麦克风启动超过 8 秒（CoreAudio 未返回音频）；请重试，必要时重启系统音频服务"}});
         std::_Exit(2);
       }
     }).detach();
 #endif
     std::thread capture_thread([&] {
       try {
         capture.run(stop, [&](const std::vector<std::int16_t> &block) {
-          if (!first_audio_block.exchange(true))
+          if (!first_audio_block.exchange(true)) {
+            first_audio_started_ns.store(
+                std::chrono::duration_cast<std::chrono::nanoseconds>(
+                    std::chrono::steady_clock::now().time_since_epoch())
+                    .count(),
+                std::memory_order_release);
             emit({{"type", "recording"},
                   {"device_id", device.id},
                   {"device_name", device.name},
                   {"sample_rate", sample_rate}});
+          }
           {
             std::lock_guard lock(samples_mutex);
             samples.insert(samples.end(), block.begin(), block.end());
           }
+          if (options.emit_levels && !block.empty()) {
+            const auto [minimum, maximum] =
+                std::minmax_element(block.begin(), block.end());
+            emit({{"type", "level"},
+                  {"minimum", static_cast<double>(*minimum) / 32768.0},
+                  {"maximum", static_cast<double>(*maximum) / 32768.0}});
+          }
           if (preview_accepting.load(std::memory_order_relaxed)) {
             auto converted = resample_linear(block, sample_rate, 16000);
             std::lock_guard lock(queue_mutex);
@@ -315,13 +346,19 @@ int main(int argc, char **argv) {
       capture_finished.store(true, std::memory_order_release);
     });
 
-    const auto started_at = std::chrono::steady_clock::now();
     while (!stop.load()) {
-      if (options.duration_ms > 0 &&
-          std::chrono::steady_clock::now() - started_at >=
-              std::chrono::milliseconds(options.duration_ms))
-        break;
       if (options.duration_ms > 0) {
+        const std::int64_t audio_started_ns =
+            first_audio_started_ns.load(std::memory_order_acquire);
+        if (audio_started_ns > 0) {
+          const std::int64_t now_ns =
+              std::chrono::duration_cast<std::chrono::nanoseconds>(
+                  std::chrono::steady_clock::now().time_since_epoch())
+                  .count();
+          if (now_ns - audio_started_ns >=
+              static_cast<std::int64_t>(options.duration_ms) * 1000000)
+            break;
+        }
         std::this_thread::sleep_for(std::chrono::milliseconds(20));
         continue;
       }
@@ -347,7 +384,8 @@ int main(int argc, char **argv) {
         preview_done = true;
       }
       queue_cv.notify_all();
-      preview_thread.join();
+      if (preview_thread.joinable())
+        preview_thread.join();
       throw std::runtime_error(capture_error);
     }
 
@@ -364,7 +402,8 @@ int main(int argc, char **argv) {
         preview_done = true;
       }
       queue_cv.notify_all();
-      preview_thread.join();
+      if (preview_thread.joinable())
+        preview_thread.join();
       throw std::runtime_error("recording produced no audio samples");
     }
 

src/desktop/src/settings_backend.cpp

@@ -351,7 +351,93 @@ Json run_process(const std::vector<std::string> &arguments) {
           {"error", exit_code == 0 ? "" : output}};
 }
 
+#ifdef __APPLE__
+Json capture_recording_via_helper(int duration_ms,
+                                  const WaveformCallback &callback) {
+  const auto recorder = runtime_root() / "bin/vocotype-audio-recorder";
+  if (!std::filesystem::is_regular_file(recorder))
+    return {{"success", false}, {"error", "找不到原生录音器"}};
+
+  int output_pipe[2]{};
+  if (vocotype::common::create_pipe_close_on_exec(output_pipe) != 0)
+    return {{"success", false}, {"error", "无法创建录音器输出管道"}};
+
+  const pid_t child = ::fork();
+  if (child < 0) {
+    ::close(output_pipe[0]);
+    ::close(output_pipe[1]);
+    return {{"success", false}, {"error", "无法启动原生录音器"}};
+  }
+  if (child == 0) {
+    ::dup2(output_pipe[1], STDOUT_FILENO);
+    ::close(output_pipe[0]);
+    ::close(output_pipe[1]);
+    const std::string duration = std::to_string(std::max(1, duration_ms));
+    const std::string config = runtime_config_path().string();
+    ::execl(recorder.c_str(), recorder.c_str(), "--duration-ms",
+            duration.c_str(), "--config", config.c_str(), "--emit-levels",
+            "--no-preview", static_cast<char *>(nullptr));
+    ::_exit(127);
+  }
+
+  ::close(output_pipe[1]);
+  std::string error;
+  Json audio = Json::object();
+  FILE *file = ::fdopen(output_pipe[0], "r");
+  if (file) {
+    char *line = nullptr;
+    std::size_t capacity = 0;
+    while (::getline(&line, &capacity, file) >= 0) {
+      try {
+        const Json event = Json::parse(line);
+        const std::string type = event.value("type", "");
+        if (type == "level") {
+          if (callback)
+            callback(event.value("minimum", 0.0),
+                     event.value("maximum", 0.0));
+        } else if (type == "audio") {
+          audio = {{"success", true},
+                   {"path", event.value("path", "")},
+                   {"sample_rate", event.value("sample_rate", 0)},
+                   {"frames", event.value("frames", std::size_t{0})},
+                   {"device_id", event.value("device_id", -1)},
+                   {"device", event.value("device_name", "")}};
+        } else if (type == "error") {
+          error = event.value("error", "录音失败");
+        }
+      } catch (const std::exception &) {
+      }
+    }
+    std::free(line);
+    ::fclose(file);
+  } else {
+    ::close(output_pipe[0]);
+  }
+
+  int status = 0;
+  while (::waitpid(child, &status, 0) < 0 && errno == EINTR) {
+  }
+  if (!audio.empty() && WIFEXITED(status) && WEXITSTATUS(status) == 0)
+    return audio;
+  if (error.empty()) {
+    if (WIFEXITED(status))
+      error = "原生录音器退出，状态码 " + std::to_string(WEXITSTATUS(status));
+    else
+      error = "原生录音器异常退出";
+  }
+  return {{"success", false}, {"error", error}};
+}
+#endif
+
 Json capture_recording(int duration_ms, const WaveformCallback &callback) {
+#ifdef __APPLE__
+  // Keep CoreAudio in a disposable helper process. A deep-idle microphone can
+  // need more than five seconds before the first PCM callback, while a truly
+  // wedged AudioDeviceStart cannot be safely cancelled from inside Settings.
+  // The helper owns the bounded startup watchdog and starts the requested
+  // duration only after the first real audio block arrives.
+  return capture_recording_via_helper(duration_ms, callback);
+#else
   try {
     const auto config = load_audio_config();
     const auto device = resolve_input_device(config);
@@ -395,6 +481,7 @@ Json capture_recording(int duration_ms, const WaveformCallback &callback) {
   } catch (const std::exception &error) {
     return {{"success", false}, {"error", error.what()}};
   }
+#endif
 }
 
 Json play_recording(const std::filesystem::path &path, int output_device_id) {