English · Русский · Windows version →

Voica

A macOS menu-bar app for voice dictation with punctuation — via Groq Whisper (whisper-large-v3-turbo) or fully offline with a local model (GigaAM v3).

---

Built-in dictation on macOS/iOS doesn't add punctuation — no periods, commas, or question marks. Voica does: dictate by a hotkey and get clean, punctuated text inserted right where you're typing, transcribed via Groq Whisper (whisper-large-v3-turbo), which is fast and cheap — or fully offline with a local on-device model (Sber's GigaAM v3, excellent for Russian), no internet or API key required.

Features

• Hotkey dictation — push-to-talk (hold) or toggle (press to start / stop).
• Local offline engine (optional) — switch Settings → General to Local (offline) and dictation runs entirely on your Mac via Core ML on the Apple Neural Engine (Sber's GigaAM v3 model, MIT, punctuation out of the box, excellent Russian). One-time ~400 MB model download with a progress bar; the model can be deleted anytime in Settings → Data. If the cloud is unreachable, Voica automatically falls back to the local model (with a notification). Trade-offs: English words may come out transliterated in Cyrillic, and the vocabulary hint stays cloud-only.
• Recognized text is inserted into the active field by default (or shown in an editable window — your choice in Settings), and always copied to the clipboard as a fallback.
• History of all transcriptions (SQLite): review, re-copy, play back the audio, delete.
• Audio retention with auto-cleanup (default 30 days, configurable; text history is kept).
• Cloud recognition model & language (Settings → Dictation): Turbo (faster) or Large v3 (more accurate); language auto-detects by default (great for mixed speech) or can be forced to Russian/English for short phrases. The local engine is Russian-only.
• Vocabulary — list terms Whisper often mishears (names, jargon, anglicisms) and they're passed as a hint on every dictation to bias spelling. Soft limit ~800 characters (Whisper only reads the last ~224 tokens of the hint; a live counter in Settings shows the budget). Optionally, an AI pass (Groq LLM) reliably fixes the terms that still come out garbled — matching grammatical case and context.
• Localized UI — English and Russian, follows the system language.
• Update checks — optionally checks GitHub for a newer version on launch and points you to the release page. Never downloads or installs anything by itself; can be turned off.
• API key stored in a protected file (0600, readable only by you) — never in the repo.
• Privacy-friendly: everything stays on your Mac. Audio goes only to Groq for transcription — or nowhere at all with the local engine; the only other network call is the optional, anonymous update check to GitHub.

Screenshots

Install

1. Download Voica-<version>.dmg from Releases (or build from source — see below).
2. Open the .dmg and drag Voica to Applications.
3. The app isn't notarized, so the first launch is blocked with “Voica” Not Opened (or cannot be checked for malware). Click Done (not “Move to Bin”), then open System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway next to the Voica message; confirm once more. After that it opens normally. Alternatively, run once in Terminal: xattr -dr com.apple.quarantine /Applications/Voica.app.

First run & permissions

On first use macOS asks for two permissions:

• Microphone — to record (prompted on your first dictation).
• Accessibility — for the global hotkey: System Settings → Privacy & Security → Accessibility → enable Voica.

Then the Settings window opens — paste your Groq API key (gsk_…), click Test, then Save. Get a key at console.groq.com/keys. Don't want a key or the cloud? Choose Local (offline) in Settings → General instead — Voica downloads the model (~400 MB, once) and no key is needed at all.

Usage

• Push-to-talk (default): hold Right ⌥ Option, speak, release — text arrives in ~a second.
• Toggle: one press of the chosen key starts, another stops.
• Or click Dictate in the menu (manual start/stop, no hotkey needed).

The menu-bar icon reflects state: idle → recording (pulsing) → sending to Groq.

Settings

Organized into tabs (like the system Settings app): General — speech engine (Cloud / Local), API key (with a Test button), update check, reset to defaults; Dictation — mode (push-to-talk / toggle), hotkey, output, and the cloud recognition model (Turbo / Large v3) and language (auto / Russian / English); Vocabulary — your terms with a live budget counter, the AI correction toggle (with a model availability check), and an AI-model picker (recommended-automatic or a specific model from your live list); Data — audio storage, retention, local model deletion, and Delete all data (guarded by a random phrase).

Where data is stored

~/Library/Application Support/com.ushakov.voica/history.sqlite   # history
~/Library/Application Support/com.ushakov.voica/audio/           # audio recordings
~/Library/Application Support/com.ushakov.voica/credentials      # API key (0600)
~/Library/Application Support/com.ushakov.voica/models/          # local model (if downloaded)
~/Library/Preferences/com.ushakov.voica.plist                    # settings

Bring your own Groq key

The key is only needed for the cloud engine (and for AI term correction); the local engine works without one. Voica uses your own Groq API key (BYO-key) — the app never ships or shares anyone's key. Each user gets a free key at console.groq.com; usage is subject to Groq's Terms of Use. Free-tier limits (whisper-large-v3-turbo): 20 req/min, 2000/day, 7200 audio-seconds/hour — far more than dictation needs.

If you enable AI term correction (Settings → Vocabulary), Voica also calls a Groq chat model. By default it picks the best available one automatically from your live model list, so if Groq ever removes or renames a model the app self-heals — no update needed. You can also pick a specific model. Some Groq organizations block chat models by default — if the status shows blocked, allow the chosen model at console.groq.com → Settings → Limits. Otherwise the correction silently falls back to the raw transcription (fail-open by design).

Build from source

Only Command Line Tools are required (xcode-select --install); full Xcode is not needed.

./scripts/make-cert.sh       # once: local self-signed cert for a stable signature
./scripts/build.sh           # builds build/Voica.app (release)
./scripts/run.sh             # build + run with logs in the terminal
./scripts/package.sh         # builds build/Voica-<version>.dmg
./build/Voica.app/Contents/MacOS/Voica --test-all   # self-test

make-cert.sh creates a self-signed signing certificate in your keychain. Without it the build is signed ad-hoc, and the Accessibility permission gets lost on every update (macOS can't stably identify an ad-hoc app). With the certificate it persists. See docs/ROADMAP.md for distribution, auto-update, and cross-platform notes.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. This is a spare-time project, so responses may be slow and not every feature request will be accepted.

Acknowledgements

Voica was built largely with Claude Code, Anthropic's agentic coding tool, as an AI pair-programmer.

License

MIT © 2026 Ivan Ushakov

The bundled local recognition model (Sber's GigaAM v3) is redistributed under its own MIT license — see THIRD-PARTY-LICENSES.md.