Vocalinux 是一款免费、开源、100% 离线的 Linux 语音听写工具：按住快捷键说话，转写文字会自动输入到当前焦点窗口。它基于 whisper.cpp、Whisper 与 VOSK 等本地引擎，支持 GPU 加速，同时兼容 X11 与 Wayland，无需注册任何账号。本文面向新手，带你在 Ubuntu、Debian、Fedora 上用 3 种方式完成 Vocalinux 语音听写的安装与首次配置。

安装前快速自查：系统要求

开始之前，先对照 docs/INSTALL.md 中的要求确认系统版本：

💡 注意：Ubuntu 22.04（Python 3.10）和 Debian 11（Python 3.9）不满足 Python 3.11 的最低要求，不在支持范围内。完整的发行版兼容矩阵见 docs/DISTRO_COMPATIBILITY.md。

方式一：官方安装脚本一键安装（推荐）

官方交互式安装脚本 install.sh 是大多数用户的最优解：它会自动检测发行版和硬件、安装系统依赖、下载语音模型并配置桌面集成，全程约 1–2 分钟。

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/vo/vocalinux cd vocalinux

第 2 步：运行安装脚本

./install.sh

脚本执行时会让你选择引擎。不熟悉的直接选默认whisper.cpp即可——它是官方默认引擎，支持 AMD / Intel / NVIDIA 的 Vulkan GPU 加速，体积小巧（tiny 模型约 74MB）。

不想手动选择时，可用非交互模式直接走默认配置：

./install.sh --auto

各引擎适合什么场景？参考下表（来自 docs/INSTALL.md）：

安装脚本完成后会自动：创建独立 Python 虚拟环境（不污染系统）、下载默认语音模型（带校验和验证）、安装图标与桌面菜单项。

方式二：官方 .deb / .rpm 发行版包安装

如果你更习惯用系统包管理器管理软件，可以直接从官方 Release 页面下载对应架构的.deb（Debian / Ubuntu）或.rpm（Fedora）包，本地安装：

# Ubuntu / Debian（amd64） sudo apt install ./vocalinux_*_amd64.deb # Fedora（x86_64） sudo dnf install ./vocalinux-*.x86_64.rpm

这是"薄包"设计：Python、GTK、PyGObject 等基础库由发行版仓库提供，apt/dnf会自动解析，只有pywhispercpp和pynput两个依赖随包自带。两点提醒：

• 包内 whisper.cpp 运行在CPU模式，且没有自动更新——新版本需要重新安装包；
• 包安装无法帮你处理 Wayland 下的键盘权限，建议见下文"常见坑"部分。

方式三：从源码安装（开发者 / 定制需求）

想跟进最新功能或参与开发时，直接基于源码安装：

git clone https://gitcode.com/gh_mirrors/vo/vocalinux cd vocalinux ./install.sh

需要边装边调试时，可用开发模式安装（附带测试工具）：

./install.sh --dev

另一种选择是 PyPI 安装：pip install vocalinux。但请注意，pip 只能装 Python 部分，GTK、托盘、音频、文本注入等系统级依赖必须先用发行版包管理器装好，完整命令清单见 docs/INSTALL_MANUAL.md。对新手来说，方式一已把这一切包办，更省心。

首次启动与基础设置

安装完成后，在终端运行vocalinux，或直接从应用菜单启动 Vocalinux：

默认使用Push-to-talk（按住说话）模式：

1. 按住右 Alt 键开始说话；
2. 松开按键，文字自动输入到当前焦点应用。

语音引擎与模型可在Settings → Speech Model中调整，简单模式只需选择语言与精度偏好，高级选项里再切换引擎、模型大小和量化版本：

日常使用强烈建议在Settings → Application中打开Start on Login，让 Vocalinux 随桌面会话自动启动（基于 XDG autostart，不安装 systemd 服务）：

常见坑与快速排障

• Wayland 下快捷键没反应：全局热键需要读取键盘设备，把你的用户加入input组后重新登录：

  sudo usermod -aG input $USER

• KDE Plasma Wayland 大小写错乱：在 系统设置 → 键盘 → 虚拟键盘 中选择IBus Wayland，这是最可靠的文本注入路径。

• 找不到托盘图标 / 麦克风无声：先查 docs/TROUBLESHOOTING.md，覆盖托盘、音频、文本注入等高频问题。

• 确认版本与更新：在 设置 → About 页面可查看当前版本，并点击 Check 检查 Stable / Nightly 渠道是否有新构建：

小结

三种方式任选其一即可：

1. 安装脚本（方式一）：最省心，自动装依赖、下模型、配桌面；
2. .deb/.rpm包（方式二）：贴合系统包管理习惯，适合 Ubuntu / Debian / Fedora 用户；
3. 源码 / PyPI（方式三）：适合开发者和高级用户。

装好后，按住右 Alt 说句话，看看文字是否"自动敲进"你的编辑器——恭喜，Vocalinux 语音听写已经在工作了。更多用法（语音命令、模型切换、多语言识别）可继续阅读 docs/USER_GUIDE.md。