Omarchy 屏幕文字提取与 AI 语音听写实战：框选 OCR 取词与 Voxtype 语音输入全指南

本指南聚焦 Omarchy（Beautiful, Modern & Opinionated Linux）中两个相辅相成的“把非文本内容变成文字”的能力：一是用 Super + Ctrl + PrtScr 框选屏幕区域、由 Tesseract OCR 引擎把图像文字识别到剪贴板；二是基于 Voxtype（AI 语音转写）的全程本地语音听写，通过按住 F9 或 Super + Ctrl + X 把所说的话直接输入到当前聚焦的输入框。读完你将掌握这两条功能的快捷键、底层命令行链路、配置模板的完整参数含义，以及如何在 Omarchy 的菜单、Hyprland 键位和顶栏状态指示器层面定制它们。

功能定位：一条“外部文字进入系统”的输入管道

日常工作中最常遇到的两种麻烦是：图片里有文字却无法复制（网页横幅里的电话号码、图片页脚的地扯、截图中的报错信息），以及手上忙时想说话而不是打字。Omarchy 把这两个场景分别封装为“屏幕文字提取”与“语音听写”，统一把它们送入系统中最顺手的两个终点：

• OCR 结果直接写入剪贴板，随后用统一的剪贴板历史（Super + V）粘贴；
• 听写文本则由模拟键盘直接“敲”进当前聚焦的输入区域，也可配置为写剪贴板。

两者的官方说明见 manual/11-text-extraction-dictation.md，完整快捷键总览可参考 manual/07-hotkeys.md。

屏幕文字提取：Super + Ctrl + PrtScr 背后的完整 OCR 链路

触发与用法

按 Super + Ctrl + PrtScr，屏幕会进入区域选择状态；划出想要识别的区域后，Tesseract 开源 OCR 引擎会快速把该选区识别成文本并放入剪贴板，接着按 Super + V 即可粘贴。典型场景正如官方文档 manual/11-text-extraction-dictation.md 所述：提取图片页脚中的地址、网页标题里嵌入的号码等无法直接选中的文字。

从 Hyprland 键位到底层脚本

这条快捷键并不只是调用某个“魔法”工具，而是由一段可读的 Bash 脚本串联出标准 Wayland 截图 + OCR 管线。核心实现位于 bin/omarchy-capture-text，其流程为：

1. 启动 hyprpicker -r -z 把屏幕画面“冻结”住（注释明确说明：保持 hyprpicker 存活直到 grim 完成拍摄，让截图看到的是冻结的覆盖层，而不是收起选择框时仍在变化的内容），并通过 trap 在退出时清理；
2. 用 slurp 让用户划选区域，得到形如 x,y,w,h 的选区描述，未选择则直接退出；
3. 用 grim -g "$SELECTION" 截取该区域并通过管道直接喂给 tesseract，无需中间临时文件：

   TEXT=$(grim -g "$SELECTION" - | tesseract stdin stdout \
     --oem 1 --psm 6 -l "${OMARCHY_OCR_LANGS:-eng}" \
     --dpi 300 -c preserve_interword_spaces=1 2>/dev/null) || exit 1
   

4. 识别成功后，用 wl-copy 写入剪贴板，并调用 omarchy-notification-send 弹出“Copied text from selection to clipboard”提示。

这条管线里几个参数直接决定了识别质量，值得展开说明：

参数	作用与取值
--oem 1	使用 LSTM（神经网络）OCR 引擎模式，识别准确率明显高于传统引擎
--psm 6	Page Segmentation Mode 6，假定文本为均匀块状，适合普通屏幕截图段落
--dpi 300	以 300 DPI 输入，弥补截图像素密度不足导致的识别率下降
-l "${OMARCHY_OCR_LANGS:-eng}"	识别语言，默认 eng；可通过环境变量 OMARCHY_OCR_LANGS 覆盖（例如设为 chi_sim 识别简体中文）
-c preserve_interword_spaces=1	保留词间空格，避免英文识别结果被粘连

除了按快捷键，该功能在 omarchy CLI 的捕获分组（omarchy:group=capture）下也有入口（脚本头部元数据给出示例 omarchy capture text），适合放进自定义工作流脚本。区域选择流程还复用了 Omarchy 统一的截图组件，相关周边实现可对照 bin/omarchy-capture-region、bin/omarchy-capture-screenshot 等脚本。

想改键位或改语言怎么办

Omarchy 将个人键位定制收敛在 config/hypr/bindings.lua（用户专属覆盖层）。文件头部注释提供了三类操作的模板：

• o.bind("SUPER + SHIFT + R", "SSH", ...) 新增绑定；
• o.rebind(...) 覆盖默认绑定（示例中即把截图类操作换成其他按键：o.bind("SUPER + SHIFT + S", nil, "omarchy-capture-screenshot")）；
• hl.unbind("SUPER + SHIFT + B") 移除默认绑定。

若需要识别其他语言，在用户 shell 配置中导出 OMARCHY_OCR_LANGS（如 chi_sim+eng），无需改动仓库内的默认脚本。

