LocalVoiceAI Quickstart: Install and Start Dictating

This guide walks you through installing LocalVoiceAI, granting the two required macOS privacy permissions, starting the background service, and making your first voice transcription — all in under five minutes on an Apple Silicon Mac running macOS 14 or later.

Installation

Choose the installation method that suits you. Downloading a pre-built release is the fastest path; building from source is useful if you want to modify the code or stay on the latest commit.

Download Release (Recommended)
Build from Source

Download the latest pre-built binary, extract it, and run the installer script. The script checks for Homebrew dependencies (whisper-cpp and portaudio), installs the binary to ~/.local/bin/localvoice, registers the LaunchAgent, and prints the next steps.

curl -sL https://github.com/npateriya/LocalVoiceAI/releases/latest/download/localvoiceai-darwin-arm64.tar.gz | tar -xz
cd localvoiceai-darwin-arm64
bash install.sh

Clone the repository, install Homebrew dependencies, then build and install the binary. make setup installs pkg-config, portaudio, and whisper-cpp via Homebrew and creates the required symlinks. make install compiles the Go binary with CGo, code-signs it, and registers the LaunchAgent.

make setup    # install Homebrew dependencies
make install  # build, install, and register LaunchAgent

Finishing Setup

Grant macOS Permissions

LocalVoiceAI requires two privacy permissions to operate. Open System Settings → Privacy & Security and add ~/.local/bin/localvoice to both lists:

Accessibility — allows LocalVoiceAI to simulate Cmd+V and paste transcribed text into the active window.
Input Monitoring — allows LocalVoiceAI to detect the Fn+F10 keypress system-wide, regardless of which app has focus.

Make sure both toggles are blue (enabled) before continuing. See the Permissions page for detailed screenshots and troubleshooting.

Start the Service

Load the LaunchAgent to begin listening for keypresses. If you installed from the release tarball:

launchctl start com.localvoiceai.localvoice

If you built from source, you can use the Makefile shortcut instead:

make start

Dictate Into Any App

Switch to any application — a chat window, a code editor, a browser text field, a terminal — and try it out:

Place your cursor where you want text to appear.
Hold Fn+F10.
Speak naturally.
Release Fn+F10.

LocalVoiceAI captures your audio, transcribes it locally on the Metal GPU, and pastes the result at the cursor within one to two seconds.

Check the Logs

If something doesn’t work as expected, inspect the live log output:

tail -f /tmp/localvoice.log

The log shows recording start/stop events, transcription output, and any errors — including missing-permission messages.

The two privacy permissions persist across reboots, so you only need to grant them once. However, if you later run make update to rebuild and reinstall the binary, both permissions must be re-granted because the binary hash changes and macOS invalidates the previous authorization.

On first run, LocalVoiceAI automatically downloads the Whisper ggml-small model (~244 MB) from HuggingFace to ~/.cache/localvoice/. This happens once in the background — you will see download progress in the log. Subsequent starts use the cached model and are instantaneous.

Getting Started

Usage & Configuration

Service Management

Architecture

LocalVoiceAI Quickstart: Install and Start Dictating

Installation

Finishing Setup

Build docs developers (and LLMs) love

Getting Started

Usage & Configuration

Service Management

Architecture

Documentation Index

​Installation

​Finishing Setup

Build docs developers (and LLMs) love

Installation

Finishing Setup