better-voice README

The project's README from github.com/TarunTomar122/better-voice. As one markdown file: README.md.

BetterVoice

Voice dictation with the screen context you point at.

BetterVoice is an experimental, open-source macOS menu-bar app. It transcribes speech locally and captures the full screen whenever you circle something with your pointer, leaving a restrained blue highlight around the referenced area.

BetterVoice settings overview

Use it

Each circle captures the complete display beneath the pointer. Multiple circles produce screenshots in the same order you referenced them.

Open Settings… from the menu-bar icon to choose a microphone, change the dictation language, tune the circle threshold, and customize the shortcuts. In Shortcuts, click the current key, wait for Listening…, and press the exact combination you want. It appears in place immediately; click Done when finished. Reset shortcuts to defaults restores both shortcut bindings and trigger styles. Quick notes support hold, tap-to-toggle, and double-tap-to-toggle when the shortcut is modifier-only; long explanations support press-to-toggle and double-tap-to-toggle for modifier-only shortcuts. Hold delay is adjustable from 50–500 ms (140 ms by default). The defaults are 340° for circle detection, hold ⌥ for quick notes, and press ⌘⌥ for long explanations.

Dictation language

BetterVoice dictates in English by default and nothing about that flow changed. Pick another language under Dictation Language in the menu bar, or in Settings….

English keeps the English-only Parakeet model it has always used, so an existing install downloads nothing new and its transcription is unchanged. Choosing any other language pulls the multilingual model instead, a separate one-time download of roughly the same size. Switching back to English returns to the model already on disk.

Two things follow from the language you pick:

Grammar cleanup (Beta)

Grammar cleanup is off by default. To try the beta, open Settings…, turn on Grammar cleanup (Beta), and press Download. BetterVoice then runs each transcript through the tiny, English-focused t5-tiny-gec-hone model. Its quantized ONNX weights and tokenizer are about 36 MB, stored in ~/Library/Application Support/BetterVoice, and run locally. When enabled, BetterVoice preloads the cached model in the background after launch so the first recording does not pay the initialization cost. The status bar shows “Polishing transcript locally…” while this step runs. If the model cannot download, exceeds its context limit, or returns an incomplete result, BetterVoice keeps the raw transcript so recording still completes.

This is intentionally experimental: the model fixes capitalization, punctuation, and sentence structure, and it can occasionally change wording. Delete the t5-tiny-gec-hone folder to force a fresh download.

Developer vocabulary (Beta)

BetterVoice also includes a fast, zero-download developer pass inspired by WhisperDictation and Dictate. It fixes common casing such as github → GitHub, javascript → JavaScript, and json → JSON, and recognizes spoken acronyms such as “n p m” in terminals and editors. It preserves the transcript’s wording and runs locally in milliseconds. The pass is enabled by default and can be turned off from Settings…. The generic grammar model remains an independent, opt-in beta.

Your own vocabulary

The developer pass ships with a fixed table, and it will never cover kubectl, an internal service name, or a colleague's surname. Those live in a file you edit:

~/Library/Application Support/BetterVoice/vocabulary.json

Open it from the menu bar with Edit Vocabulary…. The key is what the transcript says, the value is what you meant, and phrases of several words work:

{
  "terms": {
    "cube cuttle": "kubectl",
    "engine x": "nginx"
  }
}

Saving is enough; the file is re-read on your next recording. Longer sources are applied first, so a phrase wins over a word inside it, and matching is whole-word and case-insensitive, so filenames, domains, and paths are left alone. A source you list replaces the built-in spelling for that same term.

One rule is worth respecting: never use an ordinary word as a key. Mapping read me to README rewrites every sentence containing "read me". The file ships with no terms for that reason, and it is ignored entirely while Developer vocabulary (Beta) is off. A malformed file is ignored rather than failing the recording.

Download

Download the latest Apple Silicon build from the BetterVoice releases page. Choose BetterVoice-macos-arm64.zip, unzip it, and open BetterVoice.app:

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

The release targets macOS 14+ on Apple Silicon. This experimental build is signed with an Apple Development certificate and is not notarized with a Developer ID certificate yet. On the first launch, macOS may require you to Control-click the app, choose Open, and confirm. If macOS still blocks it, use System Settings → Privacy & Security → Open Anyway. Then approve Microphone and Accessibility when BetterVoice asks; Screen Recording is optional for visual context. The local speech model downloads once (about 500 MB).

The first launch opens a guided setup: download the local model, grant microphone and Accessibility access, optionally enable Screen Recording for visual context, choose your microphone, and review the shortcut walkthrough. After setup, open Settings… from the menu bar any time to revisit these choices.

BetterVoice stays available in the menu bar and Dock while it is running. Choose Quit BetterVoice from either menu before deleting the app. If the UI is unavailable, run pkill -x BetterVoice, then move BetterVoice.app to the Trash.

Install from source

Requirements: macOS 14+, Swift 6/Xcode command-line tools, and a local Apple code-signing identity.

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

The script builds, signs, and opens .build/BetterVoice.app. BetterVoice then walks through:

  1. The one-time local Parakeet model download (~500 MB)
  2. Microphone permission
  3. Accessibility permission for global shortcuts and returning text to the selected field
  4. Optional Screen Recording permission for circles and visual context
  5. Microphone selection and the shortcut walkthrough

