ESC
开源 2 分钟阅读

BetterVoice：用指针圈选屏幕上下文进行语音听写

BetterVoice 是一款实验性的开源 macOS 菜单栏应用，可本地转写语音，并在你用指针圈选屏幕内容时捕捉完整显示画面，留下蓝色高亮标记。支持快速笔记和长解释两种模式，转录文本可插入当前输入框。内置可选的文法清理 Beta 功能，通过本地 T5 小模型修正大小写与标点；同时提供开发者词汇修正，将 github 转为 GitHub 等。采用本地语音模型，注重隐私，支持 Apple Silic

来源：GitHub

BetterVoice

用指针圈选屏幕上下文进行语音听写。

BetterVoice 是一款实验性的开源 macOS 菜单栏应用。它本地转写语音，并能在你用指针圈选某个区域时捕捉完整屏幕，在所指区域周围留下克制的蓝色高亮。

Buy me a coffee

如果你喜欢 BetterVoice 或我的其他实验，请我喝杯咖啡有助于支持未来的项目。❤️

BetterVoice onboarding and visual capture preview

使用

  • 按住 ⌥ 快速记笔记。短暂按住后开始录音，松开即结束。
  • 按 ⌘⌥ 进行长解释。再次按下结束。
  • 开始和停止聆听时，会发出柔和的系统提示音。
  • 录音过程中，用指针圈选任何重要 UI。蓝色轨迹会跟随你的移动，每次捕捉时会有脉冲确认。
  • 当 macOS 允许时，BetterVoice 会将转录文本插入选中的文本字段。长解释还会将转录文本和捕捉图像复制到剪贴板；快速笔记则保持原有剪贴板不变。

每次圈选都会捕捉指针下方的完整显示画面。多次圈选会按你引用的顺序生成多张截图。

文法清理（Beta）

文法清理默认关闭。要试用 Beta 版，请打开 Getting Started…，开启 Grammar cleanup (Beta)，然后按 Download。BetterVoice 会将每段转录文本通过小巧的、专注于英语的 t5-tiny-gec-hone 模型进行清理。其量化 ONNX 权重和分词器约 36 MB，存储在 ~/Library/Application Support/BetterVoice，并在本地运行。启用后，BetterVoice 会在启动后在后台预加载缓存模型，因此第一次录音不需要承担初始化成本。此步骤运行时，状态栏会显示“正在本地润色转录文本…”。如果模型无法下载、超出上下文限制或返回不完整结果，BetterVoice 会保留原始转录文本，录音仍能完成。

这是刻意保持实验性的功能：模型会修正大小写、标点和句子结构，偶尔也可能改动措辞。删除 t5-tiny-gec-hone 文件夹可强制重新下载。

开发者词汇（Beta）

该分支实验还包含一个快速、无需下载的开发者处理流程，灵感来自 WhisperDictation 和 Dictate。它修正常见大小写，例如 github → GitHub、javascript → JavaScript、json → JSON，并识别终端和编辑器中的口头缩略词如“n p m”。它保留转录文本的措辞，并在毫秒级内在本地运行。该流程在此分支中默认启用，可在 Getting Started… 中关闭。通用文法模型仍然是独立的、可选择开启的 Beta 功能。

下载

从 BetterVoice releases 页面 下载最新的 Apple Silicon 版本。选择 BetterVoice-macos-arm64.zip，解压并打开 BetterVoice.app：

unzip BetterVoice-macos-arm64.zip
open BetterVoice.app

该版本面向 macOS 14+ 和 Apple Silicon。此实验性构建使用 Apple Development 证书签名，尚未使用 Developer ID 证书进行公证。首次启动时，macOS 可能要求你按住 Control 键点击应用，选择 打开 并确认。如果 macOS 仍阻止，请使用 系统设置 → 隐私与安全性 → 仍要打开。然后批准 BetterVoice 请求的麦克风、屏幕录制和辅助功能权限。本地语音模型会一次性下载（约 500 MB）。

从源码安装

