Voxtype whisper.cpp 完整配置指南从零打造 Ubuntu 语音转文字系统作者肖恭伟 |日期2026-08-05 |环境Ubuntu 24.04 GNOME X11 Cursor IDE效果按住 ScrollLock → 说话 → 松开 → 中文自动识别 → 自动粘贴到光标位置难度中等 |预计耗时40 分钟一、写在前面我一直想找一款 Linux 下按一下就开始录音、说完自动转文字、自动粘贴到光标的工具。Windows 下有飞书妙记、“讯飞语记”Mac 下有MacWhisper但 Linux 下一直没有开箱即用的方案。直到发现Voxtype——一个专为 Linux 桌面设计的 push-to-talk 语音转文字工具底层使用whisper.cppOpenAI Whisper 的 C 推理实现。这套方案的核心优势离线运行本地 CPU 推理无需联网低延迟small 模型约 2-4 秒返回结果不抢焦点识别结果通过剪贴板自动粘贴开机自启登录即用无需手动启动本文记录我从零搭建、调试、优化的全过程。即使你之前没接触过 systemd / udev / X11 剪贴板只要按步骤复制粘贴命令40 分钟内可以完成。二、效果展示打开 Cursor IDE光标停在输入框按住 ScrollLock键盘右上角通常用不上的那个键看到屏幕右下角弹出正在录音通知正常说话普通话松开 ScrollLock2-4 秒后识别结果自动出现在光标位置举例我说你好这是一个测试松开 ScrollLock 后输入框会自动出现你好这是一个测试。整个过程不需要复制粘贴不需要切换窗口不抢键盘焦点。三、环境准备3.1 确认系统版本cat/etc/os-release|grepPRETTY_NAME应该输出类似Ubuntu 24.04 LTS。3.2 确认是 X11 会话echo$XDG_SESSION_TYPE必须输出x11。如果输出wayland需要先切回 X11开机登录时点右下角齿轮选 GNOME on Xorg。为什么要 X11Voxtype 通过xdotool模拟 CtrlV 粘贴Wayland 下用wtype替代但配置更复杂本文以 X11 为主线。3.3 记录 DISPLAY 编号echo$DISPLAY记下这个值可能是:0或:1后面写 systemd 配置要用。3.4 准备 sudo 权限后续安装系统包需要 sudo确保当前用户在 sudoers 里sudo-v四、安装基础依赖sudoapt-getupdatesudoapt-getinstall-yxclip xdotoolwgetcurl三个工具的作用工具作用xclipX11 剪贴板读写Voxtype 把识别结果写入剪贴板xdotool模拟键盘按键触发 CtrlV 粘贴wget下载 whisper 模型文件验证安装xclip-versionxdotool--version五、安装 Voxtype5.1 下载 deb 包cd~/Downloadswgethttps://github.com/peteonrails/voxtype/releases/download/v0.7.5/voxtype_0.7.5-1_amd64.deb5.2 安装sudoapt-getinstall-y./voxtype_0.7.5-1_amd64.deb5.3 验证voxtype--version应该输出voxtype 0.7.5或更新版本。六、配置 uinput 设备权限关键Voxtype 需要读取/dev/uinput设备才能监听 ScrollLock 按键事件。默认情况下只有 root 能访问所以我们需要加一条 udev 规则。6.1 创建规则文件sudotee/etc/udev/rules.d/99-uinput-uaccess.rules/dev/nullEOF KERNELuinput, SUBSYSTEMmisc, TAGuaccess, OPTIONSstatic_nodeuinput EOF6.2 重载规则sudoudevadm control --reload-rulessudoudevadm trigger --name-matchuinput6.3 验证权限生效ls-l/dev/uinput输出应该看到你的用户名如david而不是rootcrw------- 1 david david 10, 223 8月 5 20:30 /dev/uinput如果显示 root注销重新登录systemd user instance 会自动获得 uaccess tag。七、下载 Whisper 模型Whisper 模型越大越准但越慢。我推荐small模型466 MB对中文识别准确率和速度的最佳平衡点。7.1 模型对比模型大小中文准确率CPU 推理时间适用场景base142 MB一般~1s英文速记small466 MB好~2-4s中文日常推荐medium1.5 GB很好~8s重要稿件large-v3-turbo1.5 GB极好~10s顶配但慢7.2 下载 small 模型mkdir-p~/.local/share/voxtype/models/wget-c-O~/.local/share/voxtype/models/ggml-small.bin\https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin下载约需 5-15 分钟取决于网速。-c参数支持断点续传。7.3 验证文件完整性ls-lh~/.local/share/voxtype/models/ggml-small.bin必须显示约 466 MB。如果只有几十 MB是下载中断了重新执行 7.2。八、配置 Voxtype8.1 创建配置文件mkdir-p~/.config/voxtypecat~/.config/voxtype/config.tomlEOF # 状态文件 state_file auto # 热键按住 ScrollLock 录音 [hotkey] key SCROLLLOCK modifiers [] # 音频输入 [audio] device default sample_rate 16000 max_duration_secs 60 # whisper 模型配置 [whisper] backend local model small language zh translate false # 强制简体输出不加这行模型偶尔会输出繁体 initial_prompt 简体中文。请使用简体中文输出。 # 输出方式剪贴板 模拟 CtrlV [output] mode clipboard paste_keys LEFTCTRLV post_output_command xdotool key --clearmodifiers ctrlv # 通知 [output.notification] on_recording_start false on_recording_stop false on_transcription true EOF8.2 关键配置说明配置项作用推荐值key SCROLLLOCK录音热键SCROLLLOCK最不冲突model smallwhisper 模型small中文推荐language zh强制中文识别zhinitial_prompt引导解码风格“简体中文。”mode clipboard输出到剪贴板clipboardpost_output_command模拟粘贴xdotool ctrlv8.3 关于initial_prompt这是最重要的优化。Whisper 的language zh默认是简体中文但base/small模型对短句会随机选简/繁体。加上initial_prompt后模型会以 prompt 里的字符集风格继续输出相当于喂给它简体样本。实测不加这个每次约 20% 的概率输出繁体加上后几乎 100% 简体。九、配置 systemd 开机自启9.1 创建服务文件mkdir-p~/.config/systemd/usercat~/.config/systemd/user/voxtype.serviceEOF [Unit] DescriptionVoxtype push-to-talk voice-to-text daemon Documentationhttps://voxtype.io PartOfgraphical-session.target Aftergraphical-session.target [Service] Typesimple ExecStart/usr/bin/voxtype daemon Restarton-failure RestartSec5 EnvironmentXDG_RUNTIME_DIR%t EnvironmentPATH/home/david/.local/bin:/usr/local/bin:/usr/bin:/bin EnvironmentXCURSOR_PATH/usr/share/icons # 关键把下面的 :1 改成你第三节查到的 DISPLAY 值 EnvironmentDISPLAY:1 [Install] WantedBygraphical-session.target EOF9.2 启用服务systemctl--userdaemon-reload systemctl--userenablevoxtype.service systemctl--userstart voxtype.service9.3 验证服务运行systemctl--userstatus voxtype.service --no-pager应该看到● voxtype.service - Voxtype push-to-talk voice-to-text daemon Loaded: loaded (/home/david/.config/systemd/user/voxtype.service; enabled) Active: active (running)十、验证全链路10.1 检查模型加载journalctl--user-uvoxtype-n15--no-pager|grep-imodel loaded应该看到whisper_model_load: type 3 (small) whisper_model_load: model size 487.01 MB INFO Model loaded in 0.21s INFO Model loaded, ready for voice input10.2 检查粘贴链路echo粘贴测试 123|xclip-selectionclipboard xdotool key ctrlv这条命令执行后你应该看到粘贴测试 123被粘贴到终端里。如果没看到说明 X11 权限有问题极少情况。10.3 实际使用打开 Cursor任何需要输入的应用都行光标停在输入框按住 ScrollLock说话“这是一个测试”松开 ScrollLock等待 2-4 秒输入框出现“这是一个测试”第一次按下 ScrollLock 时系统会自动弹出uinput 权限授予对话框部分 GNOME 版本勾选始终允许即可。十一、常见问题排查Q1按 ScrollLock 完全没反应排查# 1. 看服务是否在跑systemctl--userstatus voxtype.service --no-pager# 2. 看 uinput 权限ls-l/dev/uinput# 3. 看日志有没有错journalctl--user-uvoxtype-n30--no-pager最常见原因DISPLAY 编号写错了。把EnvironmentDISPLAY:1改成echo $DISPLAY的实际值。Q2识别结果是繁体字解决确认config.toml里加了initial_prompt 简体中文。请使用简体中文输出。然后systemctl--userrestart voxtype.serviceQ3识别完成但没粘贴到目标应用排查# 手动测试 xdotool 是否能用xclip-selectionclipboard-oxdotool key ctrlv如果手动也不工作检查XAUTHORITY或尝试重启 GNOME。如果手动能工作但 Voxtype 不行在voxtype.service里加EnvironmentXAUTHORITY%t/.XauthorityQ4识别准确率低逐级升级模型# 升级到 mediumsed-is/^model small/model medium/~/.config/voxtype/config.tomlwget-c-O~/.local/share/voxtype/models/ggml-medium.bin\https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin systemctl--userrestart voxtype.service专业术语优化在initial_prompt里加上你的领域词汇initial_prompt GNSS 全球导航卫星系统、精密单点定位、对流层延迟、北斗三号。简体中文。Q5开机自启不生效确认服务已 enablesystemctl--useris-enabled voxtype.service# 应该输出 enabled重启后检查reboot# 登录后systemctl--userstatus voxtype.serviceQ6怎么停用 Voxtype# 临时停用systemctl--userstop voxtype.service# 永久停用取消开机自启systemctl--userdisable voxtype.service# 彻底删除rm~/.config/systemd/user/voxtype.service systemctl--userdaemon-reload十二、性能调优可选12.1 GPU 加速推荐有独显的用户sudoapt-getinstall-yvulkan-tools mesa-vulkan-drivers systemctl--userrestart voxtype.service# 验证 GPU 是否启用journalctl--user-uvoxtype-n30--no-pager|grep-ivulkanGPU 加速可让推理速度提升 3-10 倍。12.2 调整录音时长如果经常录长段口述[audio] max_duration_secs 300 # 5 分钟12.3 LLM 后处理清理口述语气词如果你想自动去除嗯、“那个”、就是说这类语气词sudoapt-getinstall-yollama ollama pull llama3.2:1b修改config.toml[output.post_process] command ollama run llama3.2:1b Clean up this dictation. Remove filler words like 嗯/那个. Output only cleaned Chinese text: timeout_ms 30000 trim true十三、原理简述ScrollLock 按下 ↓ voxtype daemon 监听 /dev/uinput ↓ 开始录音PulseAudio / PipeWire ↓ ScrollLock 松开 ↓ whisper.cpp small 模型 CPU/GPU 推理 ↓ initial_prompt 引导 → 简体中文解码 ↓ 识别结果写入剪贴板xclip ↓ post_output_commandxdotool 模拟 CtrlV ↓ 目标应用接收粘贴为什么用剪贴板而不是直接 type 模拟键盘直接 type 在某些应用Chrome 输入框、远程桌面、部分 X 应用会丢字剪贴板 模拟 CtrlV 让应用自己处理粘贴兼容性最好为什么用 systemd --userVoxtype 需要访问用户的 X server 和 PulseAudio放在用户态服务由 GDM 登录后自动拉起不需要 root符合 Linux 桌面最佳实践十四、文件位置速查/etc/udev/rules.d/99-uinput-uaccess.rules uinput 权限 ~/.config/systemd/user/voxtype.service 开机自启 ~/.config/voxtype/config.toml Voxtype 主配置 ~/.local/share/voxtype/models/ggml-small.bin whisper 模型 /usr/bin/voxtype 主程序十五、写在最后这套方案我用了两个月每天写代码、写文档、回邮件全靠它。最大的好处是解放双手——尤其是写论文、起草邮件这类长文本任务。如果你在配置过程中遇到本文没覆盖的问题可以看 Voxtype 日志journalctl --user -u voxtype -f看 Voxtype 官方文档https://voxtype.io留言讨论配置过程中最重要的是三处✅ DISPLAY 编号写对第三节查第九节配置✅initial_prompt加简体引导第八节✅ uinput 权限生效第六节重启后生效祝你装机愉快