Automatic microphone selection prefers a connected external input and falls back to the system input. You can choose a specific device during setup or from the menu bar.

To keep macOS permissions attached to the same identity across rebuilds, explicitly select your certificate when needed:

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

If something is not working

Open the menu-bar icon and choose Settings…. It shows the live state of the microphone, Screen Recording, Accessibility, selected input, local transcription model, and the grammar cleanup toggle. Errors stay visible in a small recovery window with a path back to setup instead of disappearing as a system beep.

Clipboard behavior

macOS lets one clipboard contain text, rich text, and image representations, but each destination decides which representation to accept. For either mode, BetterVoice captures the focused app and field when recording stops, puts the transcript on the clipboard, and sends one ⌘V directly to that captured app. When both transcript and screen context exist, it then puts the captured images on the clipboard and sends a second ⌘V to the same app. Long explanations leave those images available on the clipboard; quick ⌥ notes restore the clipboard you had before recording. If the clipboard changes during the handoff, image insertion is skipped to avoid overwriting user data.

Privacy and storage

A session contains:

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

Development

swift test -Xswiftc -strict-concurrency=complete

See docs/ARCHITECTURE.md for the implementation map.

Contributing

New to the project? Start with the contribution guide. It covers the local setup, test command, architecture boundaries, and the kinds of changes that are useful to BetterVoice.

Current scope: English transcription by default with other languages behind the picker, Apple Silicon macOS 14+, and an experimental downloadable release. The release is not notarized with a Developer ID certificate yet. Circle recognition is intentionally forgiving; you do not need to draw a perfect circle.

Inspired by the fluidity of Wispr Flow. BetterVoice is not affiliated with Wispr Flow.

better-voice (TarunTomar122/better-voice)

Searching Database…

281 ·GitHub
Better-voice
Что это?BetterVoice — экспериментальное open-source приложение для macOS в строке меню для голосового диктования. Оно транскрибирует речь локально и также захватывает область экрана, которую вы обводите указателем во время разговора, так что транскрипт идёт вместе с визуальным контекстом.
Это просто инструмент диктовки, или он умеет ещё и скриншоты?И то и другое: он вставляет голосовой транскрипт в активное текстовое поле, а если вы обвели что-то на экране во время записи, он также вставляет скриншот обведённой области в то же поле.
Как его запустить?Скачайте сборку для Apple Silicon (BetterVoice-macos-arm64.zip) со страницы релизов, распакуйте и откройте BetterVoice.app; первый запуск проведёт вас через пошаговую настройку. Либо соберите из исходников локальным скриптом сборки, которому нужны Swift 6/Xcode command-line tools.
Нужно ли выдавать какие-то особые разрешения macOS?Да — обязательны разрешения Microphone и Accessibility, а Screen Recording необязательно, но нужно, если хотите функцию «обвести — получить скриншот».
Готов ли релиз к установке без дополнительных шагов?Сборка подписана, но пока не нотаризована сертификатом Developer ID, поэтому macOS может заблокировать её при первом запуске, и понадобится клик с Control и выбор Open либо разрешение через System Settings.
Работает ли он и на Mac с Intel?Нет, сейчас поддерживаются только Mac на Apple Silicon с macOS 14 или новее.
Работает ли диктовка без интернета?Да, после одноразовой локальной загрузки модели (~500 МБ) транскрибация речи полностью работает офлайн, на устройстве.
Куда уходят мои аудио- и экранные данные?Транскрибация полностью локальна через FluidAudio, временные аудио удаляются сразу после транскрибации, а сохранённые сессии лежат на диске в ~/Desktop/BetterVoice максимум 7 дней (с лимитом 500 МБ).
Можно ли переключить диктовку на другой язык, кроме английского?Да, можно выбрать другой язык в строке меню или в Settings; переключение с английского запускает одноразовую загрузку отдельной многоязычной модели, а английский продолжает использовать оригинальную модель Parakeet.
Что такое бета Grammar cleanup?Опциональная функция, прогоняющая транскрипты через крошечную локальную модель t5-tiny-gec-hone (~36 МБ), чтобы исправить заглавные буквы, пунктуацию и структуру предложений в английском тексте; при сбое или таймауте модели используется сырой транскрипт.
Можно ли научить его своим словам вроде названий внутренних сервисов?Да, есть редактируемый файл словаря (открывается через Edit Vocabulary... в строке меню), который сопоставляет неверно расслышанные фразы транскрипта правильному написанию, с применением целословного сравнения без учёта регистра.
Какие горячие клавиши записи по умолчанию?Зажмите ⌥ для быстрой заметки (остановится при отпускании), а ⌘⌥ нажмите для запуска/остановки более длинного объяснения; и горячие клавиши, и порог распознавания обводки настраиваются в Settings.
What are similar projects?parrot, lipflow, murmur-youtube, tendedero, FluidVoice, course2md, jot-gemini-transcribe-macOS, quill
Which topics is it in?menubar, transcription, screenshot, speech-to-text, speech-recognition, privacy-first, accessibility, macos-app, apple-silicon, swift, offline, local-first
Creator
TarunTomar122
Size
5.3 MB
Stars
281
Updated
CommitOct 12Releasev0.1.10Aug 29
Age
1mo
Commits · 90 Days