Desktop Integration.zh CN

桌面集成

English · 首页

Hyprland 控制

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

加载已安装的 snippet：

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

默认控制集中在相邻的功能键上。Snippet 不会修改 Omarchy 原有的 Super+Ctrl+X Voxtype 快捷键：

binddp = , F8, Cancel voice input, exec, voice-input record cancel
binddp = , F9, Toggle voice input, exec, voice-input record toggle
binddp = , F10, Restart voice input, exec, bash -lc 'voice-input record cancel && voice-input record start'

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

如果需要 push-to-talk，请把 F9 toggle 替换为按下和释放 binding：

bind = , F9, exec, voice-input record start
bindr = , F9, exec, voice-input record stop

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

voice-input setup hyprland

可以取消当前录音且不输出文本，也可以丢弃当前 session 后立即重新开始：

voice-input record cancel
voice-input record cancel && voice-input record start

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 在活动 phase 中每 50 ms 读取一次原子更新的 JSON state，在 idle 状态下则每 100 ms 读取一次。Quickshell local socket 独立接收 newline-delimited waveform frame；连接断开后每 400 ms 尝试重连。较长的 transcript 使用锚定到最新文本的四行 viewport，并通过边缘渐隐处理较早的内容。

顶部边缘光晕在全部活动 pipeline 中使用同一个频谱包络 renderer。Listening 在说话时会显示 12 个实时麦克风频段；在说话前和停顿期间则显示平缓的虚拟频谱，其延伸距离与 processing 相同。Finalizing、Refining 和 Sending 共用一段持续推进的虚拟频段动画；这些 phase 切换时只会对整个光晕执行颜色 crossfade，不会重置几何轮廓、运动 phase、节奏或亮度，也不会产生移动的颜色边界。session 结束时的 waveform reset 不会立即清空最后一个实时帧；HUD 会等到 runtime snapshot 进入 idle 后再清空。Listening 会通过一次短暂衰减到约 5% 光晕可见度再恢复的过程，把该帧交接给 Finalizing；capsule 本身会始终保持可见。过渡进度会和 phase 变化同步重置，不会等到下一帧动画才重置，因此目标 processing 轮廓不会在 crossfade 之前闪现。

同一个 capsule 的内部底部增加了一行状态栏，并通过增高 capsule 保持原有 transcript viewport 不变。左侧会把 runtime phase 映射为 Arming、Listening、Finalizing、Refining、Sending 或 Error；右侧以 MM:SS 显示有效录音时长。只有 capture 和 ASR 都准备完成，并且 phase 进入 recording 后，daemon 才会开始计时；接受停止请求时会冻结时长。Finalization 及后续阶段继续显示冻结后的数值，因此 arming 和处理阶段的等待时间不会计入录音时长。

HUD 仅使用 Quickshell，并且与识别流程相互独立：

• 重启 daemon 不会重启 Quickshell；
• HUD crash 不会停止 ASR 或文本输出；
• [hud].enabled = false 会隐藏 HUD surface，同时常驻 service 可以继续运行；如需移除该 process，请 stop/disable voice-input-hud.service；
• 每个 state snapshot 都包含 hud_enabled、hud_margin_bottom、hud_height、hud_position、hud_offset_x 和 hud_offset_y，Quickshell 会应用这些值。

主题

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

Quickshell Settings

Settings 使用另一套 Quickshell 配置，并且与常驻 HUD 分开：

~/.local/share/voice-input/quickshell-settings

通过以下命令打开：

voice-input settings

该命令会先通过不包含 secret 的 Quickshell IPC 激活已有的 voiceInputSettings instance。如果没有可激活的实例，则启动：

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

这套配置会创建普通 FloatingWindow，而不是 layer-shell panel；窗口关闭后进程会退出。Settings 按需运行，并且没有 systemd unit。随附的 Hyprland snippet 会让 Voice Input Settings client 浮动并居中，使 compositor 采用窗口请求的 900 × 620 工具窗口尺寸，而不会把它平铺到整个 workspace。

全高度导航包含 Overview、Speech、Refinement、Output、Appearance 和 Hotkey & state。Overview 只读显示本地 service 报告，以及当前 Speech、Refinement、Output 和 Appearance 配置的摘要。详细页面采用带有清晰分隔线的扁平桌面表单区域，不再使用多层 dashboard card。Provider 专属字段会按条件显示，技术参数则保留在相关页面的可展开高级设置区域中；隐藏字段仍保留在完整配置草稿中。Header 会显示未保存状态，并提供语言菜单、位于 overflow 菜单中的 Reload settings 操作和 Close 按钮。

QML 会启动一个专用 Rust child backend，并通过 stdin/stdout 传输带版本号的 NDJSON。QML 不会直接写入 TOML 或 credential。runtime.get 只会向 Overview 返回允许公开的 service 与 runtime metadata；该状态与配置保存状态相互独立，也不会宣称 provider 已经连通。

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。

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