---

name: review-ugc-render description: Mandatory pre-publish review gate for a UGC video render. Transcribes the finished render's AUDIO with Whisper and word-diffs it against the approved spoken script, then gates keeping the render as the final version (video_review) — blocking a render whose generated audio mis-voices a word (e.g. the approved "human-vetted" spoken as "human witted"), says a different number or brand name, flips a negation, drops an approved phrase, or comes back silent. Correct speech written differently ("5mg" said "five milligrams", "30%" said "thirty percent", a spoken URL, "don't" said "do not", "larkfieldstraps" said "larkfield straps", a confirmed pronunciation like "TG1" said "T G one") passes. Runnable, gating counterpart to GooseWorks' fuller transcript-integrity review. Every ugc-video-formats recipe runs this after render and BEFORE keeping the final version. status: superseded version: "2.0.5" superseded_by: check-layer@1.2.0

Superseded: the video kit now does this with the check-layer part, version 1.2.0, in the parts folder of this repository. It runs the same speech-against-script rules on every video with speech: numbers, units, negations and brand names must match, and confirmed pronunciations count as the written name. This atom stays, unchanged in behaviour, for skills outside the kit until they move; its scripts still run.

review-ugc-render

The QC gate every UGC video recipe MUST clear before it publishes. Not an eyeball /watch — a deterministic transcript-vs-script diff that exits non-zero on a defect so the recipe can hard-stop keeping the render as the final version (video_review).

In short: it compares what the render actually SAYS with the script the user approved. Correct speech that is only written differently passes (numbers, units, URLs, contractions, fused brand names, confirmed pronunciations). A wrong number, a flipped negation, a mis-voiced word or brand, a dropped phrase or silence fails.

Why this exists

Seedance generates the audio natively. It sometimes mis-voices a word — the approved line human-vetted comes back spoken as human witted; documented siblings: Brume→Brune, Avitu→av-too. The defect lives in the render's audio, so an eyeball /watch ("dialogue matches the script") slips it through, and a downstream caption pass then bakes the wrong word in verbatim. Nothing was comparing the actual spoken audio against the script the user approved.

This gate does exactly that, deterministically, and refuses to publish on a miss.

When to run

• MANDATORY in every remix-ugc-*-from-sample and create-ugc-*-video-from-refs recipe, in the QC phase, after the master render exists and before keeping it as the final version (video_review).
• Re-run after every fix / re-roll until it PASSES.

Contract

Before rendering, persist the exact approved spoken lines (the verbatim utterance, no beat notes) to working/approved-script.txt. Then, after render:

python3 <pack>/review-ugc-render/scripts/review_render.py \
  --video working/final.mp4 \
  --script-file working/approved-script.txt \
  --json working/review-verdict.json

When the voice-over used confirmed pronunciations, add them (recommended): --pronunciations working/brand-rules.json — the same file create-vo-elevenlabs read (its --rules brand-rules.json, or the read_pronunciations.py output; both carry a pronunciations: [{term, say_as}] list). Leave the flag out when there is no such file: a missing file is an ERROR (exit 3).

• exit 0 → PASS — proceed: keep the render as the final version (video_review).
• exit 2 → FAIL — do NOT keep it. Read the report, fix, re-run.
• exit 3 → ERROR — the check could not run (see below); fix the environment or the input, do not publish blind.

Transcription backend (in priority order): the GooseWorks whisper-proxy (CLI credentials or the sandbox token) → OPENAI_API_KEY (honors OPENAI_BASE_URL) → local whisper CLI. ffmpeg must be on PATH. With GW_MEDIA_VIA=mcp the CLI credentials are never used: that login can be a different account from the one the agent is connected to, and the paid transcript would bill it. In that mode the check uses OPENAI_API_KEY or the local whisper CLI, or stops and says so.

What counts as the same speech

Both the script and the transcript are put in one canonical spoken form before the diff. The rules are bounded — each is an exact rewrite, never a fuzzy match.

| Written | Heard | Rule | |---|---|---| | 49, 105, 2,500, 1 million | forty-nine, one hundred and five, two thousand five hundred, a million | number words = digits | | 2.5, 2026, 249, 1st, 2nd | two point five, twenty twenty six, two forty-nine, first, second | decimals, years and prices read in pairs (only when spoken as words: written 2 20-minute is never 220), ordinals (second = 2nd only when the script writes 2nd) | | No. 1, No.1, #1 | number one | number sign, only when written with the dot or # (no 1-star reviews and no one stay negations) | | 5mg, 30g, 500ml, 12oz, 10 lbs, 30-day | five milligrams, thirty grams, …, thirty days | unit after a quantity (weights, volumes, %, money, hours/minutes/seconds, days/weeks/months/years, calories, x times) | | 30% | thirty percent / 30 per cent | percent | | $49, $49.99 | forty nine dollars, forty nine dollars and ninety nine cents | money | | larkfieldstraps.com, www.example.com | larkfieldstraps dot com, w w w dot example dot com, example dot com | URL; www. is optional | | don't, can't, it's, you're | do not, cannot / can not, it is, you are | contractions | | Larkfieldstraps, Gooseworks, everyone, OneGlow | Larkfield Straps, goose works, every one, One Glow | fused/split: exact join of 2–3 words | | TG1 | TG1, TG one, T.G. one | written forms, no alias needed | | TG1 | T G one, T G 1 (letters spaced out) | only with a confirmed alias |

