Re-cut source sheet from past spots

---
name: client-spot-recut-source-sheet
description: "Build a re-cut source sheet from a client's delivered spots with Vivu: product shots, spoken claim lines and supers, checked on frames or captions, merged across versions. Use before a re-cut."
---

Re-cut source sheet from a client's past spots

This skill turns a folder of spots you already delivered to one client, plus the brief for a new cut, into a source sheet the editor can work from. Claude measures the spots, prices the job against the user's Vivu plan, has the user upload them to a private Vivu project, runs one search per brief slot (a product shot, a spoken claim line, supers), looks at end cards locally when the brief wants them, checks every candidate against frames or the local transcript, merges the same shot across the 30 second, 15 second and vertical versions, and writes a CSV with file, version, in and out points, frame, spoken line, on screen text, other versions and a rights flag per row.

The value is in what the delivery list and file names never say: which second the product is on screen and which model it is, which line of the voiceover states the claim, what the super and end card actually read, and that the same shot sits in three versions under three different names. Only the footage shows that. Vivu narrows 25 spots to a few candidate windows per slot; Claude then looks at every window before it becomes a row, because Vivu's text about a window can name the wrong color, a line nobody said, or a super that is only a logo.

When to use

Use when an editor, assistant editor or producer says things like "pull every product shot from the client's old spots", "find where the VO says the claim in last year's ads", "list the supers and end cards across all versions", "build a source sheet for the re-cut", or "which versions reuse this shot". For a one off question about a single spot, search Vivu directly or scrub the file. For raw camera rushes rather than finished spots, use a selects workflow built for rushes; this skill assumes short finished ads with supers and a mix. It does not judge which shot works best, cut anything, or make variants.

Working principles

1. Report measured numbers, not estimates. When a number is an estimate, say so.
2. Nothing is verified until it has been checked against the source video. Vivu results are candidates until Claude has looked at the frames or read the local transcript for that window.
3. Stop and tell the user when a required capability or tool is missing. Do not guess around it.
4. Ask the user before anything that is expensive to redo or that acts on their behalf: indexing (it uses plan minutes), the field mapping and sample row before the full sheet, and any upload of client footage.
5. Keep every rejected candidate in a separate file with the reason, so the editor can see what was ruled out.
6. Never decide rights. Flag music, talent and stock on every row for the editor to confirm with the client.

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.

No scheduler is needed; this is a one shot job per brief.

Inputs to collect

Ask for anything missing, most important first.

1. The folder of delivered spots for this client (required).
2. The new brief, as slots: each product shot needed (described by how the product looks and what it is doing, not by logo), each claim line, and whether supers and end cards are wanted. Default: one product slot, one claim slot, supers and end cards.
3. How versions are named (for example CLIENT_CAMPAIGN_LENGTH_vN). Default: read length and orientation from ffprobe and keep the file name as the version label.
4. Where to write the sheet. Default: a working folder next to SPOTS_DIR.

Files and state

Keep everything in one working folder:

recut-sheet/
  config.json            spots folder, brief slots, queries, Vivu project id
  inventory.csv          one row per spot: file, duration_s, width, height, version label, vivu video_id
  proxies/               720p copies, only if the delivery files are large masters
  results/               raw search results, one JSON per slot
  frames/                strips and full frames per candidate
  state.json             steps done, uploaded files, candidates checked (video_id + start_ms), rows written
  source_sheet.csv       the deliverable
  rejected_candidates.csv  every candidate that failed the check, with the reason

state.json lets a rerun resume: skip files already in the project, searches already saved in results/, and candidates already judged. A candidate key is video_id plus start_ms, so the same window is never judged or written twice.

Step 1: Check the Vivu connector and the setup

Goal: know that every tool the run needs is present.

