1. 项目概述解放双手的全局语音输入工具作为一名长期与代码和文档打交道的开发者我一直在寻找一种能让我在思考时双手不离开键盘又能高效输入文字的方法。传统的语音输入工具要么绑定在特定应用里要么需要频繁切换窗口打断工作流。直到我遇到了 Murmur一个开源的全局“一键说话”语音转录工具它彻底改变了我的输入习惯。简单来说Murmur 让你在任何应用、任何窗口下只需按住一个键比如 F12说话松开后你说的话就会像打字一样出现在当前光标位置。无论是向 Claude Code 提问、在 VS Code 里写注释、在浏览器搜索框输入还是在终端里敲命令都无需复制粘贴或切换焦点。它的核心价值在于实现了真正的“零上下文切换”。你的思维是连续的操作也应该是连续的。当你正在终端调试突然想到要给代码加个注释传统方式需要你切到编辑器可能还要手动激活语音输入。而有了 Murmur你的手不用离开键盘眼睛不用离开当前窗口按住键说完注释就写好了。这对于追求极致效率的开发者、需要大量文字输入的内容创作者甚至是因重复性劳损RSI而希望减少打字的用户来说都是一个革命性的生产力工具。2. 核心设计思路与架构解析2.1 为何选择“全局”与“一键”模式市面上的语音转文本方案很多但 Murmur 的设计哲学非常明确无侵入、零干扰、极低延迟。它没有自己的界面不接管你的任何应用只是作为一个系统级的后台服务Daemon默默运行。这种设计避免了“另一个需要管理的应用”带来的心智负担。“一键说话”Push-to-Talk模式是其交互设计的精髓。相比于“唤醒词”模式比如“Hey Siri”一键触发有几个显著优势精准控制你明确知道录音何时开始、何时结束避免了误触发或背景噪音被录入的尴尬。在办公室或开放环境尤其重要。隐私性只有在你按住键的时候麦克风才会拾音并发送到云端。你不会担心它一直在“监听”。低延迟从松开按键到文字出现整个过程通常在1秒以内感觉就像敲击键盘的延迟几乎没有等待感。这种设计本质上是在你的键盘和操作系统之间插入了一个高效的“语音输入法”但它比输入法更底层、更通用。2.2 技术栈选型与跨平台考量Murmur 的技术选型清晰地反映了其目标在 macOS 和 LinuxWayland上提供原生般的体验。热键监听在 Linux 上它使用evdev直接读取原始键盘事件这需要input用户组权限。这种方式能捕获所有全局按键即使应用全屏或处于后台。在 macOS 上则使用pynput库并通过系统的“辅助功能”权限来实现全局监听。这两种方案都是各自平台上实现全局热键最可靠的方式。文本注入这是模拟键盘输入的关键。Linux 上依赖ydotool这是一个强大的命令行自动化工具可以模拟键盘和鼠标事件。macOS 则使用pynput或原生的CGEvent。对于更复杂的场景如注入到后台的tmux会话Murmur 实现了专门的tmux注入器直接通过tmux的命令行接口发送文本这实现了真正的“后台自动化”。语音转录核心目前默认且唯一集成的后端是AssemblyAI的流式转录 API。这个选择很务实高准确度AssemblyAI 在英文转录准确度上第一梯队对开发领域的专有名词、代码术语识别较好。流式处理支持边说边转可以实现“松开按键即出文字”的低延迟体验。多语言支持支持超过90种语言方便非英语母语用户或多语言环境。免费额度新用户有50美元免费额度对于个人日常使用来说足够用上很久。配置管理采用简单的 JSON 配置文件~/.config/murmur/config.json并支持热重载。这意味着你修改配置后无需重启守护进程下一次按键触发时就会生效非常方便。注意由于依赖evdev和ydotoolMurmur 目前仅支持 LinuxWayland 合成器和 macOS。Windows 和 X11 暂不支持主要是因为缺乏同等简洁可靠的全局事件监听和注入方案。项目欢迎贡献来扩展平台支持。3. 从零开始的详细安装与配置指南3.1 macOS 系统安装Homebrew 推荐对于 macOS 用户Homebrew 是最省心的方式。由于项目处于活跃开发期作者推荐安装最新的开发版--HEAD。# 1. 添加项目的 Homebrew Tap brew tap ls1xt/murmur https://github.com/ls1xt/homebrew-murmur # 2. 安装最新开发版的 Murmur brew install --HEAD ls1xt/murmur/murmur安装完成后在终端输入murmur --help应该能看到命令列表。接下来是最关键的一步授予辅助功能权限。没有这个权限Murmur 将无法监听全局按键和模拟键盘输入。打开系统设置 隐私与安全性 辅助功能。点击左下角的锁图标解锁。点击“”号找到并添加你常用的终端应用如 Terminal、iTerm2、Alacritty 或 Warp。如果你后续通过murmur daemon enable将其设为登录启动项系统可能还会提示你添加python3或murmur二进制文件本身请同样允许。3.2 Linux 系统安装与依赖配置Linux 的安装步骤稍多主要是系统级依赖和权限设置。以下以 Ubuntu/Debian 系为例# 1. 安装系统依赖 sudo apt update sudo apt install ydotool portaudio19-dev python3-dev python3-venv git -y # portaudio19-dev 是音频录制所需python3-dev 用于编译某些Python包。 # 2. 将当前用户添加到 input 组以获取读取键盘设备的权限 sudo usermod -aG input $USER # 重要此操作需要你注销并重新登录或者新开一个终端会话执行 newgrp input才能生效。 # 3. 启用并启动 ydotool 的用户服务 systemctl --user enable --now ydotool # 测试 ydotool 是否工作执行 ydotool type “hello”应该能看到输入。 # 4. 从源码安装 Murmur git clone https://github.com/ls1xt/murmur.git cd murmur # 使用 uv一个更快的 Python 包管理工具或 pip 安装依赖 # 如果未安装 uv可以用 pippython3 -m venv .venv source .venv/bin/activate pip install -e . uv sync # 此时你可以用 uv run murmur --help 来运行或将其安装到环境 uv pip install -e .3.3 获取并配置 AssemblyAI API 密钥无论哪个平台都需要一个 AssemblyAI 的 API 密钥。访问 AssemblyAI 官网 注册账号。进入 Dashboard你会看到你的 API Key。新账号自带50美元免费额度。在终端中配置 Murmurmurmur config --key transcriber.api_key --value YOUR_API_KEY_HERE这条命令会将密钥安全地写入~/.config/murmur/config.json。3.4 启动守护进程与基础测试配置好密钥后就可以启动 Murmur 的核心服务了。# 启动守护进程后台服务 murmur daemon start # 如果你想让它开机自启 murmur daemon enable # 检查运行状态 murmur daemon status现在进行测试将光标聚焦到任何一个可以输入文本的地方比如一个记事本、浏览器地址栏按住 F12 键不放清晰地说一句话例如“Hello world, this is a test.”然后松开 F12。稍等片刻通常不到一秒你刚才说的话就应该被转换成文字并输入到光标处了。实操心得第一次使用时可能会因为按键时机或说话习惯导致效果不佳。建议先进行几次简单的测试比如对着记事本说“测试一二三”熟悉从按下到松开、以及语音转录的延迟节奏。如果没反应请跳转到后面的“故障排查”章节。4. 高级功能配置与实战应用场景4.1 自定义热键与多语言配置默认的 F12 可能与其他软件冲突或者你想为不同语言分配不同的按键。这需要通过编辑配置文件来实现。首先生成或查看当前配置murmur config ~/.config/murmur/config.json然后编辑~/.config/murmur/config.json文件。一个支持英文F12和德语CtrlCmdK的配置示例如下{ hotkey: { bindings: [ { modifiers: [], trigger: KEY_F12, mode: push_to_talk, language: en }, { modifiers: [KEY_LEFTCTRL, KEY_LEFTMETA], trigger: KEY_K, mode: push_to_talk, language: de } ] } }modifiers: 修饰键如KEY_LEFTCTRL,KEY_LEFTMETA(Cmd),KEY_LEFTALT。trigger: 触发键格式为KEY_前缀加上键名如KEY_F12,KEY_T。mode: 模式push_to_talk按住说话或toggle切换开关。language: 语言代码如en英语、zh中文、de德语、ja日语等。完整列表可参考 AssemblyAI 文档。保存文件后无需重启 daemon直接尝试新的快捷键即可生效。4.2 剪贴板模式与安全注入策略有时你不想直接把文字输入到当前应用而是想先复制到剪贴板检查或编辑后再粘贴。Murmur 提供了“剪贴板模式”。你可以为其单独设置一个热键例如CtrlCmdCmacOS或CtrlAltCLinux在配置中设置mode: push_to_talk并配合destination: clipboard。但更简单的方法是使用内置的默认绑定如果默认配置已启用。另一个重要的配置是注入策略。有些应用特别是终端或某些IDE如果接收字符的速度太快可能会丢字。如果你发现转录的文字有缺失可以调整注入速度或切换策略。# 查看当前注入配置 murmur config --key injector # 增加每个字符输入后的延迟单位毫秒 murmur config --key injector.key_delay --value 5 # 或者直接切换到剪贴板注入策略一次性粘贴全部文本 murmur config --key injector.inject_strategy --value clipboard注意事项clipboard策略并非万能。它依赖于系统的粘贴快捷键通常是 CmdV / CtrlV。如果目标应用不支持该粘贴快捷键或者其焦点模型特殊如某些虚拟机或远程桌面可能会失败。keystroke模拟击键是兼容性最好的默认策略。4.3 实现语音驱动的 AI 助手自动化以 Claude Code tmux 为例这是 Murmur 最强大的应用场景之一创建一个常驻后台的 AI 助手会话你可以随时通过语音向其发送指令而无需切换窗口。场景你正在全屏浏览器查资料突然想到一个代码问题。你想问 Claude Code但不想切出浏览器。实现步骤创建后台 tmux 会话tmux new-session -d -s claude-voice tmux send-keys -t claude-voice claude C-m这会创建一个名为claude-voice的分离后台会话并在其中启动 Claude Code。配置 Murmur 热键指向该 tmux 会话 编辑~/.config/murmur/config.json在bindings数组中添加一个新项{ modifiers: [KEY_LEFTCTRL, KEY_LEFTMETA], trigger: KEY_T, mode: toggle, destination: tmux:claude-voice:0.0, append_enter: true }destination: “tmux:claude-voice:0.0”表示注入到名为claude-voice的 tmux 会话的第一个窗口0的第一个面板0。append_enter: true在注入文本后自动追加一个回车键相当于“发送消息”。mode: “toggle”按一次开始录音再按一次或随便按个键盘键停止并注入。适合说一段较长的话。使用现在无论你当前在哪个窗口只要按下CtrlCmdT听到提示音如果启用后开始说话。说完后再按一次CtrlCmdT或按一下其他键你说的话就会自动发送到后台的 Claude Code 会话中并得到回复。你可以随时切换到那个 tmux 窗口查看对话历史。警告此功能非常强大但需谨慎使用。如果destination指向的是一个普通的 Shell 面板你语音输入的内容会被当作命令执行务必确保目标面板运行的是预期的、安全的应用程序。5. 常见问题排查与性能调优5.1 安装与权限问题问题Linux 下运行murmur daemon start报错 “No keyboard devices found” 或热键无反应。排查用户未加入input组或未重新登录。解决执行groups | grep input确认。如果不在执行sudo usermod -aG input $USER后必须注销并重新登录或在新终端中执行newgrp input。问题Linux 下文字无法输入ydotool type “test”也没反应。排查ydotool服务未运行。解决执行systemctl --user status ydotool查看状态。确保已启用并启动systemctl --user enable --now ydotool。问题macOS 下热键无反应或提示需要辅助功能权限。排查终端应用或murmur本身未被添加到“辅助功能”权限列表。解决严格按照上文“macOS 系统安装”部分的步骤在系统设置中添加正确的应用。添加后最好重启一下终端应用。5.2 录音与转录问题问题按下热键有反馈音但松开后无文字输入或报转录错误。排查1API 密钥未设置或设置错误。解决运行murmur config --key transcriber.api_key检查。重新用murmur config --key transcriber.api_key --value YOUR_KEY设置。排查2麦克风设备选择错误或权限问题。解决运行murmur list-mics查看可用麦克风。在配置文件中指定设备IDmurmur config --key audio.device_index --value 1数字从list-mics结果中获取。在系统设置中确保给了终端应用麦克风权限。排查3网络问题或 AssemblyAI 服务暂时不可用。解决检查网络连接。查看 daemon 日志启动时加-v参数是否有网络超时错误。问题转录准确度不高尤其是专业术语或特定口音。解决利用 AssemblyAI 的自定义词汇表功能。创建一个文本文件每行一个词或短语如“Kubernetes”, “GraphQL”, “我的项目名XYZ”。然后在配置中指定murmur config --key transcriber.word_boost --value “$(cat /path/to/your/custom_words.txt)” murmur config --key transcriber.word_boost_weight --value 0.5这能显著提升特定词汇的识别率。5.3 文本注入与兼容性问题问题文字输入不完整丢字或少字。排查默认的注入速度对某些应用太快。解决增加按键延迟murmur config --key injector.key_delay --value 10单位毫秒。或者切换到剪贴板模式murmur config --key injector.inject_strategy --value clipboard。问题在特定应用如某些基于 Electron 的应用、虚拟机、远程桌面中无效。排查这些应用可能有特殊的安全策略或焦点处理机制阻止了模拟按键。解决首先尝试“剪贴板模式”。如果还不行可能是该应用环境下的根本性限制。可以尝试在该应用内使用系统自带的或应用内建的语音输入作为补充。问题同时按下其他键时热键触发不灵敏。解决这是全局热键监听的一个常见限制。尽量使用不常与其他功能键组合的按键作为触发键。如果问题严重可以尝试在配置中调整hotkey.debounce_delay去抖延迟参数但通常不需要。5.4 性能与资源占用Murmur 守护进程本身非常轻量主要资源消耗发生在语音流式上传和转录期间。根据我的实测在空闲时内存占用约 30-50 MBCPU 可忽略不计。在进行转录时会产生网络流量音频数据和一定的 CPU 使用编码和网络 IO但对于现代机器来说完全无感。如果你担心隐私或网络延迟社区正在积极贡献本地转录后端如 OpenAI Whisper。未来版本可能会集成这些选项实现完全离线的语音输入这对于网络环境不好或对隐私要求极高的场景将是终极解决方案。目前你可以关注项目的 GitHub Issues 和 Pull Requests 来获取这些实验性功能的进展。