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	查找活动窗口和显示器，并判断输出目标类型
wtype	在 Wayland 中直接输入，以及模拟粘贴按键
wl-copy、wl-paste	Wayland 粘贴、剪贴板备份和恢复
systemd 用户会话	运行 daemon/HUD service，并加载加密 credential
可通过 /usr/bin/qs 启动的 Quickshell 0.3 或更高版本	常驻 HUD 和按需启动的 Settings

不同发行版的 package 名可能不同，请直接检查命令：

command -v cargo make pw-record hyprctl wtype wl-copy wl-paste systemctl qs

特定配置所需的依赖

依赖	需要它的情况
/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 以 offline 模式构建。因此，全新机器需要先获取一次 lockfile 指定的 Rust dependency：

git clone https://github.com/Saco93/voice-input.git
cd voice-input
cargo fetch --locked
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/
~/.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

安装程序会保留已有的 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

也可以打开按需启动的 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 使用 Super+Ctrl+X toggle 模式，并包含可选的 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 record toggle

再次执行 toggle 即可停止测试录音。如果不希望输出任何识别文本，请执行 voice-input record cancel。

使用 Qwen realtime 时，请先确认 Alibaba credential，然后重启 daemon。测试 LLM：

voice-input llm test

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

更新或移除

从源代码更新时，请获取新 revision 和 lockfile 对应的 dependency，然后重新安装：

git pull --ff-only
cargo fetch --locked
make enable-service

更新后请 reload Pi，使其加载已替换的 session-registry extension。安装程序还会删除旧版本遗留的已安装 hud.py 和 settings.py；HUD 和 Settings 现在都需要 Quickshell。

停止并禁用两个 unit：

make disable-service

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

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