Glossary

Teach DemoVoice the right pronunciation for technical terms, acronyms, and brand names — and the common ways Whisper hears them wrong.

Why Use a Glossary?

Two things go wrong without a glossary:

Whisper transcribes a product name as something else (e.g. AmazeCRM → Amaze CRM), and that wrong text flows through to TTS.
TTS pronounces a technical term the wrong way (e.g. YAML as "why-am-l" instead of "yamel").

The glossary fixes both: aliases teach Whisper to normalize misheard variants into the canonicaltext, and pronunciation tells TTS how to say it.

Glossary File

demovoice init creates .demovoice/glossary.yaml. DemoVoice loads it automatically when present. The format is a list of terms:

.demovoice/glossary.yaml

terms:
  - text: AmazeCRM
    pronunciation: "amaze C R M"
    aliases:
      - "Amaze CRM"
      - "Amazed CRM"

  - text: GitHub App
    pronunciation: "git hub app"
    aliases:
      - "github app"

  - text: BYOK
    pronunciation: "B Y O K"

  - text: Vercel
    pronunciation: "ver SELL"

  - text: kubectl
    pronunciation: "kube control"
    aliases:
      - "kube cuddle"

Term Fields

Field	Description
text	The canonical spelling. This is the text TTS receives and what aliases are normalized to.
pronunciation	Phonetic hint sent to the TTS model. Write it as you want it spoken.
aliases	Common transcription misses or alternate spellings to normalize back to `text`.

Built-in Presets

DemoVoice ships with a tech-demo preset enabled by default. It covers common software-demo vocabulary — GitHub, repo, Linear, OpenAI, API, CLI, PR, OAuth, SDK, JSON, YAML, TypeScript, Kubernetes, Docker, Postgres, webhooks, frontend, backend, and CI/CD — plus prompt guidance for transcription and synthesis.

Built-in presets load first; project glossaries load after and can override or extend preset terms.

Additional Glossary Files

List additional glossary files in your config or pass them with repeatable --glossary flags:

demovoice render demo.mp4 \
  --glossary glossaries/product.yaml \
  --glossary glossaries/people.yaml \
  --output demo.demovoice.mp4

Or, in demovoice.yaml:

.demovoice/demovoice.yaml

glossaries:
  - glossary.yaml
  - glossaries/product.yaml
  - glossaries/people.yaml

Tips

Acronyms

For letter-by-letter pronunciation, use spaces between letters: "A P I", "B Y O K".

Stress

Use caps on the stressed syllable: "ver SELL".

Iterate quickly

Use demovoice inspect to see how Whisper heard your audio. Add the wrong-sounding variants to aliases, then re-run.

Plain-text format

.txt glossary files are also accepted — one term per line — but YAML lets you specify pronunciation and aliases per term.

Pro tip: Commit .demovoice/glossary.yaml to version control. Every demo your team renders will share the same vocabulary, and corrections compound over time.