Guards that keep the rules honest:

• A unit word not after a quantity is left alone — a brand "MG" never becomes "milligrams".
• Letters spelled one by one ("T G") are not fused into a word. That needs a confirmed pronunciation.
• Fusion is exact concatenation. "Larkfeld Straps" is not "Larkfieldstraps".
• A join never swallows a negation: "no table" is not "notable" ("no thing" is "nothing").
• A number word joins a word only when every part has 2+ letters: "every one" is "everyone", but "G one" is not "gone".

What still FAILS

| Report line | Root cause | Fix | |---|---|---| | [high] said "59" where script has "49" — number differs… | Wrong, added or dropped number | Re-roll. A number is never a benign paraphrase. | | [high] dropped "5mg" — unit differs… | A unit after a number was changed, added or dropped ("5mg" said "five") | Re-roll. Only a dropped dollars/euros/pounds alone ("$9.99" said "nine ninety-nine") is not HIGH; dropped cents is. | | [high] extra "doesn't" … negation changed | A not/never/no/without was added or lost — the claim flips | Re-roll. | | [high] said "Brune" where script has "Brume" — brand name not heard as approved | Brand mis-voiced or dropped (--brand-term / confirmed pronunciation) | Re-roll; spell it phonetically in the SPOKEN LINE (e.g. Avi-too, never a (pronounced …) parenthetical). See create-video-seedance-2-fal Failure Modes. | | [high] said "witted" where script has "vetted" — audio likely mis-voices… | Seedance mis-voiced a similar-looking word | Re-roll a new seed. | | [medium] dropped "…" / low similarity | Seedance dropped an approved phrase | Re-roll; if only a tail word, a surgical stitch_replacement.py window fix may recover it. | | [low] extra "…" + low similarity | Extra speech beyond benign filler | Re-roll. A single filler word ("so", "okay") in a normal-length line is LOW and passes. | | ⚠ audio is effectively silent | Wrong render / audio track lost in post | Re-render / re-check the mux; never publish a silent take. | | ERROR: no transcription backend | No proxy credentials, no OPENAI_API_KEY, no local whisper | Sign in / set the key / install whisper, then re-run. | | ERROR: alias … would change a number, unit or negation | A bad --alias or pronunciation entry | Fix the alias. Aliases may only respell a name. |

The verdict passes only when similarity ≥ --min-ratio and there is no HIGH issue. Numbers, units, negations and declared brand names fail on their own (HIGH). Any other dropped or extra word is medium/low: it lowers the similarity, and fails the gate only when the similarity drops below --min-ratio (so one dropped ordinary word in a long line can pass). --expect-music is advisory only; it does not by itself fail the gate.

Brand names and confirmed pronunciations

Brand words are never removed from the diff. (Before 2026-10-06, --brand-term fuzzily stripped brand-like words, which let "Brune" pass for "Brume". That is gone.)

• --pronunciations PATH (recommended when the voice-over used one) — the confirmed pronunciations file: create-vo-elevenlabs's brand-rules.json or the output of its scripts/read_pronunciations.py ({"brand_id", "basis", "pronunciations": [{"term", "say_as", "fact_id"}]}). Every entry becomes an alias and its term a brand term. An entry that cannot be used (see alias rules) is skipped with a WARNING, never fatal. A missing or unreadable file is an ERROR (exit 3), so pass the flag only when the file exists.
• --alias "TERM=SPOKEN" (repeatable) — one confirmed spoken form, e.g. --alias "TG1=T G one". The term also becomes a brand term. A bad --alias is an ERROR (exit 3), checked before any transcription is spent.
• --brand-term TERM (repeatable) — marks a brand name. Exactly:
  1. Where the term's words appear in the script, a substitution or drop there is HIGH (a brand mis-voicing). Its fused/split forms count as equal.
  2. A differing span is accepted as the same brand (reported [low], counted as a match) only when all of these hold: it has no negation, number or unit change; every word on both sides is an alphabetic word of some --brand-term; and the two sides look alike (character similarity ≥ 0.6). This keeps the older calling pattern working: a script written in the spoken form (Try ak-mee today) with --brand-term Acme --brand-term ak --brand-term mee passes when Whisper writes Try Acme today ("ak mee" vs "acme" = 0.67). Everything else still fails HIGH: a heard word that is not a declared term (Brume heard Brune), two different declared names (Hale vs Hart, Brume Body Pod vs Brume Band), a truncation (Acme heard ak), or a number inside a term (Pod 4 vs Pod 5, 7-Eleven: 7 days vs 11 days). Prefer --pronunciations over passing say_as words as --brand-term.

Rules for aliases:

• Only pass spoken forms the user confirmed (saved brand pronunciations, or a form they confirmed in chat). Never invent one from the transcript to make the gate pass.
• An alias may respell a name, digits and number-like syllables included ("TG1" = "T G one", "Tenzeal" = "ten-zeal", "Nosha" = "NO-shuh"). It is refused when the written term has a number, unit or negation that the spoken form changes ("TG1" = "T G two"), when the spoken form adds not, never, without, none, nothing or nobody ("Brume" = "never Brume"; no and nor are fine as syllables, "Nomad" = "no-mad"), or when the spoken form is only numbers, units or negations ("Decagon" = "five").
• If you listened and the audio is right but Whisper spelled a coined brand name in a new way, ask the user to confirm that spelling, save it as a pronunciation, a