From 60f05cebd8e7968621a0ce015cf72987ec7577c7 Mon Sep 17 00:00:00 2001
From: "Somhairle H. Marisol" <muqiu-han@outlook.com>
Date: Tue, 29 Sep 2026 10:50:12 +0800
Subject: feat(recorder): add offline voice clip pipeline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

[变更性质]
- 本提交新增本机离线的语音片段录音能力，不涉及网络服务或语音识别。

[新增功能]
- 通过 Pulse 默认输入持续采集音频，以本地 Silero VAD 触发片段。
- 以私有目录和权限写入 24 kbps Ogg/Opus 录音，并提供 systemd 用户服务安装器。

[实现方案]
- 使用有限前置缓冲、静音封段和最长段滚动状态机，避免静音落盘及内存无限增长。
- 增加真实 Opus 编解码、服务 dry-run 和纯逻辑状态转换测试；记录模型归属和部署前置条件。

[影响范围]
- 新增 Python CLI、运行时模块、中文运维文档和自动测试。
- 未安装、启用或启动任何用户 systemd 服务；不删除或修改录音数据。
---
 src/mic_clipper/runner.py | 92 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 src/mic_clipper/runner.py

(limited to 'src/mic_clipper/runner.py')

diff --git a/src/mic_clipper/runner.py b/src/mic_clipper/runner.py
new file mode 100644
index 0000000..787bf58
--- /dev/null
+++ b/src/mic_clipper/runner.py
@@ -0,0 +1,92 @@
+"""Runtime wiring for capture, VAD, segmentation, and durable clips."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable, Iterable
+from datetime import datetime
+from pathlib import Path
+from typing import Protocol
+
+import numpy as np
+
+from mic_clipper.audio_input import PulseAudioInput
+from mic_clipper.segmenter import Audio, End, Segmenter, Start
+from mic_clipper.storage import ClipWriter, OpenClip
+from mic_clipper.vad import SileroVad
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+class Vad(Protocol):
+    def probability(self, samples: np.ndarray) -> float: ...
+
+
+class Writer(Protocol):
+    def open(self, started_at: datetime) -> OpenClip: ...
+
+
+def record_frames(
+    frames: Iterable[np.ndarray],
+    *,
+    vad: Vad,
+    writer: Writer,
+    segmenter: Segmenter,
+    now: Callable[[], datetime],
+    threshold: float = 0.5,
+) -> None:
+    """Record one finite or failing frame stream, closing an active encoder on exit."""
+    clip: OpenClip | None = None
+    try:
+        for samples in frames:
+            events = segmenter.push(samples, vad.probability(samples) >= threshold, now())
+            for event in events:
+                if isinstance(event, Start):
+                    clip = writer.open(event.started_at)
+                    try:
+                        clip.write(event.samples)
+                    except BaseException:
+                        clip.abort()
+                        clip = None
+                        raise
+                elif isinstance(event, Audio):
+                    if clip is None:
+                        raise RuntimeError("segment audio arrived without an active encoder")
+                    clip.write(event.samples)
+                elif isinstance(event, End):
+                    if clip is None:
+                        raise RuntimeError("segment end arrived without an active encoder")
+                    clip.close()
+                    clip = None
+    finally:
+        if clip is not None:
+            clip.close()
+
+
+def run_forever(root: Path, *, threshold: float = 0.5) -> None:
+    """Recreate all live components after a transient audio-service failure."""
+    retry_seconds = 1
+    while True:
+        try:
+            record_frames(
+                PulseAudioInput().frames(),
+                vad=SileroVad(),
+                writer=ClipWriter(root),
+                segmenter=Segmenter(pre_roll_seconds=0.5, silence_seconds=1.5),
+                now=lambda: datetime.now().astimezone(),
+                threshold=threshold,
+            )
+            raise RuntimeError("Pulse input ended unexpectedly")
+        except KeyboardInterrupt:
+            LOGGER.info("microphone clip recorder stopped")
+            return
+        except Exception as error:
+            LOGGER.warning(
+                "audio recorder unavailable (%s); retrying in %s seconds",
+                error,
+                retry_seconds,
+            )
+            time.sleep(retry_seconds)
+            retry_seconds = min(retry_seconds * 2, 60)
-- 
cgit v1.2.3