Glossaries

A glossary is a named JSON file stored once on your machine — under $OPENBBQ_HOME/glossaries/, by default ~/.openbbq/glossaries/ — and shared across workspaces. It does three jobs:

1. Bias the recognizer (the model that writes down what it hears) toward the canonical spelling of source terms.
2. Correct known mishearings to the canonical spelling while the transcript is cut into subtitle lines.
3. Guide translation with canonical translations and keep-as-is rules.

Create a glossary

openbbq glossary new project-name --context "Technical interviews about AI developer tools"

This writes ~/.openbbq/glossaries/project-name.json with an empty term list. The context line describes the material so translators and agents can make better calls:

{
  "schema": "openbbq/glossary@1",
  "name": "project-name",
  "context": "Technical interviews about AI developer tools",
  "terms": []
}

Add terms

Edit the file and add one entry per name or term you care about:

{
  "source": "OpenBBQ",
  "target": null,
  "aliases": ["Open BBQ", "Open BQ"],
  "note": "Project and CLI name",
  "keep": true
}

Set target for a term with a canonical translation; set keep: true for a brand or proper noun that stays as-is. Leaving both unset means the translation decision is still open.

Inspect the library

openbbq glossary list
openbbq glossary show project-name

Bind a glossary to a workspace

At init:

openbbq init /path/to/video.mp4 --workspace workspaces/demo --glossary project-name

Or later:

openbbq glossary use project-name --workspace workspaces/demo

The binding is written to manifest.glossary. transcribe, segment, and translate init all follow it; each command's own --glossary option overrides it for that run.

Mine candidate terms

After transcribing, OpenBBQ can surface words worth a second look — repeated names and words the recognizer wasn't sure about:

openbbq glossary suggest --workspace workspaces/demo

Useful filters:

openbbq glossary suggest \
  --workspace workspaces/demo \
  --glossary project-name \
  --max-prob 0.6 \
  --min-count 1 \
  --max 30

• --glossary — leave out terms the glossary already knows.
• --max-prob — only words below this recognition confidence.
• --min-count — only words heard at least this many times.
• --max — stop the list here.

Suggestions are deterministic candidates, not automatic edits. Review them, then add the ones that deserve a term.

Audit the transcript

The audit pages through every resolved transcript segment with its evidence, so you can confirm names from context instead of guessing:

openbbq glossary audit --workspace workspaces/demo --offset 0 --limit 20

Each page shows the neighboring text, word probabilities, the resolved and raw source text, reference captions when available, and glossary matches. Follow next_offset until remaining reaches zero; pages are at most 20 segments.

Apply term updates

Add or update terms atomically — up to 20 terms per apply — with a terms file:

{"terms":[{"source":"Andy Matuschak","aliases":["Annie Matushak"],"note":"researcher; confirmed ASR variant"}]}

openbbq glossary apply --workspace workspaces/demo glossary-terms.json

Then rerun openbbq segment so the corrections reach the subtitle lines. Its output reports glossary_matched_terms, glossary_aliases_applied, and glossary_no_effect. A bound glossary that matched nothing is not proof that terminology was maintained — treat it as a prompt to look again.

Where next?

• Transcription and listening checks — where the recognizer's doubts get resolved
• Translation and review — where targets and keep rules take effect