review-finished-ad

The gate between a rendered master and the user. A finished ad has to look like the brand's ad and play like an ad, not like a pile of clips. This skill checks both, fixes are made by the caller, and the gate is re-run until it passes.

Run it

Needs ffmpeg + ffprobe on PATH and pip install --quiet numpy pillow.

python3 scripts/review_finished_ad.py \
  --video working/final.mp4 \
  --json working/review/finished-ad.json \
  --sheet working/review/finished-ad-sheet.png \
  --logo working/brand/logo.png \
  --palette "#0b3d2e,#f4efe6" \
  --product-images working/brand/product-1.png,working/brand/product-2.png \
  --font working/brand/font.ttf --brand-name "Acme"

• --logo is the logo file the video actually composites: the kit's logoUrl / logos[0], or the wordmark file the recipe's end card uses. PNG, JPEG or SVG (an SVG is rasterised with cairosvg or rsvg-convert). Never a generated logo.
• No logo image in the video (the brand name set as text in the brand font, because the kit only has a favicon or no logo): omit --logo, and judge the text wordmark on the sheet.
• --endcard-s is the end card's length (default 3.0). Set it to the real length: a longer silent or static end card would otherwise read as dead air or a freeze.
• --logo-at 3.2 (repeatable) adds a timestamp where the logo also appears mid-video; the end card (last ~1.6s) is always checked.
• --no-speech for formats with no voiceover or dialogue (music-only), so silence is not judged.
• --expect-size defaults to 1080x1920. Video ads are always 9:16.

Exit 0 → PASS. Still read the sheet (below) before publishing. Exit 2 → FAIL. failed lists the checks; each note says what to fix. Exit 3 → ERROR. The check could not run (missing file, no ffmpeg); fix and re-run. Never publish blind.

Machine checks

logo is grayscale correlation with a fine size search, so the right logo scores 0.9+ at any size:

• Transparent mark (PNG/SVG wordmark or symbol): matched in either polarity, so a white version on a dark card counts. Pass ≥ 0.85, fail < 0.75. Another brand's wordmark scores about 0.6-0.7; a same-font near-copy about 0.8 (warn).
• Opaque logo (a JPEG, a mascot photo, a square app icon): matched as the whole image. Pass ≥ 0.85, fail < 0.70. A different mascot on a similar background scores about 0.5.

Between the two lines it is a warn: look at the sheet for a warped, cropped or redrawn logo.

Eye checks — read the sheet every time

finished-ad-sheet.png shows one frame per shot plus the end card, with the platform UI areas shaded red, and the brand references underneath. Open it and confirm each line in the verdict's judge_on_sheet:

• Safe zones: no caption, CTA, price, logo or product name inside a red band (top 220px, bottom 400px, right 140px at 1080x1920).
• Font: on-screen text uses the brand font shown in the specimen.
• Product likeness: every product shot matches the reference product images (shape, label, colour). A stand-in, a catalogue image of another product, or a mascot is a fail.
• Product consistency: the product looks the same in every scene.
• Logo unaltered: not stretched, recoloured, cropped or redrawn.

Any of these failing is a FAIL, the same as a machine check.

Fix loop

Fix only the failing window (re-composite the end card, regenerate one shot, re-time one line), re-render, and re-run this script. Up to 2 repair rounds. If it still fails, do not present the video as finished: the caller reports it as blocked with the failed checks, so the user sees a clear warning.

Output

--json writes { verdict, failed[], video{width,height,duration,has_audio,cuts}, checks{<name>: {status, note, data}}, sheet, judge_on_sheet[] }. Status is one of pass, fail, warn, not_applicable.