README.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

# Mic Clipper

一个面向 Linux 桌面的本机常驻“说话片段录音器”。它持续从 PipeWire/Pulse 的动态默认麦克风输入读取音频，仅在本地 Silero VAD 判为语音时才创建文件。

## 行为与隐私

- 16 kHz 单声道输入；每 32 ms（512 个采样）运行一次本地 ONNX VAD。
- 语音开始时带 0.5 秒内存前置音频；持续静音 1.5 秒后关闭片段。
- 使用 Ogg/Opus、`libopus`、24 kbps、语音优化编码，保存为 `*.opus`。
- 文件写入 `~/Documents/Mic Clips/YYYY-MM-DD/HH-MM-SS.opus`；跨午夜时目录按片段开始日期确定。
- 静音不会创建文件。音频只在内存中保留有限的前置缓冲；不调用 ASR、不上传、不保存转写文本，也不自动删除旧录音。
- 单段最长 10 分钟。连续说话会无缝滚动为下一段，避免内存无限增长；相邻段会在边界处保持音频连续。
- 目录权限为 `0700`，录音文件为 `0600`。日志仅写设备/编码器故障与重试信息，不写音频或文本。

存储量约为 `24 kbit/s / 8 = 3 kB/s`，即每小时约 10.8 MB、每天连续录音约 259 MB。实际仅保存语音片段，通常会低于这个上限。

## 运行时依赖

目标解释器必须是：

```text
/home/somhairle/.hermes/hermes-agent/venv/bin/python
```

该解释器需要已有 `numpy` 与 `onnxruntime`。系统需要带 `pulse` 输入和 `libopus` 编码器的 `ffmpeg`。本项目不执行 `pip install`、模型下载或任何联网操作。

部署前必须确认项目包内存在：

```text
src/mic_clipper/assets/silero_vad_v6.onnx
```

该权重已从当前机器已验证的 `faster-whisper` 1.2.1 本地资源复制进项目包。归属、MIT 许可声明和 SHA-256 校验值见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。运行时代码只读取包内模型；不会下载模型，也不会回退读取外部包资源。

## 安装与服务

以下命令均从项目根目录执行。先用 dry-run 审阅将执行的 systemd 命令；它不会写入家目录。

```bash
RUNTIME=/home/somhairle/.hermes/hermes-agent/venv/bin/python
PROJECT=/home/somhairle/projects/mic-clipper
PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service install --dry-run
```

经独立审阅后，安装并立即启用用户服务：

```bash
PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service install
```

安装器仅写 `~/.config/systemd/user/mic-clipper.service`，然后执行 `daemon-reload` 与 `enable --now`。服务 `Wants`/`After` PipeWire、WirePlumber 与 pipewire-pulse，应用本身会在默认麦克风暂不可用或设备切换时以 1、2、4...60 秒退避重试。`Restart=on-failure` 只处理异常退出，手动 `stop` 不会立即拉起服务。

## 日常命令

```bash
# 服务状态
PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service status

# 手动启动、停止、重启
systemctl --user start mic-clipper.service
systemctl --user stop mic-clipper.service
systemctl --user restart mic-clipper.service

# 前台运行（便于排障；Ctrl-C 正常收尾当前编码器）
PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli run

# 卸载 unit，不删除任何录音
PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service uninstall
```

## 故障排查

```bash
# 查看不含音频内容的服务日志
journalctl --user -u mic-clipper.service -f

# 确认 PipeWire/Pulse 默认源与 ffmpeg 能力
pactl get-default-source
ffmpeg -hide_banner -h demuxer=pulse
ffmpeg -hide_banner -h encoder=libopus
```

若日志显示 Pulse 输入退出，确认 `pipewire.service`、`wireplumber.service` 和 `pipewire-pulse.service` 正常运行；应用会自行重试。若 VAD 报模型缺失，先恢复上文列出的包内 ONNX 文件，不能用联网下载替代。