Installation.zh CN

安装指南

English · 首页

平台前提

当前实现面向使用 Hyprland 和 Wayland 的 Linux 图形用户会话。仓库提供的是 systemd 用户级 unit。随附集成目前没有覆盖其他 compositor 或 init system。

依赖

标准完整安装所需的依赖

依赖	用途
支持 Rust 2024 的 stable Rust toolchain、Cargo	构建二进制文件
GNU Make、install、sed、grep	执行随附的 Makefile
PipeWire 的 pw-record	采集单声道 PCM 麦克风音频
Hyprland 工具 hyprctl	查找活动窗口和显示器，并判断输出目标类型
wl-clipboard 2.3 或更高版本（wl-copy、wl-paste）	Wayland 粘贴、剪贴板备份与恢复，以及 sensitive 剪贴板标记
systemd 用户会话	运行 daemon/HUD service，并加载加密 credential
安装在 /usr/bin/qs 的 Quickshell 0.3 或更高版本	常驻 HUD 和按需启动的 Settings；Voice Input 使用该精确路径
Qt Shader Tools / qsb 6.7 或更高版本	安装期间使用 Qt 6 target set 编译 HUD shader

不同发行版的 package 名可能不同，请直接检查命令，并单独确认 Quickshell 的精确路径：

command -v cargo make pw-record hyprctl wl-copy wl-paste systemctl
test -x /usr/bin/qs
qsb_path=$(command -v qsb || command -v qsb6 || printf '%s' /usr/lib/qt6/bin/qsb)
test -x "$qsb_path"
"$qsb_path" --help | grep -F -- --qt6

Makefile 会依次查找 qsb、qsb6 和 /usr/lib/qt6/bin/qsb。如果 Qt 安装在其他位置，请向 make 传入 QSB=/path/to/qsb；所选工具必须支持 --qt6。

特定配置所需的依赖

依赖	需要它的情况
/usr/bin/voxtype	使用默认 local-cli provider，或在 Qwen 失败后启用 fallback_to_local = true
OpenCC 命令 opencc	语言为 simplified-chinese 或 traditional-chinese；最终文本会执行 t2s/s2t 转换
Alibaba API credential 和网络连接	Qwen 实时 ASR 与 Qwen final-pass ASR
OpenAI-compatible API credential 和网络连接	LLM 整理
xclip 和 xdotool	对 XWayland 窗口进行可靠的剪贴板输出与粘贴

Backend 路径有意设为 /usr/bin/voxtype。请勿把它改为 voice-input 本身。

可选功能依赖

• Fcitx5 和 fcitx5-remote：用于输出期间暂时切换到 ASCII 状态。缺少 fcitx5-remote 时，daemon 会跳过这项操作。
• 启用 remote control 的 Kitty、kitty CLI 和 GNU timeout：用于查找当前 Pi/Codex 会话。详见 Agent 上下文。
• Pi：仅在需要 Pi 会话上下文时使用。Makefile 会自动安装对应 extension。
• systemd-creds：用于写入或检查加密 credential。仅使用本地功能时可以不配置 credential。

在全新环境中安装

Makefile 会让 Cargo 严格使用 lockfile。全新机器第一次构建时，Cargo 会按需下载 lockfile 指定的 Rust dependency：

git clone https://github.com/Saco93/voice-input.git
cd voice-input
make enable-service

make enable-service 会执行 release 构建，把文件安装到当前用户的 home 目录，生成两个 service unit，重新加载 systemd 用户管理器，启用 unit 并重启它们。该流程不需要系统级安装。

默认安装位置如下：

~/.local/bin/voice-input
~/.local/share/voice-input/quickshell/
~/.local/share/voice-input/quickshell-settings/
~/.local/share/voice-input/quickshell/shaders/wavy-halo.frag.qsb
~/.local/share/voice-input/fonts/NotoSansSC-Variable.ttf
~/.local/share/voice-input/fonts/OFL-NotoSansSC.txt
~/.local/share/voice-input/config.toml
~/.local/share/voice-input/voice-input.service
~/.local/share/voice-input/voice-input-hud.service
~/.local/share/voice-input/omarchy-hyprland-snippet.conf
~/.local/share/voice-input/omarchy-waybar-snippet.jsonc
~/.config/voice-input/config.toml
~/.config/systemd/user/voice-input.service
~/.config/systemd/user/voice-input-hud.service
~/.pi/agent/extensions/voice-input-session-registry.ts

HUD 和 Settings 会加载内置的 Noto Sans SC 可变字体；如果字体无法加载，则继续使用 Qt 的系统字体 fallback。该字体采用安装目录中附带的 SIL Open Font License。

安装程序会保留已有的 Voice Input config。如果检测到指定位置存在兼容的旧版 Voxtype config 和加密 credential blob，安装程序可以导入它们。请在使用前检查导入的配置。

请确保图形会话的 PATH 包含 ~/.local/bin，因为已安装的 Hyprland 和 Waybar snippet 会按名称调用 voice-input：

