---
name: supers-proof-sheet
description: "Proof every burned-in super in a set of finished ad cutdowns against the approved script with Vivu, and get a delivery proof sheet CSV of matches and mismatches. Use before client delivery."
---Supers proof sheet before client delivery
This skill checks the on-screen text of a delivery before it goes to the client. The producer gives Claude the approved super copy from the script (selling lines, prices and dates, the end slate, the legal fine print) and the folder of finished versions (30 s, 15 s, vertical cutdowns). Claude indexes the versions in a private Vivu project, runs one search per super category, reads every super from full frames at the moments Vivu points to, sweeps each version with a 1 s contact sheet for anything the searches missed, compares each line word for word with the approved copy, and writes a proof sheet CSV the editor works from.
The value is that supers exist only in the rendered picture. Project files go through several rounds and drift from the script, transcripts carry no on-screen text, and voiceover rarely reads the fine print. The errors this catches are the ones that cost a redelivery: an old end date left in a template, a price changed in the voiceover but not in the super, a dropped letter in the legal line. Nothing reaches the sheet from Vivu's description of a moment; every line is read from a frame of the user's own file.
When to use
Use when someone asks to proof the supers before delivery, check the cutdowns against the approved script, QC the on-screen text, catch typos or wrong prices in the end cards, or build a supers check sheet for the editor. For one question about one spot ("what does the end card say in the 15"), open the file or run one Vivu search instead. This skill does not judge whether the fine print is legally sufficient, and it does not check logos, faces or music.
Working principles
- Report measured numbers, not estimates. When a number is an estimate, say so.
- Nothing is "verified" until it has been checked against the source video. A Vivu result is a pointer to a moment; the text on the sheet comes from a frame Claude read.
- Stop and tell the user when a required capability or tool is missing. Do not guess around it.
- Ask the user before anything that is expensive to redo or that acts on their behalf (indexing, sending the sheet to anyone).
- Never guess a word. When a frame is too small or blurred to read, the row says UNREADABLE and the user checks the master.
- Compare against the approved copy the user supplied, not against what looks right. The skill reports differences; the client's legal team decides what the fine print must say.
What you need before starting
Check each item at the start of the run and tell the user plainly what is missing before doing anything else.
| Requirement | Why | How to check |
|---|---|---|
| Vivu connector with write access | create a private project, open its upload page, search | vivu_get_account shows can_create_projects: true (tool names may carry a server prefix). "has not granted vivu.write" means the connection is read only; the user reconnects Vivu with write access |
| A shell with local access to the delivery folder | measure durations, extract frames and contact sheets from the user's own files | ls DELIVERY_DIR lists the version files |
| ffmpeg and ffprobe | frames, crops and contact sheets | ffmpeg -version and ffprobe -version |
| The approved super copy | the thing every line is compared with | the user pastes it or points to the script; Claude lists the lines back by category |
| An upload path | moving the versions into Vivu | vivu_open_upload_page plus the user's own browser, or a browser tool that can attach local files |
| Slack connector (optional) | only if the user wants the summary posted for the editor | read the target channel once |
This skill runs in Claude Code on the user's computer (terminal or the Code tab of Claude Desktop), because it reads local files and runs ffmpeg. It needs no residential IP (nothing is downloaded) and no scheduler (it is a one off check per delivery).
Inputs to collect
Ask for anything missing, most important first.
- The delivery folder with every version that ships (required). Default: all .mp4 and .mov files in it.
- The approved super copy (required), grouped by category: selling lines, prices and dates, end slate, fine print. Give each line a short key (B1, P1, D1, S).
- Which lines belong in which versions, if the script says so. Default: any approved line may appear in any version.
- Whether the footage is sensitive. Default: yes, the project is created private.
- Where the sheet goes. Default: the CSV in the working folder; no posting.
Files and state
Keep everything in one working folder next to the delivery:
supers-proof/
approved.json approved lines with key, category and exact text
versions.tsv file name, duration_s, width, height, Vivu video_id
state.json project_id, searches run (field, job_id), versions swept, rows written
results/FIELD.json each completed search result, saved without its result_page_url
frames/ full frames and enlarged crops used for reading
sheets/ 0.5 s window sheets and 1 s version sheets
supers_proof_sheet.csv the deliverable
state.json makes a rerun resume: skip searches whose job_id already has a saved result, skip versions already swept, and never write the same (version_file, on_screen_start, approved_key) row twice. Vivu result page links are never stored here; they expire after four hours.
Step 1: Check the Vivu connector and the setup
Goal: confirm every requirement before anything costs time or credits.
- Call vivu_get_account. If the tool is missing, tell the user to add the Vivu connector in Claude (https://mcp.vivu.ai/mcp) and stop. If can_create_projects is false, or a later write call fails with "has not granted vivu.write", ask the user to reconnect Vivu with write access and stop.
- Run ffmpeg -version and ffprobe -version. List DELIVERY_DIR.
- Ask for the approved copy if it is not in hand.
Done when the account check passed, ffmpeg answered, and the delivery folder is listed.
Step 2: Collect the approved copy and the versions
Goal: a clean list of approved lines and a measured list of versions.
- Write approved.json with one entry per approved line: key, category (benefit, price_date, end_slate, disclaimer) and the exact text, keeping capitals, punctuation and line breaks as " / ". Read it back to the user by category and fix anything they correct. Every later comparison is only as good as this file.
- Measure each version, one file per ffprobe call (ffprobe accepts only one input). In the commands below, DELIVERY_DIR is the delivery folder and FILE is one version's file name:
ffprobe -v error -show_entries stream=width,height:format=duration -of csv=p=0 "DELIVERY_DIR/FILE"
- Write versions.tsv with file name, duration_s, width and height. Flag vertical versions and anything under 720 pixels on the short side; fine print there may not be readable.
In our test run the synthetic versions added up to 1.95 minutes. Passing several files to a single ffprobe call failed, so probe each file on its own.
Done when the user has confirmed approved.json and versions.tsv lists every version.
Step 3: Price it and get approval
Goal: the user sees the cost against their plan before anything is indexed.
- Total index minutes = sum of duration_s / 60. Searches per delivery: four category searches plus one control, all precise.
- Call vivu_get_usage and show one table:
| This delivery | Plan allowance | Remaining | |
|---|---|---|---|
| Index minutes | measured total | from vivu_get_usage | from vivu_get_usage |
| Search credits | estimate: 5 precise searches | from vivu_get_usage | from vivu_get_usage |
- Plan facts: Free is $0 a month with 20 indexing minutes a month and 50 search credits a month; Premium is $30 a month with 180 indexing minutes and 500 search credits. A precise search costs 5 credits; a fast search uses 1 credit.
- If the delivery does not fit, offer to index only the versions that carry unique supers first (for example the hero 30 and the vertical, with the 15s that share their cards checked from the 1 s sheets only), then a larger plan. Do not drop a version the user asked to ship without saying which one.
This step was not exercised in our test run: the factory account has no plan allowance to compare against.
Done when the user approves the table.
Step 4: Upload and index
Goal: every version ready in a private project.
- Call vivu_list_projects and reuse a project for this client and delivery if one exists. Otherwise call vivu_create_project with name "Supers proof CLIENTCODE DATE" and visibility "private". The default visibility is organization, which shows client footage to everyone in the workspace.
- Call vivu_open_upload_page with the project ID right before the upload. The upload link expires after 180 seconds, so hand it to the user immediately to open in their own browser and select the version files, or use a browser tool that can attach local files. Claude in Chrome accepts at most 10 MB per upload call; larger files go through the Vivu web app. Never split or recompress a version to fit, because the frames you read must be the frames that ship.
- Poll vivu_list_videos until every version is ready. Vivu replaces spaces and punctuation in file names with underscores, so match each video_id back to versions.tsv by the normalized name and record it.
In our test run the six synthetic versions were all ready about 2.2 minutes after the upload started (an upper bound: readiness was not checked earlier). That upload used an internal uploader; the user browser path was not exercised in our test run.
Done when versions.tsv has a video_id for every version and every one shows ready.
Step 5: Find each category with Vivu
Goal: a time window for every place a super of each category is on screen.
Each query describes the kind of text and where it sits, never the approved words, so a wrong word still gets found. Run them with vivu_search_videos (project_id, query, mode "precise", maximum_results 40). Precise is the only mode that returns a time window; fast returns whole files and the versions are short enough that file picking saves nothing. maximum_results 40 is the recall ceiling: a delivery of 8 to 12 versions has one to three supers of each category per version.
| Field | Query | Mode |
|---|---|---|
| price_date | a price, offer or date written as text over the picture or on a card, such as a dollar amount per month, an amount off, free months, or a start or end date for the offer | precise |
| benefit | a large headline of selling text laid over the footage in the middle part of the ad, stating a product feature or benefit claim such as coverage, speed, ingredients or no fees; not a price, discount, free months or any other offer, not the closing card with the brand name, tagline or website, not subtitles of what people say, and not small print | precise |
| disclaimer | one or two lines of small legal fine print text near the bottom of the screen, such as terms apply, offer conditions or ingredient notes | precise |
| end_slate | the closing card at the end of the ad showing the brand logo together with a tagline or a website address | precise |
| control | a promo code or discount code shown on screen for viewers to type in at checkout (change it to a category the approved script does not have) | precise |
Each call returns a job ID. Call vivu_get_search_results until complete is true; each status call can wait up to 45 seconds, so a pending search is not a stalled one. Save the completed result to results/FIELD.json with the result_page_url field removed, and the job_id to state.json. Show the Vivu result page link in the reply if useful and say it expires after four hours.
There is no spoken query in the chain on purpose: the voiceover often says something different from the super, and that difference is what the sheet must catch, so speech is never evidence for what is on screen.
The chain: a search gives the window, the frame pass in Step 6 reads the words, and the sheet pass in Step 7 catches what the search left out. A control that returns results means the queries are matching anything with text; tell the user and tighten the wording.
Worked example from our test run: on 18 videos (7.38 minutes: synthetic cutdowns with planted copy errors, plus public carrier ads), the price_date search found 5 real windows and no false ones on the synthetic set and 11 real windows on the public set (this count includes open captions of the voiceover that say a price, which the sheet leaves out), with 1 missed card (a vertical price guarantee card after the returned window). The benefit wording above came after 2 rewordings on the same corpus. The first wording returned 2 false of 8 on the synthetic set (the end slate tagline) and 7 false of 10 on the public set (offer cards, slates, voiceover captions); the second shortened the windows and missed 2 benefit lines. The final wording returned 6 real on the synthetic set with none missed, and 3 real on the public set with 1 missed (a data upgrade card made of numbers and arrows). The fine print search returned 6 real on the synthetic set and 9 real on the public set with 0 missed, and the end slate search 8 real on the public set. The control returned nothing on either set.
Done when every query in the table has a saved result and the control came back empty or was explained to the user.
Step 6: Read every super from full frames
Goal: the exact on-screen text of every super, read by Claude from the user's file.
Vivu's window holds the super, but it is wider than the super and often holds two of them, and its reason text names only one. Never copy wording from the reason.
- For each window, make a 0.5 s sheet (START and END in seconds from start_ms and end_ms). Use tile=8xROWS with ROWS = ceil(window length in seconds / 4), so the sheet holds every half second of the window; a fixed tile size would keep only the first part of a long window and drop the rest without an error.
ffmpeg -v error -ss START -to END -i "DELIVERY_DIR/FILE" -vf "fps=2,scale=240:-2,tile=8xROWS" -frames:v 1 sheets/FILE_START.png
- Pick the tile where each super is complete and fully faded in, then extract that full frame at its time T:
ffmpeg -v error -ss T -i "DELIVERY_DIR/FILE" -frames:v 1 -q:v 3 frames/FILE_T.png
- For fine print, crop the line and enlarge it before reading (X, Y, W, H in pixels of the source frame; 1.5x to 3x is usually enough):
ffmpeg -v error -ss T -i "DELIVERY_DIR/FILE" -vf "crop=W:H:X:Y,scale=iw*3:-2" -frames:v 1 frames/FILE_T_fineprint.png
- Write down each super exactly as it appears, with on_screen_start and on_screen_end as MM:SS from the first and last tile that show it. When a word cannot be read with certainty, keep what is legible and mark the row UNREADABLE.
- A window that holds no super of the category it was searched for (for example an end card tagline returned by the benefit search) is a false result. Count it per search and keep it off the sheet; Step 8 reports these counts. Any other super you read in that window still goes on the list, under the category its frame shows.
In our test run every super in the synthetic versions was legible from full frames, including the fine print of the vertical version after an enlarged crop. On the public set, a block of fine print in a low resolution vertical ad and the smallest line of another vertical ad were only partly legible; those rows belong under UNREADABLE until checked against the master. The three frames at the start, middle and end of a window are not enough: they missed the selling line in most first wording windows.
Done when every window has its supers written down with times and a frame path.
Step 7: Sweep every version with a 1 s contact sheet
Goal: catch supers the searches did not return, and approved lines that never appear.
ffmpeg -v error -i "DELIVERY_DIR/FILE" -vf "fps=1,scale=320:-2,tile=6xROWS" -frames:v 1 sheets/FILE_1fps.png
Set ROWS = ceil(duration_s / 6) from versions.tsv, so a 42 s version is not cut off at 36 s. Look at each sheet from the first tile to the last. Every tile with text that is not already in the Step 6 list gets read from a full frame as in Step 6. On a contact sheet fine print shows as a thin line that cannot be read; treat that line as a super to read, not as noise. Update state.json with the swept version.
In our test run the sheet showed the vertical price guarantee card that the price search missed.
Done when every version in versions.tsv is marked swept in state.json.
Step 8: Compare with the approved copy and write the sheet
Goal: one row per super on screen, each marked MATCH, MISMATCH or UNREADABLE.
- Assign each super its category from what the frame shows, not from the search that returned it, then match it to the approved line of that category with the closest text, then compare character by character: words, numbers, dates, currency signs, capitals and punctuation. A single dropped or swapped letter is a MISMATCH.
- Open captions of the voiceover are not supers. Keep them out of the sheet unless the approved script lists them.
- Approved lines that never appear in a version where the script expects them go in a closing list, "Approved but not found", with the version name.
- Show the user the field mapping and the first rows, including one MISMATCH if there is one, before writing the full sheet:
version_file,on_screen_start,on_screen_end,category,read_from_frame,approved_key,approved_copy,status,frame,editor_fixed
FWK_HERO_15_V_v3.mp4,00:06,00:09,price_date,"$3.49 a bottle / Through June 30, 2027",P1,"$3.99 a bottle / Through June 30, 2027",MISMATCH,frames/FWK_HERO_15_V_v3_7.0.png,
| Field | Source | If unavailable |
|---|---|---|
| version_file | versions.tsv | none |
| on_screen_start, on_screen_end | first and last tile showing the super (Step 6 or 7) | the Vivu window, labeled NOT VERIFIED |
| read_from_frame | Claude's reading of the full frame or crop | UNREADABLE |
| approved_key, approved_copy | approved.json | NO MATCH (a super the script does not have) |
| status | the comparison | UNREADABLE |
| editor_fixed | left blank for the editor | blank |
- Write supers_proof_sheet.csv. Report the counts plainly: rows, MISMATCH, UNREADABLE, approved lines not found, and false windows per search. If nothing differs, say so; do not pad the sheet.
In our test run every planted error (a wrong hour count, a wrong price, an old end date and a dropped letter in the fine print) came out as a MISMATCH. Vivu's reason text named the wrong price, hour count and date but never mentioned the fine print line with the typo.
Done when the user has approved the sample rows and supers_proof_sheet.csv exists with one row per super.
Step 9: Hand it to the editor
Goal: the editor has the sheet and knows what to fix.
- By default, tell the user where the CSV is and stop.
- If the user wants it posted, name the Slack channel, show this message fully rendered, and wait for an explicit yes before posting. Posting acts as the user.
Supers proof, CAMPAIGN, N versions checked against the approved script (DATE)
M lines differ from the approved copy:
• VERSION_FILE MM:SS CATEGORY: "ON SCREEN" (approved: "APPROVED")
Unreadable: LIST or none. Full sheet: supers_proof_sheet.csv (fill editor_fixed as each line is fixed).
Whether the fine print is legally sufficient is for the client's legal team; this sheet only compares on-screen text with the approved script.
- Use file names and timestamps in the message, never the Vivu result page link.
In our test run the message was rendered to a file and not sent; posting was not exercised in our test run.
Done when the user has the CSV path, or the approved message has been posted.
Compliance
- Use only the client's own finished versions that the agency is delivering. Confirm this before Step 4.
- The footage stays in the user's Vivu project until they delete it. Create the project private (the default is visible to the whole organization) and confirm before Step 4.
- Actors and people on camera are not identified. The skill does not recognize faces or logos.
- The sheet reports differences from the approved copy. Whether a disclaimer is adequate or compliant is the client's legal team's call; say so in the hand off.
- Posting the sheet anywhere acts as the user and needs approval in Step 9.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| the benefit search returns the end card tagline (observed: "end slate tagline, not a benefit super", 2 false of 8 with the first wording) | a tagline reads like a selling line | use the final wording, which excludes the closing card; judge every hit from frames |
| none of the three window frames shows the super (observed: "three-frame strip shows no super") | the window is several times longer than a super that is on screen for a few seconds | read the Step 6 sheet of the whole window, not three frames |
| the fine print window holds two lines but the reason mentions one (observed: "reason names only the first") | one window covers several cards in a row | read every line in the window from enlarged crops; never copy the reason |
| a price card near the end of a vertical version is missing (observed: "window stops before the 5-year price guarantee card") | the search returned one window per run of cards and stopped early | the Step 7 sheet sweep catches it; read it from a full frame |
| voiceover captions come back as a price or a selling line (observed: "not a designed super") | open captions are text on screen too | keep captions off the sheet unless the script lists them |
| ffprobe fails with "was already specified" (observed) | several files were passed to a single ffprobe call | probe each file on its own |
| a sheet or crop stack fails with "Padded dimensions cannot be smaller than input dimensions." (observed) | frames of different sizes (vertical and horizontal) in one stack | build sheets per version, or scale every frame to the same height first |
| fine print in a low resolution vertical version cannot be read | small text at low resolution | mark UNREADABLE and check against the master or a higher resolution export |
| "has not granted vivu.write" | Vivu connected read only | the user reconnects Vivu with write access |
| upload page asks to sign in or shows an error | the one time upload link expires after 180 seconds | request a new link right before opening it |
| a file is rejected by the browser upload tool | Claude in Chrome accepts at most 10 MB per upload call | the user adds that file in the Vivu web app |
| a result's file name does not match versions.tsv | Vivu replaced spaces and punctuation with underscores | match on the normalized name |