Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/npateriya/LocalVoiceAI/llms.txt

Use this file to discover all available pages before exploring further.

Most LocalVoiceAI problems fall into one of a few categories: missing macOS permissions, a stale binary after a rebuild, a missing dependency, or a network issue during first-run model download. The sections below walk through each scenario with its symptoms, root cause, and exact fix.
SymptomThe log at /tmp/localvoice.log shows:
[ERROR] Event tap failed — missing permissions.
  1. System Settings → Privacy & Security → Accessibility → add localvoice
  2. System Settings → Privacy & Security → Input Monitoring → add localvoice
  Note: re-grant both permissions after every rebuild (binary hash changes)
Holding Fn+F10 produces no recording or transcription.Causelocalvoice creates a CGEventTap at the session level to detect F10 key presses system-wide. macOS requires two separate privacy permissions for this:
  • Accessibility — allows the process to simulate Cmd+V paste into the focused window
  • Input Monitoring — allows the process to observe all keystrokes system-wide
If either permission is missing or has its toggle switched off, the event tap fails immediately on startup and the service exits.Fix
  1. Open System Settings → Privacy & Security → Accessibility
  2. Add ~/.local/bin/localvoice and ensure the toggle is blue (enabled)
  3. Open System Settings → Privacy & Security → Input Monitoring
  4. Add ~/.local/bin/localvoice and ensure the toggle is blue (enabled)
  5. Restart the service: 
    make stop && make start
Both toggles must be blue. A grey toggle means the permission was granted at some point but is currently disabled — click it to re-enable.
SymptomRunning ./localvoice or ~/.local/bin/localvoice directly from a terminal window does not respond to F10 keypresses, even though permissions appear to be granted.CauseWhen you launch a binary directly from a terminal, the process inherits that terminal’s permissions context. iTerm2, VS Code’s integrated terminal, and similar apps may not hold an Input Monitoring entitlement themselves, which prevents any child process they spawn from receiving system-wide key events — even if localvoice is listed in the Input Monitoring preference pane.FixUse the LaunchAgent instead of running the binary directly. The LaunchAgent (com.localvoiceai.localvoice) runs as its own first-class process under launchd, completely independent of any terminal:
make install   # registers the LaunchAgent (first time only)
make start     # starts it
Once started this way, the service runs in the correct process context and responds to F10 from any app.
SymptomThe service appears to record and transcribe — [REC] and [OK] Pasted: lines appear in the log — but the pasted text is nonsense, unrelated words, or random characters.CauseThe most common cause is a sample rate mismatch between the audio capture rate and the rate Whisper expects. A secondary cause is a corrupted or incomplete model file.Fixlocalvoice auto-detects your microphone’s native sample rate (48 kHz or 44.1 kHz) via PortAudio and writes a correctly-headered WAV file at that rate, so no manual configuration is needed. If you’re seeing gibberish:
  1. Restart the service to clear any stale audio state: 
    make stop && make start
  2. Check the log for any [ERROR] lines from whisper-cli: 
    tail -f /tmp/localvoice.log
  3. If the model file is corrupted, delete it and let LocalVoiceAI re-download it on next start: 
    rm ~/.cache/localvoice/ggml-small.bin
make stop && make start
    The binary will download a fresh copy of ggml-small.bin (~244 MB) automatically.
Speak clearly and hold F10 for at least one full second before starting your phrase. Very short recordings (under ~250 ms) are discarded entirely with a [SKIP] Too short, ignored. log line.
SymptomThe service worked before, but after running make update it stops transcribing and the log shows the event tap error again:
[ERROR] Event tap failed — missing permissions.
Causemake update recompiles the binary from source and code-signs it with a new ad-hoc signature:
codesign -s - --force ~/.local/bin/localvoice
Every build produces a binary with a different cryptographic hash. macOS ties Accessibility and Input Monitoring grants to the specific binary hash, so when the hash changes, both permissions are automatically revoked — even though the file path is identical.FixAfter every make update, re-grant both permissions:
  1. Open System Settings → Privacy & Security → Accessibility
  2. Remove the old localvoice entry (if present) and re-add ~/.local/bin/localvoice
  3. Open System Settings → Privacy & Security → Input Monitoring
  4. Remove the old localvoice entry (if present) and re-add ~/.local/bin/localvoice
  5. Confirm both toggles are blue (enabled)