export PATH="$HOME/.local/bin:$PATH"

请通过 shell 或 session environment 持久设置该路径；只在一个 terminal 中执行 export 不会影响其他会话。

安装但暂不启用 service

make install
systemctl --user daemon-reload

如果需要先检查或编辑生成的 unit，可以使用以上命令。之后再启动：

systemctl --user enable --now voice-input.service voice-input-hud.service

第一次配置

公开示例默认使用 provider = "local-cli" 和 /usr/bin/voxtype，并且关闭 LLM、Agent 上下文、final pass 和 pre-roll。

通过交互式向导选择稳定的 provider：

voice-input setup model

Model setup wizard 有意不提供实验性的 Qwen-Audio-3 provider。如需试用 Audio3，请打开 Settings，选择 Qwen-Audio-3（实验性），并在保存前单独确认实验功能警告。程序不会自动启用该选项，也不会把它视为稳定默认值。

使用以下命令打开按需启动的 Quickshell Settings 窗口：

voice-input settings

该命令会尽量通过不包含 secret 的 Quickshell IPC 激活已有实例；如果没有可激活的实例，则启动 /usr/bin/qs --daemonize --no-duplicate --path ~/.local/share/voice-input/quickshell-settings。Settings 需要 Quickshell 0.3 或更高版本，并且不作为 systemd service 运行。

Credential replacement field 留空会保留现有的加密 credential。保存时，Settings 只会通过继承的 stdin 把新 key 发送给 Rust backend，后者再通过 stdin 把它传给 systemd-creds。Rust 会验证完整配置，分别以 0700 和 0600 权限创建配置目录和文件，并采用原子替换。Rust 还可以重启 voice-input.service；如果配置持久化已经成功但重启失败，Settings 会单独报告重启错误。

手动编辑配置后，重新启动 daemon：

systemctl --user restart voice-input.service

全部字段请参阅 配置参考；credential 优先级请参阅 安全与隐私。

桌面集成

在 Hyprland 配置中加载已安装的 snippet：

source = ~/.local/share/voice-input/omarchy-hyprland-snippet.conf

仓库提供的 snippet 使用 F8 取消、F9 toggle，并使用 F10 丢弃当前内容后重新开始。该 snippet 不会修改 Omarchy 原有的 Super+Ctrl+X Voxtype 快捷键，同时包含可选的 HUD 移动快捷键。添加后请重新加载 Hyprland。如果需要 hold 模式，可以生成一组配对的 record start 与 record stop binding：

voice-input setup hyprland

查看 Waybar snippet：

voice-input setup waybar

在把它合并到现有 JSONC 之前，请阅读 桌面集成。

验证安装

systemctl --user status voice-input.service voice-input-hud.service
voice-input status
voice-input diagnostics
voice-input record toggle

voice-input diagnostics [--format text|json] 是安全且有明确内容上限的支持诊断报告；与 extended status 不同，它不会包含正常 transcript，也不会包含私有 endpoint 或 model 值。再次执行 toggle 即可停止测试录音。如果不希望输出任何识别文本，请执行 voice-input record cancel。

使用 Qwen realtime 时，请先确认 Alibaba credential，然后重启 daemon。对于实验性 Audio3 provider，可以用预先录制的 16 kHz、单声道、PCM16 WAV 分别测试两个远程 API；以下命令不会启动 daemon，也不会把文本输入其他应用：

voice-input asr stream-test --file sample.wav  # WebSocket 流式识别
voice-input asr test --file sample.wav         # Native 完整音频请求

两个命令都要求当前配置已经选择 Audio3，并明确确认实验功能。它们会把 WAV 上传到解析后的 Regional 路由或完全按原值使用的 Custom endpoint，并且可能产生 Alibaba API 费用。

测试 LLM：

voice-input llm test

该命令要求用户已经启用 LLM refinement，并配置 model 和 credential。

更新或移除

从源代码更新时，请获取新 revision 并重新安装。如果 lockfile 增加了 dependency，Cargo 会按需下载：

git pull --ff-only
make enable-service

更新会替换已安装的 binary、HUD 与 Settings asset、内置 font、编译后的 .qsb、生成的用户级 unit、Hyprland/Waybar snippet、共享 sample file 和 Pi session-registry extension。已有的用户 config.toml 和加密 credential store 会保留。安装程序还会删除旧版本遗留的已安装 hud.py 和 settings.py；HUD 和 Settings 现在都需要 Quickshell。

更新完成后，请关闭并重新打开 Settings，reload Pi 以加载替换后的 extension，并 reload Hyprland 以重新读取替换后的 sourced snippet。voice-input setup waybar 只会输出新安装的 fragment；如果此前把 fragment 复制到了 Waybar JSONC 文件中，请重新合并新版内容并重启 Waybar。

停止并禁用两个 unit：

make disable-service

该 target 只会停止并禁用 service，不会删除安装文件、配置或 credential。请先确定需要保留哪些内容，再手动删除其余文件。

下一步：配置参考 · 桌面集成 · 故障排查