Whisper is genuinely good. It also consistently mangles "GitHub", "WhisperKit", your company name, and that one package manager your team uses. A replacement dictionary is the cheapest fix — and you don't have to be an engineer to set one up.

What is custom vocabulary dictation on Mac?

The reason this matters: Whisper was trained on a giant slice of the public web (per the original OpenAI paper "Robust Speech Recognition via Large-Scale Weak Supervision"). That's wonderful for general English and rough coverage of programming terms. It's terrible for the words that exist only in your team's Slack history.

Why does Whisper keep misspelling brand names?

The honest version: no vocabulary list will turn a noisy café recording into clean medical terminology. What it will do is stop the most embarrassing, most repetitive failures — the ones where you end up correcting the same word ten times a day.

How does MetaWhisp's replacement dictionary work?

MetaWhisp's replacement dictionary has two parts, and they do different jobs. The first part is a vocabulary list fed into WhisperKit as an initial prompt before each transcription. WhisperKit runs Whisper large-v3-turbo on Apple's Neural Engine, and it accepts a string of "expected words" that biases the decoder toward. If "WhisperKit" is in your list, the model is more likely to output "WhisperKit" than "whisper kit" when it hears the phonemes. The second part is a post-transcription rewrite. After the model produces text, MetaWhisp runs the transcript through your replacement rules and substitutes the canonical form. So even if the model misses the bias, the rewrite catches it. Both run locally. Your audio never leaves the Mac, your vocabulary file never leaves the Mac, and no telemetry about your words goes anywhere. That's the whole point of running Whisper on the Neural Engine instead of piping audio to a cloud API.

Pro tip: Don't try to be exhaustive on day one. Add the ten words that broke yesterday. Add the next five when they break. A short, accurate list beats a giant one full of guesses.

Setting up custom vocabulary in MetaWhisp (step by step)

The exact labels in the UI move as the app evolves, but the workflow is the same:

1. Open MetaWhisp and hit the global hotkey — Right Option (⌥) by default, see the global hotkey page if you want to rebind it — to make sure the app is running and responsive.
2. Find the vocabulary or replacement dictionary panel in Settings. In recent builds it's a dedicated section: one field for the spoken form, one for the written form, plus a toggle to enable the list globally.
3. Add your first entry. Type the spoken form on the left (what you actually say out loud), the written form on the right (what should land in your app). For brand names the spoken and written forms are usually identical except for capitalization.
4. Save and toggle the dictionary on. The replacement pass kicks in immediately; the prompt bias applies on the next dictation.
5. Test it. Switch to any text field — Notes, Messages, your IDE — hold Right Option, say a sentence with one of your target words, release. Verify the spelling.

If a word doesn't stick, jump to the troubleshooting section below — the most common cause is that the spoken form differs from how you actually pronounce it.

What kinds of words should I add to a custom vocabulary list?

The list is yours. In practice, four buckets cover most of the wins:

Brand names, product names, company names

The single highest-value category. Anything with unusual capitalization, punctuation, or a made-up spelling: - "Liquid" → "Liquid" (the Shopify template language) - "Framer" → "Framer" - "Vercel" → "Vercel" - "WhisperKit" → "WhisperKit" - "PostHog" → "PostHog" The model almost always has a "default" guess for these that isn't the canonical form. Your list overrides that guess.

Acronyms and jargon that look like other words

- "REST" → "REST" - "GraphQL" → "GraphQL" - "macOS" → "macOS" - "OAuth" → "OAuth" Without the list, Whisper writes them in lowercase or splits them into multiple words.

Code identifiers and package names

Useful if you dictate into a code editor or write technical docs: - "useState" → "useState" - "pnpm" → "pnpm" - "tRPC" → "tRPC" - "next.config.js" → "next.config.js" For longer code blocks, see the snippet section below — that's where custom vocabulary meets custom snippets.

Names of people, places, and pets

The hardest category. Whisper will pick the closest English-sounding name it knows. Add your colleagues, your clients, the schools your kids attend. Test each one — the spoken form has to match how you actually say the name, not how it's spelled.

Can a vocabulary list insert whole snippets?