AI 语音听写：Voxtype 的安装、键位与配置

从“安装向导”到首次使用

Omarchy 官方文档 manual/11-text-extraction-dictation.md 明确说明：Omarchy 通过 Voxtype 提供 AI 语音听写。安装入口在 Omarchy 菜单的 Install > AI > Dictation（对应菜单定义见 default/omarchy/omarchy-menu.jsonc 中 install.ai.dictation 一项，安装前会以 omarchy-pkg-present voxtype-bin 判断并置灰）。

安装动作的真实执行体是 bin/omarchy-voxtype-install，它会依次完成：

1. 用 gum confirm 征询是否“Install Voxtype + AI model (~150MB)”，即默认英文 base 模型的体积约 150MB；
2. 安装软件包 wtype（Wayland 键盘注入，供“打字输出”模式使用）与 voxtype-bin；
3. 把发行版预设配置 default/voxtype/config.toml 复制到用户目录 ~/.config/voxtype/config.toml；
4. 执行 voxtype setup --download --no-post-install 下载模型并初始化；
5. GPU 加速检测：若 omarchy-hw-vulkan 判定硬件支持 Vulkan，则自动执行 voxtype setup gpu --enable（失败不阻塞安装，|| true 兜底）；
6. 注册 systemd 用户服务（voxtype setup systemd），随后 hyprctl reload 重载键位并重启 Omarchy shell，让顶栏听写指示器生效。

首次使用系统还会通过 install/user/first-run/install-voxtype.hook 弹出一次高优级的安装邀请通知，点击即可在浮动终端中拉起上述安装流程，属于 Omarchy “first-run 引导”机制的一部分。

安装完成后，按住 F9 说话（push-to-talk），松开即结束；或按 Super + Ctrl + X 开/关持续录音。识别出的文本会出现在当前聚焦的输入区域。

键位是如何按需注册的

默认键位并不写死在 Hyprland 全局配置里，而是以“命令存在才绑定”的方式加载。default/hypr/bindings/voxtype.lua 中：

if o.cmd_present("voxtype") then
  o.bind("SUPER + CTRL + X", "Toggle dictation", "voxtype record toggle")
  o.bind("F9", "Start dictation (push-to-talk)", "voxtype record start")
  o.bind("F9", "Stop dictation (push-to-talk)", "voxtype record stop", { release = true })
end

可见三个细节：

• F9 按下绑定 voxtype record start，release = true 的绑定在松键时执行 voxtype record stop，从而形成“按住说话、松开结束”；
• 绑定被 o.cmd_present("voxtype") 守卫，未安装 voxtype 时这些键位不会占用，避免键位冲突；
• 这套默认键位随 default/hypr/omarchy.lua 中的 omarchy_default_bindings 开关整体装载（require("default.hypr.bindings.voxtype")），如需自定义，遵循 config/hypr/bindings.lua 中的 o.bind/o.rebind 模板即可。

历史迁移方面，migrations/1784767406.sh 表明旧版本曾把 Voxtype 开关做成独立的 Hyprland toggle 文件（$HOME/.local/state/omarchy/toggles/hypr/voxtype.lua），现版本已废弃该 toggle 并统一为上面的条件绑定方式——如果你的配置来自旧版本，升级迁移会自动清理。

换模型与换语言：voxtype setup model

官方文档指出默认加载约 150MB 的基础英文模型，但可以运行 voxtype setup model 自行更换。Omarchy 为此提供了菜单级封装 bin/omarchy-voxtype-model：它会在浮动终端中打开 voxtype setup model 交互界面并重启 shell，让顶栏状态恢复。wtype 依赖与配置修改同样可在该配置界面完成（见 bin/omarchy-voxtype-config 调用的 voxtype configure）。

配置模板逐项拆解：~/.config/voxtype/config.toml

安装脚本会把发行版维护的模板 default/voxtype/config.toml 落到用户目录 ~/.config/voxtype/config.toml。该模板注释详尽，几乎覆盖 Voxtype 全部可调项，是学习其行为的最佳起点，核心字段整理如下：

全局与热键

键	默认值	说明
state_file	"auto"	供外部集成（Waybar/polybar/顶栏指示器）读取的状态文件；auto 落到 $XDG_RUNTIME_DIR/voxtype/state，可给自定义路径或 "disabled" 关闭。守护进程会在状态切换时写入 idle / recording / transcribing。voxtype record toggle 与 voxtype status 依赖它
[hotkey] enabled	false	Voxtype 自带热键开关，模板注释说明默认热键已交由 Hyprland 管理（Super + Ctrl + X），故关闭内置热键以避免双重触发

音频采集 [audio]

键	默认值	说明
device	"default"	输入设备，可用 pactl list sources short 列出候选后指定
sample_rate	16000	采样率，Whisper 期望 16kHz
max_duration_secs	60	单次最长录音秒数，属于安全上限
pause_media	true	录音期间暂停 MPRIS 媒体播放，避免回声与背景音干扰
[audio.feedback]（可选）	—	录音开始/结束提示音：enabled、theme（default/subtle/mechanical 或自定义主题目录）、volume（0.0–1.0）

