Vocalinux 是一款免费开源、100% 离线的 Linux 语音听写工具：说完话，文字直接出现在当前聚焦的窗口里。本文带你从架构视角拆解它的完整数据流——麦克风采集 → VAD 语音分段 → 语音引擎转写 → 命令后处理 → 键盘文本注入，看清一句话是如何一步步"敲"进屏幕的。

🎯 先鸟瞰全局：听写数据流一图流

官方架构文档 docs/ARCHITECTURE.md 用五步概括了核心数据流：

麦克风 (PortAudio / PipeWire) ↓ audio/capture.py · audio/pipewire.py (单声道 16 kHz PCM) ↓ recognition_manager.py · VAD 分段 (Silero 神经 VAD / 振幅 VAD) ↓ 有界分段队列 (maxsize=32) ↓ 识别 worker → 语音引擎 (whisper.cpp / Whisper / VOSK …) → 命令解析 ↓ post_processor.py 后处理脚本 → TextInjector 注入文本

入口 src/vocalinux/main.py 负责组装配置管理器、识别管理器、托盘 UI、D-Bus 服务与文本注入器；音频与识别的实际工作全部运行在 GTK 事件循环之外的独立线程里——这就是你说话时界面从不卡顿的原因。

🎤 第一步：麦克风采集——音频流的源头

音频采集由 src/vocalinux/audio/capture.py 与 src/vocalinux/audio/pipewire.py 承担，提供两种采集源：

• PortAudioCaptureSource：默认采集源，经 ALSA / PulseAudio 读取麦克风
• PipeWireCaptureSource：面向 PipeWire 系统的专用源，自行拉起pw-record

两者遵守统一契约：输出单声道、16 kHz、int16 PCM数据，每块 1024 个采样（见 capture.py#L33）。采集源只管"设备 → PCM"，不做任何听写逻辑。输入设备选择与麦克风测试可在设置面板中直接完成：

在 recognition_manager.py#L3580-L3679 中，_record_audio()录音循环持续读取这些数据块，交给下一级的 VAD 判断。

📊 第二步：VAD 语音活动检测——听清你何时开口、何时停顿

连续音频必须被切分成"一句话一个片段"，这正是 VAD（Voice Activity Detection）的职责：

• 首选：Silero 神经 VAD。当onnxruntime可用时，silero_vad.py#L19-L20 每 512 个采样（约 32 ms）输出一次"语音概率"，模型文件随包内置于 data/silero_vad.onnx
• 回退：振幅阈值 VAD。缺少 ONNX 运行环境时，自动退化为简单的 RMS 振幅阈值判断

影响分段体验的参数（麦克风灵敏度 1–5、静音停止时长等）都集中在 Dictation 设置页：

完整的一句话被切出后，会压入一个有界队列（recognition_manager.py#L3352，最多 32 个片段）。这个缓冲把采集线程与识别线程解耦开：引擎还在处理上一段时，你可以继续说下一句。

🧠 第三步：语音引擎转写——把声音变成字

识别 worker 从队列取出片段，按当前选中的引擎分发转写。common_types.SpeechEngine 定义了运行时可检查的引擎契约，管理器用引擎名分发表调用各引擎的转写方法（详见 ARCHITECTURE.md "Speech engines" 一节）。

Vocalinux 支持多引擎，在 Speech Model 面板里一键切换：

模型下载一次即可，之后语音转写完全离线完成；管理器还持有一把"模型锁"，保护引擎加载、转写与清理过程不被并发破坏。

✂️ 第四步：后处理——语音命令与自定义脚本

转写结果不会直接飞向键盘，先经过两道"精加工"：

1. 语音命令解析：command_processor.py#L39-L63 把口述短语替换成标点与动作——"period" →.、"new line" → 换行、"new paragraph" → 分段，配合 "delete that" 还能删掉上一句
2. 后处理脚本：若在post_processing.script_path配置了可执行脚本，post_processor.py#L15-L44 会把文本从 stdin 传入、把 stdout 收回。所有片段由单个 worker 串行消费，严格保证文字按你说出的顺序落键

⌨️ 第五步：文本注入——让文字落进当前窗口

最后一步由 text_injector.py#L1646-L1670 完成：TextInjector先探测桌面环境（X11 还是 Wayland），再选择合适的"打字工具"：

效果就是：无论焦点在编辑器、浏览器还是终端，文字都像亲手敲出来一样进入输入框：

触发方式在同一页设置里配置：新安装默认Push-to-Talk（按住 Right Alt 说话、松开结束），由 keyboard_shortcuts.py#L51-L57 管理；也可切换双击触发的 Toggle 模式，或通过 D-Bus 服务 dbus_service.py 用全局快捷键远程控制启停。

🧵 幕后：线程如何分工

数据流能不打架地运转，靠的是清晰的线程职责划分（ARCHITECTURE.md "Threads and state ownership" 一节）：

• GTK 主线程：只碰控件、托盘与对话框；UI 状态更新经GLib.idle_add调度回主循环
• 音频采集线程：读麦克风、跑 VAD、把完成片段入队
• 识别 worker：消费分段队列，执行转写并触发回调
• 后处理 worker：单个 worker 串行执行脚本 + 文本注入，保序不乱

内置日志查看器能让你亲眼看到整条流水线：Silero VAD 加载、Vulkan GPU 探测、whisper.cpp 模型初始化，全部有据可查：

📚 想深挖源码？从这里入手

🔚 一句话总结

Vocalinux 的架构本质是一条流水线式、线程隔离的数据流：麦克风捕获 16 kHz 单声道音频，Silero VAD 把它切成语句，分段队列缓冲采集与识别两端，选定的语音引擎（默认 whisper.cpp）完全离线地转写成文字，再经语音命令与脚本后处理，最终由 xdotool、IBus 或 Wayland Portal 注入当前窗口。每一环都有明确的属主，环与环之间靠队列和锁衔接——所以你能一边说话、系统一边处理，而文字永远按你开口的顺序落到键盘上。