GabbleCustom vocabulary for Mac dictation: names and jargon
Dictation is good at ordinary words and bad at yours. Your surname, your company, the drug names or part numbers you use every day: none of them were common in the speech the model learned from. A custom vocabulary fixes that. Here is how to build one that works.
Why does dictation get names and jargon wrong?
It gets them wrong because a speech model picks the most likely text for a sound. "Karakabakov" is not likely. "Kara kaba cough" is made of pieces the model has seen before, so that is what you get.
You see the same thing with:
- People's names and company names
- Product names with odd capitalisation, like iPhone or GitHub
- Acronyms, which come out as words or as spaced letters
- Technical terms and identifiers
- Words from another language dropped into a sentence
The model is not broken. It has no way to know the word exists unless you tell it.
How do you add custom vocabulary in Gabble?
You add terms in the Dictionary tab, each with the spelling you want and the wrong versions to replace.
- Dictate a few sentences that use the term, the way you normally would.
- Look at what came out. The History tab is searchable if you want to find older examples.
- Open the Dictionary tab and add the term with its correct spelling.
- Add each wrong version you saw as a "heard as" entry.
- Dictate the sentence again to check.
Each entry has two parts:
| Preferred spelling | Heard as |
|---|---|
| Karakabakov | kara kaba cough, caracabakov |
| GitHub | git hub, Github |
| PostgreSQL | post gress, postgres q l |
| Dr. Nguyen | doctor win, doctor new yen |
These "heard as" values are examples. The ones that matter are the ones your voice and your model produce, which is why step 1 comes first.
Gabble also corrects the letter case of a term on its own. If you add "GitHub" and the transcript says "github", it is fixed without a "heard as" entry.
How does the dictionary work under the hood?
It works in up to three places, depending on your model and settings.
| Stage | What the dictionary does | When it applies |
|---|---|---|
| Recognition | Biases the speech model towards your terms | Whisper models only |
| Text replacement | Swaps "heard as" versions for the preferred spelling | Always, with every model |
| AI cleanup | Tells the AI to spell your terms exactly | Only when AI cleanup is on |
The middle row is the dependable one. It is a plain replacement on your Mac. It does not need AI and it behaves the same every time.
The first row is why the model choice matters if your vocabulary is unusual. Gabble's default model is Parakeet v3, which does not take vocabulary hints. If you find yourself adding many "heard as" versions for the same term, try a Whisper model, since the recogniser is then nudged towards your spelling in the first place. Whisper vs Parakeet covers the trade-offs.
What makes a good dictionary entry?
A good entry is specific and based on a mistake you have actually seen.
Do add:
- The exact wrong versions from your own transcripts
- Multi-word mishearings, because that is how long names usually break
- Capitalisation you care about, like product names
Be careful with:
- "Heard as" versions that are real words you also use. If you map "win" to "Nguyen", every "win" becomes "Nguyen". Use a longer phrase such as "doctor win" to keep the replacement narrow.
- Guesses. A long list of versions you imagined adds risk and fixes nothing.
Start with five or ten terms that annoy you most. Add more when you notice a new repeat mistake.
When should you use a snippet instead?
Use a snippet when you want a short phrase to turn into a long block of text. The Snippets tab pairs a trigger phrase with an expansion. You say the trigger and the expansion is inserted.
| Trigger phrase | Expands to |
|---|---|
| "my address" | Your full postal address |
| "standard sign off" | Your email closing and name |
| "meeting link" | Your calendar booking URL |
The rule of thumb: the dictionary is for words that come out wrong, and snippets are for text you do not want to say in full. A long URL is a snippet. A misspelled surname is a dictionary entry.
What about punctuation and layout?
You speak those as commands. Gabble recognises "new line", "new paragraph", "bullet point", "open quote", "close quote", "open paren" and "close paren". They are built in and need no setup.
How is this different from Apple's Dictation?
Apple's Dictation guide does not describe a custom dictionary for Dictation. macOS has other features in this area, such as text replacements in Keyboard settings and vocabulary for Voice Control, and this guide does not cover those. Several third-party dictation apps offer a dictionary of some kind. The comparison of Mac dictation apps lists which.
Does any of this leave your Mac?
No, unless you turn on AI cleanup with a cloud provider. The Dictionary and Snippets are applied on your Mac. Speech recognition runs on your Mac. If you enable AI cleanup with your own API key, your dictionary terms are included in the request along with the transcript text, so the AI can spell them. With Ollama that request stays on your Mac as well.
If you have not tried it yet, download Gabble. It is free and needs an Apple Silicon Mac on macOS 14 or later. Developers should also read voice coding on Mac for identifier-specific tips.
Frequently asked questions
How do I add custom words to dictation on a Mac?
In Gabble, open the Dictionary tab, add the word with the spelling you want, and list the wrong versions under 'heard as'. From then on those versions are replaced automatically.
Why does dictation keep misspelling my name?
Speech models choose the most likely spelling for a sound, and unusual names lose to common words. A dictionary entry with the misheard version fixes it after transcription.
Does a custom dictionary work offline?
Yes. Gabble's Dictionary and Snippets run on the Mac and do not need a connection or AI cleanup.
Does the dictionary work with Parakeet and Whisper?
The replacements work with both, because they run on the text. Biasing the recogniser itself towards your terms applies to Whisper models only.
What is the difference between a dictionary entry and a snippet?
A dictionary entry corrects how a word is spelled. A snippet replaces a short trigger phrase with a whole block of text, such as an address or a sign-off.
How many 'heard as' versions should I add?
Add the ones you actually see. Dictate the term a few times, check the output, and add each wrong version that shows up.
Try Gabble
Free dictation for Mac that runs on your machine. No account.