Whisper 模型与语言 [whisper]

键	默认值	说明
model	"base.en"	可选 tiny / tiny.en / base / base.en / small / small.en / medium / medium.en / large-v3 / large-v3-turbo；.en 后缀为纯英文模型，更快且英文更准；large-v3-turbo 比 large-v3 快且精度损失小（GPU 推荐）；也支持绝对路径指向自定义 .bin 模型
language	"en"	"en" 固定英文，"auto" 自动检测
translate	false	是否把非英语语音翻译成英语
threads	（省略）	CPU 推理线程数，省略则自动探测

输出行为 [output]

键	默认值	说明
mode	"type"	type：在光标处模拟键盘输入（Omarchy 安装脚本会一并安装 wtype）；clipboard：写入剪贴板（依赖 wl-copy）
fallback_to_clipboard	true	打字失败时自动回退到剪贴板
type_delay_ms	1	逐字符输入间隔毫秒数；0 为最快，若出现丢字可调大
[output.post_process]（可选）	—	把转写文本经外部命令（如 ollama run llama3.2:1b）清洗后再输出，用于语法修正、去口头禅；任一侧失败（超时/报错）都回退到原始转写，示例带 timeout_ms = 30000
[output.notification]	三项均 false	是否在开始录音、停止录音、转写完成时弹出通知

文本后处理 [text]（可选）

• spoken_punctuation = false：开启后可直接说 “period” 得到英文句号等标点；
• replacements = { "hyperwhisper" = "hyprwhspr" }：自定义词替换（大小写不敏感），适合纠正模型对专有名词、技术术语的拼写。

需要注意：安装脚本落盘的是发行版模板，之后的个性化修改应在用户侧 ~/.config/voxtype/config.toml 中进行；模板同时注明所有设置都可用 CLI 参数临时覆盖。

顶栏指示器：从“看不见”到“看得见”

Omarchy 顶栏会常驻一个听写指示器，实现在 shell/plugins/bar/indicators/Dictation.qml：

• 它通过 bash -c "omarchy-voxtype-status" 持续跟随状态，而 bin/omarchy-voxtype-status 内部以 exec setpriv --pdeathsig TERM voxtype status --follow --extended --format json 把 voxtype 状态流式转成顶栏友好的 JSON（setpriv --pdeathsig TERM 保证 shell 重启时跟随进程被回收，不残留孤儿进程）；
• 状态机映射：idle 时不显示激活图标（灰显麦克风占位）；recording 时图标切为活跃麦克风；transcribing 时图标切换为转写中符号，tooltip 同步显示当前状态；
• 点击该指示器会打开 Voxtype 配置：root.bar.run("omarchy-voxtype-config")，即拉起 bin/omarchy-voxtype-config 中的 voxtype configure 浮动终端会话。

卸载与回退

无需该功能时，可从菜单 Remove > AI > Dictation 走卸载路径（菜单项 remove.ai.dictation，动作对应 omarchy-voxtype-remove），卸载后由于键位受 o.cmd_present("voxtype") 守卫，F9 与 Super + Ctrl + X 会自动让位，不会残留失效绑定。

常见问题与适用前提速查

• OCR 语言不对：默认只启用 eng；设置环境变量 OMARCHY_OCR_LANGS（例如 chi_sim+eng）后即可识别其他语言。该变量在 bin/omarchy-capture-text 中以 ${OMARCHY_OCR_LANGS:-eng} 形式被消费。
• 想用英语以外的听写：把 ~/.config/voxtype/config.toml 的 language 改为 "auto"，并按需通过 voxtype setup model 换成多语言模型；纯 .en 模型对英语更快更准但对其他语言不适用。
• 转写文字没有落到输入框：确认 output.mode 是否仍为 type，且 wtype 可用；fallback_to_clipboard = true 时结果会退到剪贴板，可用 Super + V 从剪贴板历史粘贴。
• GPU 是否被利用：安装脚本只在 omarchy-hw-vulkan 通过时执行 voxtype setup gpu --enable，可在配置界面复核 GPU 状态；纯 CPU 下建议选用 base/small 级别模型或调大 threads。
• 两条功能共同的“终点”：OCR 结果走 wl-copy 进剪贴板、听写可切剪贴板模式，两者都可与 Omarchy 的统一剪贴板历史无缝衔接（参见 manual/08-unified-clipboard-history.md 与 Super + V）。

文本提取与语音听写共同构成了 Omarchy 上“把外部信息变成可编辑文本”的完整通路：前者把静态的像素文字搬进剪贴板，后者把你的声音实时变成输入框里的文字。掌握 bin/omarchy-capture-text 的 OCR 参数、default/voxtype/config.toml 的字段语义，以及 config/hypr/bindings.lua 的定制入口后，你便可以在不触碰系统默认实现的前提下，把这两条输入通道完全调整成贴合自己语言与键位习惯的形态。