/review-ugc-render

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`,