superwhisper Vocabulary and Replacements: teach it your words without making it worse
By Ryleigh Newman · Published
superwhisper gives you two tools for words it gets wrong, and they work in opposite ways. Vocabulary words are hints sent with your audio, so the model is more likely to hear a name or a term. Replacements run after the text exists and swap one string for another, exactly as you set them. Using the wrong one, or too many hints, is a common reason superwhisper gets worse instead of better.
I built YapToText, a different dictation app for the Mac, so read what I say about superwhisper with that in mind. Every fact about superwhisper here comes from its own docs, read on October 10, 2026.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
This guide in other languages: العربية, Čeština, Dansk, Deutsch, Ελληνικά, Español, Suomi, Français, עברית, हिन्दी, Magyar, Bahasa Indonesia, Italiano, 日本語, 한국어, Norsk, Nederlands, Polski, Português, Română, Русский, Slovenčina, Svenska, ไทย, Türkçe, Українська, Tiếng Việt, 简体中文, 繁體中文
On this page: 9 sections
The two tools side by side
From superwhisper's docs, Vocabulary, read October 10, 2026.
| Vocabulary words | Replacements | |
|---|---|---|
| When it works | Before transcription, sent with your audio as hints | After transcription, on the finished text |
| What it does | Makes the model more likely to recognize a word | Swaps one string for another, with no AI involved |
| Guaranteed | No. It nudges the model, and the effect varies by model | Yes. The same result every time, whatever the model |
| Good for | Names, acronyms, company names, jargon, words from other languages | Errors that keep coming back, symbols, email addresses, phrases you expand |
| Risk | A long list can confuse the model and change punctuation | Little. Matching ignores capitals |
Keep the vocabulary list short
The docs are direct about this. Too many vocabulary words can confuse the transcription model, words in other languages can hurt accuracy and automatic language detection, and vocabulary shapes punctuation and formatting, not just spelling. Their advice is to keep the list short and use replacements for corrections that must be consistent.
If superwhisper started adding words or repeating text after you added a lot of vocabulary, the page on added and repeated words covers that case.
How replacements behave
- Case does not matter when matching. A replacement for todo also catches ToDo, TODO and Todo.
- Case does matter in the output. The text comes out exactly as you typed it in the replacement.
- One wrong word, many spellings. If a word is misheard several ways, add a replacement for each one and point them all at the right spelling.
- Independent of the model. They apply the same way whichever voice model transcribed the text.
Symbols and email addresses
Voice models are tuned for speech, so an at sign or a slash rarely comes out as a symbol. The docs suggest a set of replacements for this:
From superwhisper's docs, Vocabulary, read October 10, 2026. The docs list dash as well.
| Say | Get |
|---|---|
| at sign | @ |
| dot com | .com |
| dot net | .net |
| dot org | .org |
| hashtag | # |
| slash | / |
| underscore | _ |
For addresses you use often, add each one as a replacement, for example a phrase like my work email that turns into the address. For a one-off address, say it as name, at sign, domain, dot com, and let the symbol replacements do the rest.
Where to find them
Both live in Settings, Vocabulary in the Mac app, in the same list. Click the trash icon beside an item to remove it. From the terminal, the superwhisper CLI has superwhisper vocab for vocabulary words and superwhisper snippets for replacements, which the CLI docs describe as the same From and To pairs as the app.
Moving to a new Mac? Vocabulary travels with the rest of your settings, as the backup page explains, and the CLI page covers the other commands.
One vocabulary trick for language detection
When the language is set to Automatic and dictation keeps coming out in English, superwhisper's docs suggest adding one phrase in your language to the vocabulary list as a hint, or setting a fixed language. The hint works through the model, so its effect varies by model. The page on changing the language has the steps.
How YapToText handles the same job
superwhisper from its docs, read October 10, 2026. YapToText from its own settings.
| superwhisper | YapToText | |
|---|---|---|
| Hints to the speech model | Vocabulary words | Your dictionary words prime the Whisper model |
| Fixed swaps after | Replacements | Substitutions, with Whole word and Case options |
| More than one list | Not described in the docs | Several dictionaries, each can be turned off without deleting it |
| Learning from you | Not described in the docs | Fix the same word twice and it asks to make the correction stick |
| Per task | Not described in the docs | Each mode can use every enabled dictionary, or pick some |
YapToText also suggests fixes from your dictations, on the Mac, and the quickest way in is to select the right spelling anywhere, press the Quick Edit key and say add this to my dictionary. The dictionaries help page covers it, and the custom vocabulary guide compares the options on a Mac.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
The short version
- A name it never hears right. Add it as a vocabulary word.
- A word it always spells wrong. Add a replacement, one per wrong spelling.
- Symbols and emails. Replacements, such as at sign and dot com.
- Results got worse. Trim the vocabulary list.
- Terminal. superwhisper vocab and superwhisper snippets.
If superwhisper changes how these work, open an issue on GitHub and I will update this page. Every one gets read.
This app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.
Related
Sources
- https://superwhisper.com/docs/get-started/interface-vocabulary (checked 2026-10-10)
- https://superwhisper.com/docs/get-started/cli (checked 2026-10-10)
- https://superwhisper.com/docs/common-issues/language-detection (checked 2026-10-10)
- https://github.com/ryleighnewman/YapToText (checked 2026-10-10)
- https://apps.apple.com/us/app/yaptotext/id6786382289 (checked 2026-10-10)
Questions
What is the difference between vocabulary and replacements in superwhisper?
Vocabulary words are hints sent with your audio so the model recognizes a term. Replacements run after transcription and swap text exactly as you set it.
Why did superwhisper get worse after I added vocabulary?
Its docs say too many vocabulary words can confuse the model and affect punctuation and language detection. Keep the list short and use replacements for fixed corrections.
Are superwhisper replacements case sensitive?
Matching is not, so todo also matches TODO. The output uses the exact capitals you typed in the replacement.
How do I dictate an email address in superwhisper?
Add replacements such as at sign for @ and dot com for .com, or add a whole address as its own replacement.
Can I edit superwhisper vocabulary from the terminal?
Yes. The superwhisper CLI has vocab for vocabulary words and snippets for replacements.