Home.zh CN

Voice Input Wiki

English

Voice Input 是一个常驻的 Agent-aware 语音输入服务，面向 Omarchy、Hyprland 和 Wayland。它组合了 Qwen 实时 ASR、实验性 Audio3 Streaming 与 Native 识别、可选的完整音频恢复、保守的 LLM 文本整理、Pi/Codex 术语上下文、不接收点击的 Quickshell HUD，以及按需启动的 Quickshell Settings。

本页仅作为索引。项目的简短介绍请参阅仓库 README。

从这里开始

目标	页面
从全新 clone 开始安装	安装指南
查看全部 TOML 配置项	配置参考
了解采集、ASR、整理和输出流程	架构
启用 dictation 开始时聚焦的 Pi/Codex 会话术语上下文	Agent 上下文
集成 Hyprland、Quickshell 和 Waybar	桌面集成
了解哪些数据会离开本机	安全与隐私
排查故障	故障排查
构建、测试、打包或贡献代码	开发指南

当前支持的运行方式

Voice Input 目前面向使用 Hyprland 和 Wayland 的 Linux 图形用户会话。标准安装会启动两个 systemd 用户服务：

• voice-input.service 运行 Rust daemon。
• voice-input-hud.service 让 assets/quickshell 中的 Quickshell HUD 保持常驻。

Settings 使用 assets/quickshell-settings 中的另一套 Quickshell 配置，并且按需显示为普通浮动窗口；它不是第三个 service。

公开示例配置默认使用本地 ASR，并明确调用 /usr/bin/voxtype。Alibaba Qwen 实时 ASR、Qwen 全音频最终识别、LLM 整理、Agent 上下文和麦克风 pre-roll 都需要用户主动启用。

常用命令

voice-input record toggle
voice-input record restart
voice-input record cancel
voice-input diagnostics
voice-input status
voice-input status --follow --format json --extended
voice-input settings
voice-input setup model
voice-input llm test

提交支持报告时，请使用 voice-input diagnostics [--format text|json]。请勿分享 voice-input status 的输出，包括带 --extended 的输出：status 用于本地 UI 集成，其中可能包含当前或最近一次 transcript 和 tooltip。

检查服务：

systemctl --user status voice-input.service voice-input-hud.service
journalctl --user -u voice-input.service -u voice-input-hud.service -b

主要行为

• Qwen 实时 ASR 提供 partial 和 final transcript；Server VAD 同时提供语音活动状态。如果结束前发生符合条件的传输中断或 transcript 停滞，worker 最多重建一次会话，并在完整音频恢复接管前重放保留的音频。
• 实验性 Audio3 Streaming 通过 WebSocket 提供实时文本。结束前发生一次可恢复的断线时，程序会创建新 task，使中断 task 的 transcript 失效，并以 4 倍实时速度重放保留的完整前缀。第二次断线、发送 finish-task 后断线或其他降级结果会使用已配置的 Audio3 Native 或本地完整音频恢复路径。
• 对于 Qwen Realtime，可选的 final pass 会把完整的临时 WAV 上传到配置的 Alibaba-compatible HTTP endpoint。成功后，其结果会替换实时识别文本。
• 独立采集和共享 pre-roll 采集路径都会在达到 audio.max_duration_secs 后自动停止并进入最终处理；默认上限为五分钟。
• 实时音频使用容量受限的非阻塞传输方式。如果远程 stream 处理速度落后，采集仍会继续，并通过已启用的 final pass 或本地 fallback 处理完整录音，而不会采用不完整的远程文本。
• LLM 整理失败时继续使用 ASR 文本。带上下文的请求与可能执行的纯 transcript 重试共用一份预算：默认 15 秒，上限为 30 秒。
• Pi/Codex 上下文是可选功能，仅用于术语校正，并且会经过验证、脱敏和长度限制。程序会在 dictation 开始时捕获术语来源，并为 Audio3 Streaming 和 Refine 冻结同一份快照；停止时的焦点只选择 refinement 的目标风格。即使没有启用会话上下文，Pi/Codex 目标也会使用忠实且紧凑的 Markdown。
• 每段 transcript 都会通过剪贴板粘贴并恢复原内容：Wayland 使用 wl-copy 和 Hyprland sendshortcut，XWayland 使用 xclip 和 xdotool。在原生 Wayland 上，临时 transcript 和恢复的剪贴板内容都会标记为敏感；用户仍应把两者视为敏感数据。
• Quickshell HUD 从 state.json 读取状态、可见性和几何配置，并通过单独的 Unix socket 接收波形帧。因此，界面更新频率不会决定 ASR packet 的发送频率。HUD 内部底部的状态行会显示当前阶段和有效录音时长，不会把 arming 或后续处理时间计入录音时长。
• voice-input settings 会激活已有的 Settings 窗口，或者启动新窗口。QML 通过带版本号的 NDJSON 与 Rust child backend 通信；只有 Rust 负责验证配置，并以原子方式写入配置和 credential。

项目边界

Voice Input 是独立的社区项目，与 Omarchy、Alibaba、OpenAI、OpenRouter、Pi、Codex 或 Voxtype 没有官方隶属或背书关系。

下一步：安装指南 · 架构 · 故障排查