First-time setup

Assumes Install & permissions is done. Screenshots below are captured from the marketing settings UI replica (public/screenshots/setup-*.webp).

Overview

Step	Where	Goal
1	Menu bar → Settings	Open the main UI
2	General	Turn off demo mode for real dictation
3	Voice models	Pick an engine and key if needed
4	Shortcuts	Confirm dictation ⌃⌥Space, command ⌃⌥C (rebindable)
5	Text processing	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: Shortcuts, Voice models, Text processing, Voice commands
   • Tools: File transcription, History

Fig. 1 · Settings (UI replica · setup-01-settings.webp)

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 (UI replica · setup-02-demo.webp)

When to keep demo on

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

3. Choose a voice model

1. Open Settings → Voice models.
2. Pick an engine, e.g.:
   • Apple (on-device; good first success path)
   • Doubao and others (see Plans for Free limits)
   • Bailian / MiMo / OpenAI Speech / 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 · Voice models (UI replica · setup-03-models.webp)

Fastest path

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

Local Only Mode

If Local Only is on, public cloud engines fail. Use Apple, the four built-in on-device engines (SenseVoice / Whisper Turbo / Fun-ASR-Nano / Parakeet), or localhost — or turn Local Only off temporarily.

4. Confirm shortcuts

1. Open Settings → Shortcuts.
2. Find Voice typing — default is usually ⌃⌥Space; Voice command defaults to ⌃⌥C.
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, Voice translation, and Direct Voice Typing (skips polish; unbound by default) later.
6. If the page warns about Accessibility, finish Install & permissions.

Fig. 4 · Shortcuts (UI replica · setup-04-hotkeys.webp)

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

5. Text processing (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 processing (UI replica · setup-05-postprocess.webp)

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 voice typing (UI replica · setup-06-try.webp)

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.