要求：macOS 14+、Swift 6/Xcode 命令行工具，以及本地 Apple 代码签名身份。

git clone https://github.com/TarunTomar122/better-voice.git
cd better-voice
./scripts/build-app.sh

该脚本会构建、签名并打开 .build/BetterVoice.app。然后 BetterVoice 会逐步引导：

  1. 麦克风权限
  2. 屏幕录制权限
  3. 辅助功能权限（用于将文本返回选中字段）
  4. 一次性本地 Parakeet 模型下载（约 500 MB）

自动麦克风选择会优先使用已连接的外部输入，并回退到系统输入。你可以在设置过程中或从菜单栏选择特定设备。

为了让 macOS 权限在多次重建后仍绑定到同一身份，请在需要时显式选择证书：

BETTERVOICE_SIGNING_IDENTITY="Apple Development: Your Name (TEAMID)" ./scripts/build-app.sh

如果出现问题

打开菜单栏图标并选择 Getting Started…。它会显示麦克风、屏幕录制、辅助功能、所选输入、本地转录模型和文法清理开关的实时状态。错误会显示在一个小型恢复窗口中，并带有返回设置界面的路径，而不会像系统蜂鸣一样消失。

  • 快捷键无反应： 启用 辅助功能，确认本地模型显示 Ready，并确保只有一个 BetterVoice 进程在运行。构建脚本会在启动重建前关闭之前的进程。
  • 没有截图： 在 系统设置 → 隐私与安全性 → 屏幕录制 中启用 BetterVoice，然后退出并重新打开应用。设置界面每次都会读取当前 macOS 权限；不会缓存旧答案。
  • 转录文本未插入： 启用 辅助功能。当目标应用阻止粘贴事件时，转录文本会保留在剪贴板和已保存会话中。
  • 麦克风错误： 在菜单栏菜单的 麦克风 下选择设备。
  • 模型下载失败： 重新打开 Getting Started…，在模型行重试。
  • 文法模型下载失败： 重新打开 Getting Started…，在文法清理行重试 Download。
  • 尝试文法清理： 在 Getting Started… 中开启 Grammar cleanup (Beta)，然后按 Download。
  • 意外的空录音： 短于 2.5 秒且没有语音或圈选的会话会被静默丢弃。较长的空会话会保存且不打开错误对话框。

剪贴板行为

macOS 允许一个剪贴板同时包含文本、富文本和图像表示，但每个目标应用决定接受哪种表示。对于长解释，BetterVoice 会在录音停止时捕捉焦点应用和字段，只将转录文本放入剪贴板，并直接向该应用发送一次 ⌘V。然后恢复包含文本和图像的完整剪贴板。快速 ⌥ 笔记仅使用临时剪贴板进行插入，并恢复录音前的剪贴板。

隐私与存储

  • 转录通过 FluidAudio 在本地运行。
  • 临时音频在转录后删除。
  • 会话保存在 ~/Desktop/BetterVoice 中，最多保留 7 天。
  • 保存的会话上限为 500 MB，包括在活跃捕捉期间；最旧的会先被移除。
  • 本地语音模型是独立的一次性缓存，约 500 MB。
  • 录音会在 20 分钟时安全停止，被遗弃的临时音频会在启动时清除。
  • 随时使用菜单栏中的 Open Saved Sessions 或 Clear Saved Sessions…。

会话包含：

<timestamp>-<id>/
├── context.md
├── context-1.png
└── context-2.png

开发

swift test -Xswiftc -strict-concurrency=complete

实现地图见 docs/ARCHITECTURE.md。

贡献

项目新手？从贡献指南开始。它涵盖了本地设置、测试命令、架构边界以及对 BetterVoice 有用的更改类型。

当前范围：英语转录、Apple Silicon macOS 14+，以及实验性可下载版本。该版本尚未使用 Developer ID 证书公证。圆圈识别有意保持宽容；你不必画出完美的圆圈。

灵感来自 Wispr Flow 的流畅体验。BetterVoice 与 Wispr Flow 无关。