Desktop Integration.zh CN

桌面集成

English · 首页

Hyprland 控制

Voice Input 本身不会捕获按键。Hyprland 会运行简短的 client command，并由这些命令连接 daemon control socket。

加载已安装的 snippet：

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

其中主要 binding 使用 toggle 模式：

bindd = SUPER CTRL, X, Voice input, exec, voice-input record toggle

当 release event 不可靠时，toggle 更稳定。每个 toggle client 都会附加 request timestamp；如果请求在 finalization 阶段之后排队超过 750 ms，daemon 会忽略它。

如果需要 push-to-talk，请把按下和释放配对：

bind = SUPER CTRL, X, exec, voice-input record start
bindr = SUPER CTRL, X, exec, voice-input record stop

Hyprland 必须能够收到 release。多 modifier 组合无法可靠触发 release 时，请改回 toggle。hotkey.mode 不会自行安装 binding；以下命令会根据该字段生成配置：

voice-input setup hyprland

取消当前录音且不输出文本：

voice-input record cancel

Quickshell HUD

主 HUD 由独立 service 运行：

systemctl --user status voice-input-hud.service
systemctl --user restart voice-input-hud.service

Unit 会运行：

/usr/bin/qs --no-duplicate --path ~/.local/share/voice-input/quickshell

它设置 XDG_RUNTIME_DIR=%t，为每个 screen 创建一个 PanelWindow variant，只在当前 focused Hyprland monitor 上显示。Surface 位于 overlay layer，不请求 keyboard focus，不占用 exclusive zone，并从完整 input mask 中减去自身区域，因此不会接收点击。

HUD 数据路径

$XDG_RUNTIME_DIR/voice-input/state.json
$XDG_RUNTIME_DIR/voice-input/waveform.sock

StateStore.qml 每 50 ms 读取一次原子更新的 JSON state。Quickshell local socket 独立接收 newline-delimited waveform frame；连接断开后每 400 ms 尝试重连。较长的 transcript 最多显示约五行，并向上移动完整文本，使最新内容保持可见。

Daemon service 会设置 VOICE_INPUT_EXTERNAL_HUD=1，从而阻止 daemon 启动旧版 Python HUD。因此：

• 重启 daemon 不会重启 Quickshell；
• HUD crash 不会停止 ASR 或文本输出；
• [hud].enabled = false 不会关闭单独启用的 HUD service；如需关闭，请 stop/disable voice-input-hud.service；
• [hud].margin_bottom 和 [hud].height 当前用于 Python fallback；Quickshell 实现直接使用 72 和 56。

主题

Quickshell 会读取：

~/.config/omarchy/current/theme/colors.toml

它把 accent、foreground、color3、color5 和 color1 映射为不同 phase 的颜色。无法读取或解析文件时，它会保留内置颜色。该主题文件不是必需依赖。

HUD 位置

当前位置和偏移会保存在 config 与 runtime state 中：

voice-input hud position bottom-left
voice-input hud move right
voice-input hud move up 12
voice-input hud center
voice-input hud reset

• move 未指定数值时使用 [hud].nudge_step。
• X 正值向右；Y 正值让 HUD 上移。
• center 选择 bottom-center 并只清除 X。
• reset 选择 bottom-center 并清除两个 offset。

建议使用的可选 binding：

bind = SUPER CTRL ALT, left,  exec, voice-input hud move left
bind = SUPER CTRL ALT, right, exec, voice-input hud move right
bind = SUPER CTRL ALT, up,    exec, voice-input hud move up
bind = SUPER CTRL ALT, down,  exec, voice-input hud move down
bind = SUPER CTRL ALT, c,     exec, voice-input hud center

Waybar

随附 JSONC fragment 定义了 custom/voice-input：

voice-input setup waybar

其中执行：

voice-input status --follow --format json --extended

status --follow 每 250 ms 检查一次 state，并且只在 payload 发生变化时输出。Snippet 根据 phase class 显示 icon；右键打开 Settings，左键打开 model setup wizard。

请把该 object 合并到 Waybar config，并将 custom/voice-input 加入所需的 module list。Setup command 只会输出 fragment，不会编辑现有 Waybar file，也不会重启 Waybar。

Wayland 与 XWayland 输出目标

开始录音时，CLI 会询问 Hyprland 当前窗口是否属于 XWayland，并把结果作为 hint 发送给 daemon。输出时，daemon 会再次查询。如果开始时的 hint 或当前目标任意一个为 XWayland，程序都会走 XWayland 路径。

目标	直接输入	Clipboard	Paste
Wayland	wtype	wl-copy	wl-copy + wtype 按键
XWayland	明确允许时使用 wtype	xclip	xclip + xdotool

默认的 prefer_paste_for_xwayland = true 会避免在 XWayland 中直接输入。Wayland 文本超过 120 个字符时也会从 type 切换到 paste。Paste 会备份并恢复目标 clipboard；clipboard 模式只执行复制。

Hyprland discovery 会优先连接 command socket，失败后调用 hyprctl。程序可以从 systemd 用户管理器环境中读取 HYPRLAND_INSTANCE_SIGNATURE、WAYLAND_DISPLAY、DISPLAY 和 XDG_RUNTIME_DIR。如果 service 无法访问 session，请在图形会话启动时更新 systemd 用户环境，然后重启 service；不要硬编码其他用户的 runtime path。

旧版 Python HUD

当 VOICE_INPUT_EXTERNAL_HUD 不存在或值为 false，并且 [hud].enabled = true 时，daemon 可以在非 idle 状态启动 assets/hud.py。该脚本需要 Python GTK4 和 Gtk4LayerShell，并可能使用 layer-shell preload library。它读取相同的 state 和 waveform 路径。标准安装 service 会明确禁用它，并使用 Quickshell。

另请参阅：故障排查 · 配置参考