​
This process is not trusted

Grant Accessibility permission to the wh process, not only to your terminal app. System Settings opens automatically on first run. If it does not open: 
open x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility
Enable wh, then restart: 
wh restart

​
Double-tap does not start recording

Tap Right Option twice within the configured threshold. The default is 0.4 seconds. To change it, edit hotkey.double_tap_threshold in ~/.whisper/config.toml or use the Recording settings panel.

​
Apple Intelligence grammar does not work

Verify:
  1. macOS 26 or later
  2. Apple Silicon
  3. Apple Intelligence enabled in System Settings
If any requirement is missing, use Ollama, LM Studio, or disabled grammar mode.

​
Ollama grammar does not work

Verify: 
ollama pull gemma3:4b-it-qat
ollama serve
curl http://localhost:11434/
Then choose Ollama from Settings, the menu bar, or wh backend ollama.

​
LM Studio grammar does not work

Verify:
  1. LM Studio is installed.
  2. A model is downloaded and loaded.
  3. The local server is started from the Developer tab.
  4. The API responds:
curl http://localhost:1234/v1/models
Loading a model is not enough. The local server must be running.

​
First transcription is slow

Fresh setup downloads and warms the active engine. Later runs load cached models from disk. Qwen3-ASR downloads when you switch to it. WhisperKit manages its own model folder. Kokoro downloads only after text-to-speech is enabled. Settings marks a managed MLX model as downloaded only after a complete Hugging Face snapshot is present. Partial caches show as partial and can be resumed from the Transcription panel. If idle model unload is enabled, Local Whisper may release the active model from RAM while the background service stays ready. The next transcription reloads the model on demand. wh setup, wh update, and wh restart treat the service as ready once the command socket is accepting commands, even if the model is currently unloaded. Model preparation in setup/update is bounded. If a local model check takes too long, setup continues and the model retries on first use; required update preparation fails instead of hanging indefinitely.

​
Empty transcription

Check microphone permission, input-device selection, and speech level. If macOS routes input to a virtual device such as BlackHole, select a real microphone in System Settings -> Sound -> Input. If macOS did not show a prompt during setup, use Settings -> Advanced -> Permissions to request Microphone and Accessibility again. If the first recording after sleep, wake, or long idle is empty, try once more. Local Whisper backs off, refreshes the CoreAudio device list, and resets stale macOS input streams when it sees all-zero audio or a PortAudio input error.

​
Overlay is not visible

Check: 
[ui]
show_overlay = true
Fullscreen spaces and display changes can affect where the overlay appears. Restarting the service resyncs the Swift UI and Python service state.