Dictionaries: teach YapToText your names and jargon
By Ryleigh Newman · Published · Updated
A dictation dictionary is how you teach YapToText on your Mac the names and jargon Whisper keeps mishearing: each entry says when you hear this, write that, and it applies to every dictation from then on. Dictionaries live on the Dictionaries page, and nothing in them leaves your Mac.
This page is the reference for that page: what each field and switch does. For a walkthrough with a name, a product and an acronym as examples, and for what Apple's own Dictation lets you change, see the guide to adding words to Mac dictation.
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.
On this page: 10 sections
Heard, Replace with, and Add
An entry has two fields and one button. Heard holds the spelling the speech model produced, which is not always the word you said.
- Heard. The text to look for, spelled the way it arrived. For my name that is riley.
- Replace with. The text to write in its place: Ryleigh.
- Add. Saves the entry into the dictionary you are in, such as General. It takes effect on your next dictation.
- Where the Heard spelling comes from. Open a dictation in History and click Show pipeline details. The raw transcript is the speech model's own output, before any entry ran.
The guide to adding words to Mac dictation walks through adding one, step by step.
Whole word, Case, and order
Each row has two options, and the list has an order. A new entry starts with Whole word on and Case off, and most never need changing.
- Whole word, on by default. Heard matches only as a complete word. An entry for cat does not touch catalog. Switch it off when you mean a prefix or a fragment.
- Case, off by default. Capitalization is ignored, so iphone, Iphone and IPHONE are one match. Switch it on to require the capitals exactly as typed in Heard.
- Order. The list runs from the top. If two entries could change the same words, the upper one wins. The handle at the left of a row drags it.
- Folders. Spellings that end in the same word collapse into a single row, shown as Ryleigh, 3 spellings. Open the row to edit the spellings inside.
- Tags. A word tag on a row means Whole word is on. An Aa tag means Case is on.
A fresh install starts with a few entries the speech model reliably gets wrong: iPhone, iPad, iMac, AirPods, macOS, YouTube, Wi-Fi and the app's own name, and they are added only when you have no entries of your own.
How your words shape what Whisper hears
A replacement can only fix a mistake after it happens. So, since 1.2, YapToText also works earlier: before Whisper decodes your audio, it builds a short list from the Replace with side of your entries and hands it to Whisper as a prompt, which leans the decoder toward your spellings.
- The budget. About 200 characters. Your dictionary terms go first, then distinctive words from your recent dictations, then the two-word punctuation names your commands rely on.
- What is skipped. A Replace with text of one character, or longer than 40 characters, is not used as a prompt. The replacement still handles it.
- Per mode. When a mode uses only some dictionaries, only those prime Whisper.
The replacements still run as a safety net, on the raw transcript and again after any AI cleanup, so cleanup cannot undo a fix. Your dictionary works twice: once on what Whisper hears, and again on what gets typed.
Keep several dictionaries
- New Dictionary. Start with General and add others, such as Work or Medical. Click a name to rename it.
- The switch. Each dictionary has its own switch, so you can pause a whole set without deleting anything.
- The menu. Export Dictionary saves it as a JSON file, Show in Finder reveals the file, and Delete Dictionary removes it.
- Search. The magnifying glass on a dictionary searches its entries.
- Per mode. In the editor of any dictation mode, the Dictionaries card has Use every dictionary that's turned on, on by default. Turn it off to pick exactly which dictionaries that mode runs, even ones switched off everywhere else.
All of them live in one file, vocabulary.json, inside the app's own container on your Mac, and nothing syncs it. Export Preset, in Settings, Advanced, Backup & sharing, carries your dictionaries to another Mac along with your modes and settings. A dictionary you switch off stays put until you need it again.
Add an entry without the two fields
Three routes add an entry without the two fields. Each one ends in the same place: a row on the Dictionaries page that you can edit or delete.
- By voice, over a selection. Select the correct spelling in any app, tap the Quick Edit key, Right Option by default, and say add this to my dictionary. The word goes into your first dictionary as written. For one word of three letters or more the app also adds the split form a recognizer tends to produce, like you tube for YouTube, and up to four likely mishearings from the cleanup model. If the word is already there, the card says so.
- By correcting twice. After a dictation lands, say replace, the wrong word, with, the right word. The second time you fix the same mishearing, the Home page asks “Make this correction stick?”. Add it files the fix in a dictionary named Learned, which primes Whisper as well. Fixes longer than three words are not learned.
- By Generate variations. On a row or a folder, it asks the model on your Mac for likely mishearings of that word and maps them to it, leaving out plurals, truncations and real words.
Let the app suggest fixes
With Suggest fixes from my dictations on, the default, YapToText looks through your recent history, up to 400 dictations, for words the app keeps having to recapitalize. A fix seen at least three times shows up under Suggested for you with its count, up to eight at a time.
- Add. The plus button puts it in your first dictionary, and it applies from then on.
- Dismiss. The x button means it is never suggested again.
Nothing is added until you say so. The scan runs on your Mac, from your own history file.
Limits
- Spelling is literal. An entry fires only when Heard equals what the speech model wrote. A word that arrives spelled several ways needs each spelling, or Generate variations.
- The prompt is short. About 200 characters of your words reach Whisper as a hint, so a long dictionary does not all fit. Your own terms go in first.
- Words only. Entries change words and phrases. Punctuation by voice belongs to spoken commands.
- Fragments are greedy. With Whole word off, an entry can match inside other words. Keep that setting for real fragments.
When an entry does not fire
When an entry does nothing, the cause is nearly always one of three things. Compare Heard with the raw transcript first. A one-letter difference is enough to stop it.
- The spelling. Heard differs from the raw transcript in History.
- A switch. The dictionary is off, or the mode you dictated in does not use it.
- Another entry. A row higher in the list changed the same words first, or Whole word or Case ruled the match out.
The guide to adding words to Mac dictation has the full ladder, smallest step first. If it still fails, open a GitHub issue with the word, the raw transcript and the entry.
The short version
- Heard, then Replace with. Use the spelling Whisper produced, then yours.
- It works twice. Your words prime Whisper, and the entry fixes what slips through.
- No typing needed. Select the word and say add this to my dictionary.
Fix a misheard word once, and it stays fixed. If a word will not stick, tell me on GitHub. Every issue 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
Questions
Does YapToText learn my vocabulary automatically?
Partly. It suggests fixes it sees repeated in your history and in your voice corrections, but nothing is added until you accept it.
I added a word and it still comes out wrong. Why?
Heard has to match what the speech model actually wrote. Open the dictation in History, read the raw transcript, and use that spelling.
Can I use different dictionaries in different modes?
Yes. In a mode's editor, turn off Use every dictionary that's turned on and pick the ones that mode should run.
Does my dictionary get sent anywhere?
No. Entries, suggestions and learned corrections stay on your Mac, in the app's own container.