majiayu000 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-stopset_final_render.
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: Hume→Hune, Alitu→al-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-sampleandcreate-ugc-*-video-from-refsrecipe, in the QC phase, after the master render exists and beforeset_final_render. - 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
- exit 0 → PASS — proceed to publish (
set_final_render). - exit 2 → FAIL — do NOT publish. Read the report, fix, re-run.
- exit 3 → ERROR — the check could not run (see below); fix the environment, do not publish blind.
Transcription backend (in priority order): OPENAI_API_KEY (honors
OPENAI_BASE_URL, so it routes through the gooseworks Whisper proxy when set) →
local whisper CLI. ffmpeg must be on PATH.
What FAIL means and how to fix
| Report line | Root cause | Fix |
|---|---|---|
[high] said [witted] where script has [vetted] |
Seedance mis-voiced the word in the generated audio | Re-roll a new seed. If it is a brand/coined token, spell it phonetically in the SPOKEN LINE (e.g. Ali-too, never a (pronounced …) parenthetical — Seedance reads parentheticals aloud). See create-video-seedance-2-fal Failure Modes. |
[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. |
⚠ 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 OPENAI_API_KEY and no local whisper |
Set the key (proxy OPENAI_BASE_URL) or install whisper, then re-run. |
--expect-music is advisory only (warns if a music bed is absent); it does not by
itself fail the gate.
Inputs
--video PATH(required) — the rendered master mp4.--script-file PATHor--script "text"— the approved spoken script. Omit both only for a genuinely script-free clip (the drift check is then skipped and the gate is advisory).--min-ratio FLOAT(default0.90) — transcript↔script token similarity to pass.--json PATH— write the machine verdict for the app's review panel.
Tests
python3 tests/test_review_render.py # pure verdict logic; no audio/network
Covers the canonical vetted→witted mis-voicing, brand-name mis-voicing, dropped
tails, benign filler, and the no-script advisory path.
Relationship to the content-goose review engine
This is the shipped, single-file, gating slice of the fuller
coworkers/video/molecules/review/review-loop (18-axis rubric). Here we enforce
the one axis that catches audio-vs-script defects at publish time
(review-transcript-integrity / brand_text_accuracy). Deeper multi-axis review
stays in the content-goose lab.