This is a one-time step per rebuild — the grants persist across reboots as long as the binary is not replaced.
This applies to make update only. make start, make stop, and make reload do not change the binary and therefore do not require a permission re-grant.
SymptomRunning make status prints Not running., or launchctl list | grep com.localvoiceai.localvoice returns no output. The service was previously installed but does not appear to be loaded.FixWork through these steps in order:
1

Check whether the plist is present

ls ~/Library/LaunchAgents/com.localvoiceai.localvoice.plist
If the file is missing, the LaunchAgent was never installed or was removed. Re-run the install:
make install
2

Load the plist if it exists but isn't registered

If the file is present but launchctl list shows nothing, load it manually:
launchctl load ~/Library/LaunchAgents/com.localvoiceai.localvoice.plist
3

Start the service

launchctl start com.localvoiceai.localvoice
Or with make:
make start
4

Check the logs for startup errors

tail -f /tmp/localvoice.log
Look for [ERROR] lines that indicate why the service failed to start (missing permissions, missing whisper-cli, etc.).
SymptomThe log shows:
[ERROR] whisper-cli not found. Run: brew install whisper-cpp
The service starts but immediately exits.Causelocalvoice shells out to the whisper-cli binary (provided by the Homebrew whisper-cpp package) to run inference on Apple Metal GPU. If whisper-cli is not installed or is not on the PATH the LaunchAgent uses, the process exits immediately.FixInstall whisper-cpp via Homebrew:
brew install whisper-cpp
The LaunchAgent plist sets the following PATH for the service process:
<key>PATH</key>
<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
This means whisper-cli must be located at /opt/homebrew/bin/whisper-cli (the standard Homebrew prefix on Apple Silicon). If you installed Homebrew to a non-standard location, update the PATH value in ~/Library/LaunchAgents/com.localvoiceai.localvoice.plist accordingly and run make reload.
SymptomThe log at /tmp/localvoice.log shows one of the following lines when you hold F10:
[ERROR] No input device: <error detail>
[ERROR] Cannot open mic: <error detail>
Recording never starts and nothing is transcribed.Causelocalvoice uses PortAudio to open the system’s default input device at its native sample rate. These errors occur when:
  • No microphone is connected or enabled (e.g. external USB mic unplugged, Bluetooth headset disconnected)
  • macOS has not granted the localvoice process Microphone access in Privacy & Security
  • The default input device is unavailable or in use by another exclusive-access application
Fix
  1. Confirm a microphone is connected and selected as the default input device in System Settings → Sound → Input.
  2. Open System Settings → Privacy & Security → Microphone and ensure ~/.local/bin/localvoice is listed and its toggle is blue (enabled).
  3. Restart the service to re-initialize PortAudio with the current device state: 
    make stop && make start
  4. Check the log again: 
    tail -f /tmp/localvoice.log
    A successful mic open will show a [REC] Recording at <rate>Hz... line when you next hold F10.
SymptomOn the very first start, the log shows:
[SETUP] Downloading Whisper model (~244MB) on first run...
[ERROR] Could not download model: ...
The service exits before transcription is available.CauseAt startup, localvoice checks for the model at ~/.cache/localvoice/ggml-small.bin. If the file is not found, it attempts to download it from Hugging Face. This can fail due to a network connectivity issue, a firewall blocking the Hugging Face domain, or insufficient disk space.FixEnsure you have at least 250 MB of free disk space, then try one of the following:Option 1 — Restart the service (it will retry the download):
make stop && make start
Option 2 — Download the model manually, then restart:
mkdir -p ~/.cache/localvoice
curl -L -o ~/.cache/localvoice/ggml-small.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin
make start
Once ~/.cache/localvoice/ggml-small.bin is present, localvoice skips the download step on all future starts.
For issues not covered here, open an issue on the GitHub repository at https://github.com/npateriya/LocalVoiceAI. Include the relevant lines from tail -100 /tmp/localvoice.log in your report to help with diagnosis.

Build docs developers (and LLMs) love

Get started for freeTalk to us