voiceink

A pre-built, free copy of VoiceInk — macOS dictation app (Whisper-powered, fully offline, global hotkey).

The DMG in dist/ lets you install the app on any Apple Silicon Mac without installing Xcode + cmake or sitting through a 10-minute build.

Why a pre-built DMG

VoiceInk's source is GPL v3 — fully free if you build it yourself. The official .dmg (also what brew install --cask voiceink ships) is a 7-day commercial trial that prompts for payment after a week. The binary in dist/ is the same source, built locally with make local, which the project explicitly supports for personal use.

Install on a new Mac (the common case)

If you have an AI coding agent available, point it at this folder:

"There's a tool called voiceink — install it following INSTALL.md."

It will mount the DMG in dist/, copy VoiceInk.app into /Applications, strip the quarantine attribute, and tell you what GUI permissions to grant. The detailed runbook lives at INSTALL.md.

To do it by hand:

open dist/VoiceInk-1.79-arm64.dmg

Drag VoiceInk.app onto the Applications shortcut in the DMG window. Done. No Xcode, no cmake, no build.

First launch — MUST launch from Spotlight or Finder, not via terminal:

⚠️ Why this matters: if you open the app from a terminal that's embedded inside another app (Obsidian, Cursor, VS Code, Claude Code, tmux session inside iTerm child of Obsidian, etc.), macOS TCC records the parent app as VoiceInk's "responsible process" and silently routes all permission requests through the parent's grants. The mic permission dialog will never appear, and clicking "Request Permission" in VoiceInk does nothing. Quitting and re-launching from Spotlight clears this.

• Launch via Spotlight (Cmd+Space → "VoiceInk") or Finder
• macOS Gatekeeper may block ad-hoc-signed apps. If so: System Settings → Privacy & Security → "Open Anyway".
• Grant Microphone + Accessibility permissions when prompted (Accessibility is what lets it type into any input field).

Then run ./configure.sh to apply standard settings, or set them manually in VoiceInk Settings:

• Language: Auto — required for Chinese/English code-switching.
• Model (under AI Models): Whisper Large v3 Turbo. Smaller models botch mixed-language audio.
• Task / Mode: Transcribe (NOT Translate — Translate forces output to English).
• AI Enhancement: off (it routes transcripts through an LLM and can silently translate or rewrite).
• Launch at Login: on.

Updating to a newer upstream version

Only needed when you actually want a newer feature. Most upstream commits are polish; the version in dist/ is fine for everyday use.

On a machine with Xcode installed:

• Double-click upgrade.command in Finder — opens in Terminal, runs the full upgrade, pauses at the end so you can read the output.
• Or from a terminal: ./upgrade.sh (or bash upgrade.sh if the executable bit is missing after a fresh clone).

Either way, it does: pull → build → install → package → git push.

Don't double-click upgrade.sh — macOS opens .sh files in Xcode, not Terminal. The .command wrapper exists specifically to dodge that.

That's it. The script handles:

• Pulling latest upstream source
• Xcode beta compatibility (auto-detects and applies workarounds)
• Info.plist version patching (upstream sometimes forgets to bump it)
• Installing to /Applications (quits running app first)
• Packaging the DMG into dist/
• Committing + pushing to git

Options:

• ./upgrade.sh --dry — pull and build only, don't install or commit

Then on every other Mac: pull the latest dist/ and open dist/VoiceInk-<new>.dmg.

Manual build (if upgrade.sh doesn't fit your case)

./build.sh       # pulls latest upstream into src/, runs make local
./package.sh     # repackages the new .app into dist/VoiceInk-<ver>-<arch>.dmg

What's in this folder

File	Purpose
dist/*.dmg	Pre-built drag-to-Applications installer. This is the point.
upgrade.command	Double-click in Finder to run the full upgrade in Terminal. Thin wrapper around upgrade.sh.
upgrade.sh	One-command upgrade: pull → build → install → configure → package → git push.
configure.sh	Apply/reset standard settings (language, model, AI off, login item). Idempotent.
build.sh	Clones upstream into src/, runs make local. Idempotent.
package.sh	Wraps the built .app into a compressed DMG in dist/.
src/	(gitignored) upstream clone, recreated by build.sh.
.gitignore	Keeps the upstream source + build artifacts out of git; keeps dist/*.dmg in.

Build prerequisites (only needed if you run build.sh)

• macOS 14.4+
• Xcode (full app from App Store, ~15GB) + run once: sudo xcodebuild -runFirstLaunch
• brew install cmake

build.sh will check both of these and tell you exactly what to do if either is missing.

License + redistribution

VoiceInk is GPL v3. The DMG in this repo was built from upstream source at the commit checked out by build.sh at packaging time — anyone wanting the matching source can get it from https://github.com/Beingpax/VoiceInk or by running ./build.sh here, which clones the same upstream.