Support & Troubleshooting

Everything you need to get the most out of SpokenKey. Can't find your answer? Email hello@spokenkey.com and you'll hear back quickly.

Menu bar reference

Click the SpokenKey icon in your menu bar to access these options.

Recording

Record / Stop Recording: Click to start or stop a recording manually. You can also hold your hotkey to record — release to stop and transcribe.
Hotkey: Choose which key to hold while dictating. Five presets: Right Option (default), Right Command, Fn (Globe), F5, or F6. The change takes effect immediately.
Engine: Shows which speech model is active. Parakeet TDT is the primary model — it handles all transcription locally on your Mac.

Settings

Output Mode: Controls where your transcribed text goes. "Paste" (default) types it at your cursor. "Clipboard" copies it without pasting. "File" appends to a running notes file at ~/.config/voice-dictation/dictation-notes.txt.
Sound Effects: Plays a short audio cue when recording starts and stops, so you know when SpokenKey is listening.
Launch at Login: Starts SpokenKey automatically when you log in to your Mac. Installs a standard macOS LaunchAgent — disable anytime from this menu.
AI Cleanup: When enabled, your transcription is polished by a local AI (Ollama + Llama 3.2) before pasting — fixing grammar, punctuation, and capitalization. Requires Ollama to be installed. Completely optional.
Voice Commands: When enabled, spoken phrases like "new paragraph", "bullet point", "comma", and "period" are converted into formatting instead of being typed as words. Say "delete that" to erase the last dictation.
Streaming: When enabled (on by default), text appears as you speak in real time. When you release the hotkey, the final transcription replaces the streamed text for better accuracy. Only works with "Paste" output mode — other modes use standard transcription.

Utilities

History Log: Opens your transcription history file. Every dictation is logged with a timestamp. When AI cleanup changes the text, the original transcription is also logged so you can recover it.
Edit Vocabulary: Opens your custom vocabulary file (vocabulary.json) for editing. Add word corrections that apply to every transcription — useful for names, technical terms, or words the model consistently gets wrong. See the vocabulary section below for format details.
Status: Shows the current state of SpokenKey — whether it's ready, recording, or processing a transcription.

Other

License: Shows your license status (app version only). Enter or update your Gumroad license key here.
Help & Support: Links to this support page at spokenkey.com/support.
Check for Updates: Checks if a newer version of SpokenKey is available. If one is found, you'll be directed to download it from Gumroad.

Custom vocabulary

SpokenKey lets you define custom word corrections that are applied to every transcription. This is useful for names, technical terms, acronyms, or any word the model consistently gets wrong.

How it works

Click Edit Vocabulary in the SpokenKey menu bar
This opens vocabulary.json in your default text editor
Add corrections as key-value pairs — the key is what the model transcribes, the value is what you want instead
Save the file. Corrections apply to the next dictation automatically

Example vocabulary.json

{
  "spokenkey": "SpokenKey",
  "macOS": "macOS",
  "VS code": "VS Code",
  "kubernetes": "Kubernetes",
  "tyler": "Tyler"
}

Matching is case-insensitive— if the model transcribes "spokenkey", "Spokenkey", or "SPOKENKEY", it will be corrected to "SpokenKey".

The vocabulary file is stored at ~/.config/voice-dictation/vocabulary.json. If the file doesn't exist, SpokenKey creates an empty one when you click Edit Vocabulary.

Troubleshooting

The app says it can't be opened or is from an unidentified developer: SpokenKey is signed and notarized by Apple, so this shouldn't happen. If it does: right-click SpokenKey.app, choose "Open", then click "Open" in the dialog. This overrides the Gatekeeper check. If you still see a warning, make sure you downloaded the DMG directly from Gumroad — not from a third-party site.
My hotkey doesn't work: SpokenKey needs Accessibility permission to detect your hotkey. Open System Settings > Privacy & Security > Accessibility, find SpokenKey, and make sure it's toggled on. If it's already on, try toggling it off and back on, then relaunch SpokenKey.
My hotkey stopped working after an update: macOS sometimes revokes Accessibility access when an app is updated (even though the toggle still looks "on" in System Settings). The fix: open System Settings > Privacy & Security > Accessibility, toggle SpokenKey off, toggle it back on, then quit and relaunch SpokenKey. This clears the stale permission cache.
No audio is being captured / "No speech detected": Check that microphone permission is granted: System Settings > Privacy & Security > Microphone > SpokenKey. If you're using an external mic or Bluetooth headset, make sure it's selected as the input device in System Settings > Sound > Input. Try disconnecting and reconnecting if using Bluetooth.
The first dictation after restarting my Mac is slow: This is normal. The speech model needs to load into memory on first use (~2-3 seconds). After that, subsequent dictations start instantly. If you have AI cleanup enabled, the first dictation may also need to load the Ollama model.
I enabled streaming mode but nothing changed: Streaming mode only works when the output mode is set to "Paste" (the default). If you've changed your output mode to "Clipboard" or "File", streaming silently falls back to standard mode. Change output mode back to "Paste" in the menu bar to use streaming.
AI cleanup says Ollama is not found: AI cleanup requires Ollama (a free, separate app). If you skipped the Ollama setup on first launch, you can install it anytime from ollama.com. Once installed, open Ollama, then run "ollama pull llama3.2:3b" in Terminal. Or just disable AI cleanup from the SpokenKey menu — the app works great without it.
The model download seems stuck: The speech model is ~540 MB and can take several minutes on slower connections. If the progress bar hasn't moved in more than 5 minutes, try quitting SpokenKey and relaunching — the download will resume. Make sure you have a stable internet connection for this one-time download.
Text is appearing incorrectly or getting garbled: If you're dictating very long passages (500+ characters) with streaming mode, the text replacement step can occasionally conflict with cursor movement. Try shorter dictations, or switch to standard mode (disable streaming in the menu bar) for long-form work. Check your transcription history log (accessible from the menu bar) to see what was actually transcribed.
How do I change the hotkey?: Click the SpokenKey icon in your menu bar, go to Hotkey, and choose from 5 presets: Right Option, Right Command, Fn (Globe), F5, or F6. The change takes effect immediately.
How do I get a refund?: There's a 14-day money-back guarantee, no questions asked. Request a refund directly through Gumroad (in your purchase receipt email or at app.gumroad.com/library) or email hello@spokenkey.com.
How do I check for updates?: SpokenKey checks for updates automatically when it launches. If a new version is available, you'll see "Update Available" in the menu bar. Click it to download the latest version from Gumroad.