First-time setup

Assumes Install & permissions is done. Dashed frames are screenshot placeholders (public/screenshots/setup-*.svg).

Overview

Step	Where	Goal
1	Menu bar → Settings	Open the main UI
2	General	Turn off demo mode for real dictation
3	Dictation models	Pick an engine and key if needed
4	Hotkey	Confirm dictation ⌃⌥Space, command ⌥Space (rebindable)
5	Text post-process	Spacing / polish (defaults OK)
6	Notes, etc.	End-to-end test

1. Open Settings

1. Click the VoiceHotkey menu bar icon.
2. Choose Settings.
3. Sidebar groups:
   • App: General, About, License
   • Voice: Hotkey, Dictation models, Text post-process, Voice commands
   • Tools: Transcribe files, History

Fig. 1 · Settings (placeholder · setup-01-settings.svg)

Deeplink

voicehotkey://tab/settings — see Deeplinks.

2. Demo mode

Demo mode skips the microphone and uses demo text so you can explore the UI. Turn it off for real dictation.

1. Open Settings → General.
2. Find Demo mode.
3. For real typing: switch it off.
4. Menu bar status should stop saying demo / mic unused; fix any mic or engine warnings next.

Fig. 2 · General · Demo mode (placeholder · setup-02-demo.svg)

When to keep demo on

UI exploration only, no recording. File transcription may also skip real uploads in demo mode.

3. Choose a dictation model

1. Open Settings → Dictation models.
2. Pick an engine, e.g.:
   • Apple (on-device; good first success path)
   • Doubao and others (see Plans for Free limits)
   • Whisper / Groq / Soniox / NVIDIA… (multi-engine on Trial/Pro)
3. Cloud engines: paste an API key (stored in the Keychain).
4. Fill model id, language, context terms as needed.
5. Confirm no “not configured” errors on the page.

Fig. 3 · Dictation models (placeholder · setup-03-models.svg)

Fastest path

Start with Apple or one cloud engine you already have a key for. Details: Dictation models.

Local Only Mode

If Local Only is on, public cloud engines fail. Use Apple / localhost, or turn Local Only off temporarily.

4. Confirm hotkeys

1. Open Settings → Hotkey.
2. Find Voice typing — default is usually ⌃⌥Space; Voice command defaults to ⌥Space.
3. Tap toggles recording; hold talks until release (per trigger mode).
4. If it conflicts, re-record a different chord.
5. Optional: bind Voice command and Voice translation later.
6. If the page warns about Accessibility, finish Install & permissions.

Fig. 4 · Hotkeys (placeholder · setup-04-hotkeys.svg)

Quick Send, Esc cancel, and sounds live mainly under General. See Hotkeys & recording.

5. Text post-process (defaults OK)

Option	First run
Strip trailing period	Useful for chat
Smart spacing / paragraphs	Defaults are fine
Word replacements	Add when you have fixed errors
LLM polish	Needs LLM key; later
Output action	Default: insert at caret
Translation	Separate hotkey + model

Fig. 5 · Text post-process (placeholder · setup-05-postprocess.svg)

6. End-to-end test

1. Open Notes or any text field and click so the caret blinks.
2. Press your voice typing hotkey (overlay / status should change).
3. Speak a short sentence.
4. Tap again or release hold to finish.
5. Wait for ASR (and optional polish); text should appear at the caret.
6. Optional: check History for a new entry.

Fig. 6 · Try dictation (placeholder · setup-06-try.svg)

Success criteria

• Recording feedback
• Text appears after release
• Text lands in the focused field

If it fails

Symptom	Go to
No hotkey response	Troubleshooting · hotkey
Recording but no text	Troubleshooting · no text
Permissions keep dropping	Troubleshooting · permissions

After setup

Word replacementsFix brand names and habitual ASR errors.

Local Only ModeBlock the public internet.

Voice commandsBuilt-in/user dictionary and intent; custom phrases in Settings.