Dictionaries
Dictionaries are how you give Mac dictation custom vocabulary in YapToText. Each entry is a rule that says: when you hear this, write that. It fixes a name, a brand, or a piece of jargon the microphone keeps getting wrong, and it applies to every dictation from then on.
The same entries also change what the app hears. The spellings you put in are handed to the speech model as a prompt when it decodes your audio, so a name like mine comes out right the first time instead of being patched afterward. Everything here runs on your Mac and nothing is uploaded.
How a rule works
An entry has two fields. Heard is what the recognizer actually produces. Replace with is what you want typed instead. The built-in example is swift ui becoming SwiftUI. Mine is Riley becoming Ryleigh, because that is how the microphone hears my name.
Multi-word phrases work on both sides. A Heard phrase matches however the recognizer spaced it, so several heard words can collapse into one replacement. Entries can be edited in place, duplicated, or deleted.
Substitutions run top to bottom, and order matters when two rules touch the same words. Drag an entry to move it. A fresh install starts with a handful of brand casings the speech model reliably lowercases: iPhone, iPad, iMac, AirPods, macOS, YouTube, and Wi-Fi. They are only seeded when you have no entries of your own.
Whole word and case
Every entry has two options, set when you add it.
- Whole word is on by default. The Heard text only matches when it stands on its own, so a rule for cat leaves catalog alone. Turn it off and the rule matches inside longer words too, which is what you want for a prefix or a fragment.
- Case is off by default, so iphone, Iphone, and IPHONE all match. Turn it on and the rule fires only on the exact capitalization you typed in the Heard field.
An entry shows a small word tag when Whole word is on and an Aa tag when Case is on, so you can see at a glance how it will match.
More than one dictionary
Entries live in named dictionaries. You start with one called General and can add others, say Work or Medical, and keep them separate. Each dictionary has its own on-off switch, so you can pause a whole set without deleting anything. Each one can also be searched and exported as a JSON file.
A mode can pin its own dictionaries. Every mode has a setting called Use every dictionary that's turned on, and it is on by default. Turn it off and pick exactly which dictionaries that mode should run, whether or not they are on globally.
Your dictionaries are stored in a file called vocabulary.json inside the app's own container on your Mac. It is never synced or uploaded.
How the dictionary shapes what the app hears
A replacement rule can only fix a mistake after it happens. Since 1.2 the dictionary also works earlier than that. Before the speech model decodes your audio (Whisper Large v3 Turbo is the one that ships in the app), the app builds a short glossary from the Replace with side of your entries and hands it to the model as a prompt. That biases the decoder toward your spellings, so it hears Ryleigh instead of guessing Riley and needing the fix at all.
The glossary has a budget of about 200 characters. Your dictionary terms go in first, then distinctive words from your recent dictations, then the multi-word punctuation names your commands depend on. Entries whose Replace with text is a single character or longer than 40 characters are skipped for priming; the substitution still handles them. When a mode pins specific dictionaries, only those dictionaries prime the model.
The substitutions still run as a safety net. They apply to the raw transcript before cleanup, and again after the cleanup model has rewritten the text, so a fix cannot be undone by cleanup.
Suggested fixes learned from your corrections
The app watches for corrections that keep happening and offers them as ready-made entries, in three ways.
- From your history. With Suggest fixes from my dictations turned on (it is on by default), the Dictionaries page scans your recent dictations for words whose casing the pipeline had to change. A fix seen at least three times shows up under Suggested for you with its count. Add it and it becomes a permanent entry in your first dictionary. Dismiss it and it is never suggested again.
- From voice corrections. Within 30 seconds of a dictation landing, and while you are still in the same app, saying replace X with Y fixes the inserted text. Fix the same mishear twice and the Home page asks whether to make that correction stick. Accepting puts it in a dictionary named Learned, which means it is also primed from then on. Only word-level fixes are learned, not whole-sentence rewrites.
- From a selection. Select a correctly spelled word anywhere, hold the Quick Edit key (Right Option by default), and say add this to my dictionary. The word is added with its exact capitalization, and the cleanup model lists up to four likely mishearings and maps those to the same spelling. The same sound-alike expansion is available on any existing entry.
Questions
Does YapToText learn my vocabulary automatically?
Partly. It suggests fixes it sees repeated in your history or in your voice corrections, but nothing is added until you accept it. The suggestions run on your Mac from your own history file.
I added a word to a dictionary and it still comes out wrong. Why?
The Heard field has to match what the recognizer actually produced, not what you expected. Open the dictation in History and read its raw transcript, which is what the speech model heard, then use that spelling as the Heard text. Also check that Whole word is not blocking a match inside a longer word, and that no rule above it rewrites the same words first.
Can I use different vocabulary in different modes?
Yes. Every mode uses all enabled dictionaries by default, but a mode can be set to run only the dictionaries you pick, even ones that are switched off globally.
Can I back up or move my dictionaries?
Each dictionary can be exported as a JSON file from its menu, and the whole set lives in vocabulary.json inside the app's container on your Mac. Nothing is synced by the app itself.
Does my dictionary get sent anywhere?
No. The entries, the glossary built from them, and the learned corrections all stay on your Mac. The app makes no network calls except a model download you start yourself.