Yes — and this is where it gets fun. The replacement field isn't limited to single words. You can map a spoken trigger to a multi-line snippet: - spoken: "insert my email signature" → written: your full email signature block - spoken: "insert pull request template" → written: your team's PR template - spoken: "insert standup update" → written: the standup format you use every morning The spoken form has to be unique enough that you don't trigger it by accident. Short triggers ("sign off", "PR") collide with normal speech. Longer triggers ("insert email signature") are safer. This pairs naturally with MetaWhisp's processing modes. Use the Rewrite mode to polish a dictated draft, then trigger a snippet to drop a standardized closing block underneath. The combination gets you most of the way to a fully dictated email in a few seconds.

What custom vocabulary can't fix

I want to be straight with you, because honest tradeoffs are the whole point of this blog.

Common mistakes when configuring custom vocabulary

A few patterns I see over and over: **Putting the written form in the spoken field.** If you say "GitHub" out loud but type "github" in both fields, the model gets the right hint — but you also lose the chance to fix the capitalization in the rewrite step. Always put what you actually say in the spoken field, what you want to see in the written field. **Adding too many entries at once.** A very long list dilutes the bias. Whisper treats all the prompt words roughly equally; the more you add, the less weight each one carries. Keep the working list reasonably short and rotate in new ones as needed. **Using acronyms as spoken forms without testing.** "REST" might work fine when you say "rest", but if you say "R-E-S-T" letter by letter, the model hears four separate letters and your entry won't match. Match the spoken form to your pronunciation, then test. **Forgetting to retest after macOS updates.** Apple has been changing the microphone permission and Speech framework behavior across releases — see the Apple Intelligence dictation issues post for the recent history. If your list stops working, check microphone permissions first.

Founder's note: My own working list has 23 entries — mostly brand names and Russian-to-English transliterations for the words Whisper consistently mangles in my accent. Anything I haven't hit twice in a week gets removed.

Combining custom vocabulary with post-processing

If you want the polished output to go further than spell-correction, pair the replacement dictionary with MetaWhisp's Correct or Rewrite processing modes. On the free tier you can plug in your own OpenAI or Cerebras API key — only the transcript text goes out, never the audio — and let an LLM clean up filler words, fix punctuation, and reshape structure. If you don't want any data leaving the Mac at all, skip the cloud processing modes and rely on the replacement dictionary plus your own light editing. That's the most private setup and it's what I run most days. For the workflow that takes dictation all the way to publishable prose, see how to remove filler words from Whisper transcripts.

Troubleshooting entries that don't stick

If a word isn't being transcribed correctly despite being in your list: 1. Check the spoken form. Open the dictionary panel and read the spoken form back out loud. If you don't naturally say it that way, change it. 2. Try the rewrite-only path. Some words the model will consistently mishear no matter how strong the bias. For those, rely entirely on the post-transcription rewrite — make sure the spoken form in your entry matches what Whisper actually outputs, and the written form is what you want. 3. Reduce competing entries. If "Postgres" and "PostgreSQL" and "PostgresQL" are all in your list, the model gets confused. Pick one canonical form and delete the others. 4. Reboot MetaWhisp. Settings changes occasionally need an app restart to take effect on the prompt path. 5. Test in a clean environment. Switch to TextEdit, dictate a single sentence with the target word, see what comes out. If it works there, the issue is the destination app, not the dictionary. If none of that helps, the term is probably too far outside Whisper's training distribution for prompt bias to reach. At that point your best bet is the Correct or Rewrite processing mode with an LLM, which can take a fuzzy transcript and produce the right term contextually.

Is custom vocabulary dictation on Mac worth setting up?

Yes, if any of these sound familiar: - You dictate every day and you keep correcting the same five words. - Your work involves specific brand names, packages, or technical terms Whisper has never heard of. - You want your transcripts to land in apps already correctly spelled without manual cleanup. If you dictate rarely, or your work is general prose, you can probably skip it. The base accuracy of Whisper large-v3-turbo on standard English is good enough that a vocabulary list is icing, not cake. For everyone else: it's a quick setup that pays back over time. Download MetaWhisp, add the ten words that broke yesterday, and stop retyping "GitHub" for the rest of your life.

Frequently asked questions