​
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:
Enable wh, then restart:

​
macOS keeps asking for permissions with new “python3.x” entries

macOS identifies the service by the code hash of the binary it runs. Older installs launched the service through a Python interpreter symlinked into Homebrew, so every Homebrew Python upgrade made macOS treat Local Whisper as a brand-new app: a fresh permission prompt appeared, and the old python3.x rows in Privacy & Security went stale. Current installs run the service through a frozen interpreter copy named local-whisper, whose identity survives Python upgrades. To migrate an older install:
Grant Accessibility and Microphone to local-whisper one final time, then remove the stale python3.x rows in System Settings -> Privacy & Security -> Accessibility (select a row, press the minus button). wh doctor reports whether the service runtime identity is stable.

​
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:
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:
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 the selected 1.7B or 0.6B model when you switch to it. The 1.7B default requires more memory and has higher latency; choose 0.6B in Settings or wh config on a tighter-memory Mac. macOS manages Apple SpeechTranscriber assets per locale, and Local Whisper shows Apple’s real supported, downloading, or installed state. 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 Qwen starts inserting Vocabulary terms that were not spoken, shorten the word list or turn off Use Vocabulary as context in Qwen3-ASR Settings. Context can bias recognition but cannot guarantee a spelling. Local Whisper caps the prompt at 4,096 characters, logs how many eligible rules were included when the list is truncated, and still applies enabled replacement rules after transcription. 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:
Fullscreen spaces and display changes can affect where the overlay appears. Restarting the service resyncs the Swift UI and Python service state.