Install & permissions

After install and correct permissions, global hotkeys and dictation stay reliable. Dashed frames are screenshot placeholders — replace the SVGs under public/screenshots/ with real captures when ready.

Requirements

• macOS 14 or later
• Apple Silicon or Intel
• Optional: ASR / LLM API keys (BYOK)
• Real dictation needs: Microphone + Accessibility
• Apple Speech also needs: System Settings → Privacy & Security → Speech Recognition

1. Download the installer

1. Open Releases
   Go to VoiceHotkey-releases · Latest.

2. Download the DMG
   Pick the macOS .dmg asset. Do not use the Source code archives as the app.

3. Open the disk image
   Double-click the DMG and wait for the install window.

Fig. 1 · Releases page (placeholder · install-01-releases.svg)

2. Install to a stable path

1. Drag into Applications
   Drag VoiceHotkey.app into Applications, or into ~/Applications.

2. Eject the DMG (optional)
   Keep the DMG as a backup if you like.

3. Remember the path
   Always launch from the same location, e.g.

   • /Applications/VoiceHotkey.app
   • or ~/Applications/VoiceHotkey.app

Fig. 2 · DMG install window (placeholder · install-02-dmg.svg)

Fig. 3 · Confirm the app path (placeholder · install-03-path.svg)

Don’t run long-term from Downloads

Launching from ~/Downloads or a temp folder makes macOS treat Accessibility as a different app after moves or re-downloads — hotkeys “randomly” stop working. Install to Applications first, then grant access.

3. First launch

1. Open the app
   From Launchpad or Finder. If Gatekeeper blocks it, allow it under Privacy & Security (notarized builds are smoother).

2. Check the menu bar
   A mic-style icon should appear on the right. If missing, check menu-bar overflow or that the app is still running.

3. Finish onboarding
   First launch shows Quick setup (welcome → permissions → plan → done). You can grant access there or later in System Settings.

Fig. 4 · Menu bar icon (placeholder · install-07-menubar.svg)

Fig. 5 · Onboarding permissions (placeholder · install-06-onboarding.svg)

4. Grant Accessibility

Needed for global hotkeys, inserting text at the caret, and key injection. Without it, the hotkey usually does nothing.

1. Open System Settings → Privacy & Security → Accessibility.
2. Click + (or unlock) and add VoiceHotkey.app.
3. Confirm the path matches the app you actually run.
4. Turn the switch on.
5. If you see multiple “VoiceHotkey” rows: remove the old ones, keep only the current path, then quit and reopen the app.

Fig. 6 · Accessibility (placeholder · install-04-accessibility.svg)

Open from the app

Settings → General (or onboarding) usually has a button that jumps to Accessibility. After granting, the menu bar should stop warning “Need Accessibility”.

5. Grant Microphone

Required for real dictation. Demo mode can skip the mic; production use needs this.

1. Open System Settings → Privacy & Security → Microphone.
2. Enable VoiceHotkey.
3. Allow the system prompt on first recording if it appears.
4. For external mics, check System Settings → Sound → Input. Use the same device in app General if a mic picker is shown.

Fig. 7 · Microphone (placeholder · install-05-microphone.svg)

5b. Speech Recognition (Apple engine only)

Apple Speech / SpeechAnalyzer also needs Speech Recognition (SFSpeechRecognizer). Cloud engines (Doubao, Whisper, …) usually do not.

1. Open System Settings → Privacy & Security → Speech Recognition.
2. Allow VoiceHotkey.
3. If a language is unavailable, download it in System Settings or switch engines.

6. Permission checklist

Check	Expect
Menu bar icon	Visible, menu opens
Settings → General · permissions	Accessibility + mic granted; Speech Recognition if using Apple
Hotkey press	Overlay / status change (even in demo)
Install path	Matches Accessibility entry

Still broken? See Troubleshooting.

Next

First-time setupDemo mode, engine, hotkeys, and a real typing test.

Hotkeys & recordingTap / hold, Quick Send, cancel.