1. Call vivu_get_account. If the tool does not exist, tell the user to add the Vivu connector in Claude (https://mcp.vivu.ai/mcp) and stop. If it returns can_create_projects: false, or a later write fails with "has not granted vivu.write", ask the user to reconnect Vivu and allow write access.
2. Run ffmpeg -version and ffprobe -version. If either is missing, say so and stop.
3. Check the remaining rows of What you need and list anything missing in one message.

Done when every row of What you need is confirmed or the user has been told what is missing.

Step 2: Collect the brief and inventory the spots

Goal: an inventory of every spot and a brief written as search slots.

1. Ask the user to confirm the client allows these spots to be reused for the new cut, and whether anyone on screen is under 18. Minors need the client to confirm the talent release covers the new use; without that, leave those spots out. Also tell the user that the spots will be uploaded to a Vivu project in their account and stay there until they delete it, and ask whether the client agreement allows delivered or unreleased spots to be processed in a third party tool. Without a yes, stop before Step 4.
2. Make the working folders first; ffmpeg and the shell redirect stop with "No such file or directory" when the folder is missing:

mkdir -p recut-sheet/proxies recut-sheet/results recut-sheet/frames recut-sheet/clips

Measure every file. Save this as inventory.sh and run it with the spots folder as the argument:

#!/bin/sh
# usage: sh inventory.sh SPOTS_DIR > recut-sheet/inventory.csv
echo "file,duration_s,width,height"
for f in "$1"/*.mp4 "$1"/*.mov; do
  [ -e "$f" ] || continue
  d=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f")
  wh=$(ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 "$f")
  echo "$(basename "$f"),$d,$wh"
done

3. Label versions from length and shape (width less than height is vertical).
4. If the files are large masters, make 720p proxies for upload. 720p keeps supers readable at a fraction of the size, and the sheet still points at the original file names:

ffmpeg -v error -i SPOTS_DIR/FILE -vf "scale=-2:720" -c:v libx264 -crf 23 -c:a aac recut-sheet/proxies/FILE

FILE is a file name from inventory.csv.

The proxy step was not exercised in our test run (the files were already 720p). 5. Turn the brief into slots. Describe the product by what it looks like (color, finish, shape of the camera, lens or cap) and what it is doing (held in a hand, on a table, floating), never by the logo; Vivu does not read logos for this skill.

Done when inventory.csv has one row per spot and the user has confirmed the slot list.

Step 3: Price it and get approval

Goal: the user approves the index minutes and search credits before anything is uploaded.

1. Total minutes = sum of duration_s in inventory.csv / 60.
2. Call vivu_get_usage for the plan and what remains this month.
3. Search credits (estimate): one precise search per slot, plus one more for each product that has a look-alike in the range (Step 5), at 5 credits each; a fast search uses 1 credit. One product with a look-alike, one claim line and supers is 4 searches, 20 credits. A search rerun because it returned exactly maximum_results costs another 5; ask before rerunning.
4. Show one table:

For reference, Free has 20 indexing minutes a month and 50 search credits a month; Premium is $30 a month with 180 indexing minutes and 500 search credits. For example, 25 spots of about 40 seconds is roughly 17 minutes (estimate), inside the Free allowance. 5. If it does not fit, offer these levers in order: index only the versions the brief can use (for example the horizontal masters, not every cutdown, and find the cutdowns later in Step 7 by looking at them locally); drop spots from campaigns the brief does not touch; split the job across two months; move to a larger plan. Never drop spots silently.

Done when the user has approved the table.

Step 4: Create a private project and upload

Goal: every spot indexed in a project only the user can see.

1. Call vivu_list_projects. Reuse a project for this client and brief if one exists. Otherwise call vivu_create_project with name "CLIENT recut sources" and visibility "private". The default visibility is organization, which shows the project to everyone in the Vivu workspace; client footage should not be visible that way.
2. Call vivu_open_upload_page with the project ID. The upload_url it returns expires in 180 seconds and works once, so request it right before use and never paste it into a document or message.
3. Give the link to the user to open in their own browser and select the files (or the proxies), or attach the files with a browser tool that can attach local files. Claude in Chrome accepts at most 10 MB per upload call; send larger files through the user's browser or have the user add them in the Vivu web app. Do not split or recompress spots to fit a tool limit.
4. Poll vivu_list_videos until every video shows ready. Vivu replaces spaces and brackets in file names with underscores; match each video back to inventory.csv by that normalized name, or by duration_ms against duration_s when two names collide. Record each video_id in inventory.csv and state.json.

In our test run the upload went through a headless browser rather than a user's browser, so the user side of the upload was not exercised in our test run; 12 spots were ready about 5 minutes after the upload link was requested.

Done when every row of inventory.csv has a video_id and every video shows ready.

Step 5: Run one search per brief slot

Goal: a small set of candidate windows per slot.

PRODUCT_COLOR, CLAIM_IN_PLAIN_WORDS and EXAMPLES come from the brief: describe the product the way a viewer would see it (the query above is the one we ran, for a coral pink phone), and the claim the way a person would say it. In our test run these three ran as product_a, claim_spoken and super_text.

Finding a product by how it looks relies on Vivu's visual matching, which is a weak capability: it finds most appearances but can miss close-ups and can label a look-alike with the color you asked for. Treat every product result as a candidate until Step 6. Spoken lines and large on screen text are stronger signals, and they still get checked.

Each query answers one column of the sheet. The product search finds where the product is on screen; Step 6 confirms the model on frames and Step 7 uses the same frames to find the shot in other versions. The claim search finds where the line is spoken; Step 6 takes the exact words from the transcript. The super search is the same claim flipped from said to shown: supers often restate the spoken line, and the frame gives the exact text.

Run each with vivu_search_videos (project_id, query, mode "precise", maximum_results). Use precise for every slot: fast returns whole files with an empty reason and gives no in and out points. maximum_results is also the ceiling on how many windows come back; 20 covers a product that appears two or three times in each of a dozen spots, and 30 covers supers when each spot carries two to five. If a search returns exactly maximum_results, raise it and, after the user approves the extra 5 credits, run again. Poll 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 each completed result as results/FIELD.json. Show the Vivu result page link in the reply if the user wants to browse; it expires after four hours, so it never goes in the sheet.

A product that has a look-alike in the same range (same shape, different color or tier) gets a second search for the look-alike, so the check in Step 6 can see where Vivu mixes them up.

End cards (product name lockups, logos, dates) have no search of their own: they reach the sheet only when the product or super search returns them, and end cards were not measured in our test run. When the brief wants every end card, look at the last 5 seconds of each spot locally with the Step 6 strip command.

Done when every slot has a saved result file.

Step 6: Check every candidate

Goal: every candidate judged real or rejected, with the frame or transcript that decided it.

For product shots and supers, make a strip of frames every half second across the window. START and END are the window's start_ms and end_ms divided by 1000; ROWS is (END - START) x 2 / 8 rounded up (a 7 s window is 2 rows, a 29 s window is 8 rows); FILE is the local file for that video_id; FIELD is the slot and N the result number:

ffmpeg -v error -ss START -to END -i FILE -vf "fps=2,scale=240:-2,tile=8xROWS" -frames:v 1 recut-sheet/frames/FIELD_hN_strip.png

A fixed grid would drop every frame past the last tile, so size ROWS to the window.

Look at the strip. Vivu returns a time range that contains the moment, not an exact frame, and a window can hold several shots. In our test run the median product window was 7 seconds, and one super window was 29 seconds wide and held several different supers, so read every tile, not only the middle.

1. Product shot: real only when the strip shows the brief's model in the brief's finish. Outline-only silhouettes and screen-side shots do not count. Take the in and out points from the tiles where the product is visible, not from the window edges.
2. Super: read the text from a full frame, never from Vivu's reason. Small type, vertical versions and legal lines need the full frame. SECONDS is the second of the tile where the super is fully on screen:

ffmpeg -v error -ss SECONDS -i FILE -frames:v 1 -q:v 3 recut-sheet/frames/FIELD_hN_read.png

A product name lockup without a sentence is an end card, not a super; file it under end card only if the brief asked for end cards. 3. Spoken line: read the local transcript for the window (the delivery's caption file, or local speech to text) and copy the words from there. The reason text is a paraphrase, not a transcript. As a second signal, call vivu_get_video_summary with include_segments true and start_ms and end_ms around the window. Summary segments describe what is shown, so when the same words are both spoken and on screen they may describe only the text; the transcript decides. 4. Write rejected candidates to rejected_candidates.csv with the reason, and count them.

Worked example from our test run

In our test run we used 12 public spots from one phone maker's launch campaign (5.69 minutes, three horizontal and vertical pairs, a pro model in coral pink and a look-alike base model in lavender with the same camera bar), with truth written from contact sheets before any search. The product query returned 12 windows: 10 real and 2 false, both outline-only silhouettes, and it missed 4 moments in our truth list (three close-ups and one end packshot). The look-alike never came back for the coral query, but the mirror query for the lavender model returned 6 windows, 3 real and 3 false, where the coral model or a green finish was labeled lavender. The claim query returned 2 real and 0 false, but the same app names were also on screen, so a voice-only control line (dialogue with no text) was searched too and came back 1 real. The super query returned 11 windows: 10 real, 1 false (a name lockup) and 1 missed super. No query was reworded.

Done when every candidate is in the sheet as a checked row or in rejected_candidates.csv with a reason, and the user has seen the counts of real and rejected per slot.

Step 7: Merge versions of the same shot

Goal: one row per shot, listing every version that carries it.

1. For each checked product row, look for the same shot in the other versions of that spot (same length family or same title, plus any vertical). Make a one frame per second sheet of the other version (ROWS is duration_s of FILE_B / 8 rounded up) and find the matching moment:

ffmpeg -v error -i FILE_B -vf "fps=1,scale=240:-2,tile=8xROWS" -frames:v 1 recut-sheet/frames/merge_ROW_sheet.png

Then confirm side by side. FILE_A and SECONDS_A are the checked row's file and a second inside its in and out points; FILE_B and SECONDS_B are the other version and the matching second read off the sheet; ROW is the row_id:

ffmpeg -v error -ss SECONDS_A -i FILE_A -ss SECONDS_B -i FILE_B -filter_complex "[0:v]scale=-2:360[a];[1:v]scale=-2:360[b];[a][b]hstack" -frames:v 1 recut-sheet/frames/merge_ROW.png

2. Same take, different framing (a vertical recrop of a horizontal shot) counts as the same shot; note the framing in also_in_versions.
3. Supers and end cards repeat across versions too; list each repeat with its time.

Done when every product and super row has also_in_versions filled or marked none found.

Step 8: Build the source sheet

Goal: the CSV the editor opens.

Show the user this field mapping and one sample row before writing the rest, and wait for a yes:

row_id,brief_slot,moment_type,source_file,version,start_mmss,end_mmss,frame_path,visual_description,spoken_line_local_transcript,on_screen_text_from_frame,also_in_versions,rights_flags,use_it
r01,product hero,product_shot,CLIENT_LAUNCH_30s_v3.mp4,30s horizontal,00:07,00:10,frames/product_shot_h11_strip.png,"coral pink phone floating camera bar down over a sun lounger",,"legal line at bottom",CLIENT_LAUNCH_vert_25s_v2.mp4 00:18-00:20 (vertical recrop),"talent on screen: CHECK; licensed music: CHECK",

For a reference clip the editor can drop in a timeline, re-encode so the cut lands on the exact frame. START and END are the row's start_mmss and end_mmss in seconds; FILE is the row's source_file in SPOTS_DIR; ROW_ID is the row_id:

ffmpeg -v error -ss START -to END -i FILE -c:v libx264 -c:a aac recut-sheet/clips/ROW_ID.mp4

If fewer moments exist than the brief asks for, report the real number; do not pad the sheet.

Done when the user has approved the sample row and source_sheet.csv holds one row per checked moment, with rejected_candidates.csv beside it.

Compliance

1. Reuse rights: use only spots the client allows the agency to reuse, and ask before Step 2. Music, talent (on screen and voice) and stock footage are often licensed for the original flight only; every row carries CHECK flags and the editor confirms with the client or producer. The skill never decides that a license covers the new use.
2. People on screen: talent releases apply. If anyone appears to be under 18, the client confirms the release covers the new use before those spots are included.
3. Where the footage goes: the spots are uploaded to a Vivu project in the user's account and stay there until the user deletes it. Asked in Step 2, before anything is uploaded. Create it as private in Step 4. Delete a project or video only when the user asks, and confirm first.
4. No recognition of faces, people or logos. Products are found by how they look, and every product row is checked on frames.

Known failure modes