Teach ParrotFlow a word

What you will get

Each word you teach is a term in ~/.config/parrotflow/vocabulary.yaml, beside config.yaml. The app writes this file and reloads it on save.

Correct it once and accept the offer

1. Dictate. The name comes out wrong.
2. Fix the word in the text, by hand.
3. The pill asks “Learn this spelling?”. Press Y to keep it, or N to skip.

Next time you say the name, ParrotFlow writes the spelling you taught it.

Use the correction panel

Use the panel when you want to see the rule before it is saved.

1. Open it in one of two ways. Right after a dictation, press V on the pill, or click Vocabulary. Or select the wrong word in any app, hold the hotkey and say “hey parrot”.
2. The panel has one row per word that looks wrong, with what it heard and what it should be. Fill in the right side.
3. Press Return to save. Each row becomes one rule in vocabulary.yaml, and the corrected sentence goes back where it came from.

Both sides of a row can be edited. If the recogniser splits a name in two, such as “red crawl” for Redcrawl, type the two words on the left. The rule then only matches that pair.

The V key on the pill needs the Input Monitoring permission. Without it, click the chip instead. See Permissions.

Teach it from the terminal

The commands below use the full path to the app. If you installed with Homebrew, parrotflow runs the same binary.

/Applications/ParrotFlow.app/Contents/MacOS/ParrotFlow --learn "super base" Supabase

✓ super base → Supabase

It writes the same entry the panel would have written:

terms:
  Supabase:
    pronunciations:
      - heard: super base
        from: correction

Edit vocabulary.yaml by hand

The file header says not to edit it unless you know what you are doing. The app owns this file. Prefer the panel or --learn. If you do edit it, add a term in the same shape the app writes.

A new file has terms: {}. Replace the {} with your terms:

terms:
  Supabase:
    pronunciations:
      - heard: super base
  Tasmeen:
    kind: person
    pronunciations:
      - heard: Tasmin

heard is how the recogniser writes the word. It is the only required field. kind is optional and takes person, place, organization or word.

Check that it worked

1. Find the term in the file:

   grep -A5 Supabase ~/.config/parrotflow/vocabulary.yaml

2. Ask the app what it loaded:

   /Applications/ParrotFlow.app/Contents/MacOS/ParrotFlow --check-config

   Look for the term count:

     · vocabulary: 2 terms in vocabulary.yaml, 2 matched by sound, 2 by rule

   If the file has a YAML error, this line is missing and the terminal prints vocabulary.yaml could not be read, with the line and column.

3. Optional. Run a sentence through the vocabulary step. --pipeline takes a test file that carries its own terms. It does not read your vocabulary.yaml, so copy the terms in. Save this as vocab-test.yaml:

   languages: [en]
   vocabulary:
     terms:
       Supabase:
         pronunciations:
           - heard: super base
   pipeline:
     - vocabulary

   /Applications/ParrotFlow.app/Contents/MacOS/ParrotFlow --pipeline vocab-test.yaml "we store it in super base" --app "" --quiet

   we store it in Supabase

4. Dictate a sentence with the word in it.

When a word should stay ordinary

“Vue” is a name. “view” is a word. A rule that writes Vue for “view” could also change “re-render the whole view”.

ParrotFlow does not apply every match blindly. It checks each one against the sentence before it writes the term:

• If no dictionary knows the heard word, the term is written.
• If the sentence wants a verb or a preposition in that place, a name does not fit, and the heard word stays.
• If the sentence looks like the ones where you kept the term, the term is written. If it looks like the ones where you took it out, the word stays.
• If none of these decide, the pill asks you. Press Escape or keep working, and you get what the checks settled on.

So when ParrotFlow writes “Vue” where you meant “view”, put “view” back by hand. No rule is offered for that. The sentence is kept as a counter-example, a place where the term does not belong.

You can record a counter-example from the terminal too:

/Applications/ParrotFlow.app/Contents/MacOS/ParrotFlow --against Vue "re-render the whole view" view

✓ Vue does not belong at "view"

It is written to vocabulary-uses.yaml, beside vocabulary.yaml.

Limits

• A new term has no sentences yet. Until it has one counter-example or three confirmed uses, its sentences cannot take a rule’s substitution back out. At first, expect the pill to ask, or “the whole view” to come out as “the whole Vue”. Each answer and each correction is recorded, so the next guess is better informed.
• The panel only proposes words the macOS dictionary does not know. “cloud” for Claude is a real word, so you type that row yourself.
• A fix to grammar is never offered as a rule. “user” to “users” is the same word in another form.
• To forget what ParrotFlow learnt about how a name sounds, run --forget <term>. The term itself stays.

Related

• Custom vocabulary, for how matching by sound and the sentence checks work.
• Teaching it a word, for spoken spellings and the panel in detail.
• The vocabulary file, for every field.
• The command line, for --learn, --against and --forget.