---
name: news-archive-pull-sheet
description: "Turn a station's past news packages into an archive pull sheet with Vivu: lower third text read from frames, outside footage credits, timecodes. Use when producing an anniversary or follow up story."
---News archive pull sheet with Vivu
This skill takes the past news packages a producer has already picked out of the station's archive for an anniversary or follow up story, plus a short list of what the editor needs to pull (a lower third that names a place, footage with an outside source credit, older footage that was reused, a reporter standup), and returns a pull sheet. Claude measures the packages, prices them against the user's Vivu plan, indexes them in a private Vivu project, runs one search per need, checks every result in frames from the user's own files, reads each lower third from a full frame, copies quotes from the station's transcript or caption file, and writes pull_sheet.csv with an empty "third party rights checked" column for a person to fill. Nothing is edited, published or sent by the skill.
The value is in what only the picture shows. The newsroom system keeps the slug, the air date and the script, but not what the lower third said, which shots carry a "Courtesy of", AP, AFP or REUTERS bug in the corner, or where an anniversary piece reused footage from the original event. Those details decide what the editor may pull and what needs a rights check, and they sit in the frame. Every row of the sheet comes from frames Claude looked at; lower third text is copied from a frame, never from Vivu's reason text.
When to use
Use when a producer or archive editor says "pull everything we aired where the lower third says New Orleans", "find the sound bites with the mayor of Sea Bright from our Sandy coverage", "which shots in these packages came from AP or a viewer", or "make a pull sheet from these twenty packages for the ten year piece". It fits 10 to 25 finished packages of 1.5 to 4 minutes each, chosen first from the rundown or script archive.
Not for:
- Indexing the whole archive. Pick the packages by date and slug in the newsroom system first; indexing years of air is far beyond any Vivu plan.
- Clearing rights. The skill marks footage that carries an outside credit; a person checks the license before reuse.
- Identifying people. Names come only from what the lower third prints. No face recognition.
- Checking numbers in a story. That is a fact check, not a pull sheet.
- One question about one package. Open it, or search the Vivu project directly.
Working principles
- Report measured numbers, not estimates. When a number is an estimate, say so.
- A search result is a candidate until Claude has looked at frames from the user's file inside the result window. Only checked rows go on the pull sheet.
- 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: the package list and the cost (before upload), the needs and their search wording (before searching), and the sample row (before writing the sheet).
- Lower third text is read from a full frame. The reason text is a paraphrase; it read the title lines correctly in our test run, but it is still not a source.
- Quotes come from the station's script, caption file or a local transcript, and an auto caption quote is marked so someone checks it by ear.
What you need before starting
The skill runs in Claude Code on the computer that holds the packages (a terminal or the Code tab of Claude Desktop), because it reads local files and runs ffmpeg. It downloads nothing, so no particular network or residential IP is needed. It runs once per story; nothing is scheduled and nothing is posted. Check each item at the start and tell the user plainly what is missing before doing anything else.
| Requirement | Why | How to check |
|---|---|---|
| Vivu connector with write access | create a 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: reconnect Vivu and allow write access. No Vivu tools at all: add the Vivu connector (https://mcp.vivu.ai/mcp) and stop |
| A shell with ffmpeg and ffprobe | measure the packages, extract frames and contact sheets | ffmpeg -version and ffprobe -version |
| The chosen packages in one folder (proxies are fine) | the footage to search | list the folder once |
| For each package, its slug and air date from the newsroom system | the air_date column and finding the master later | ask for a CSV export or a pasted list; match on file name |
| Scripts or caption files for the packages (optional) | exact quotes | open one; without them the quote column stays NOT TRANSCRIBED |
| A way to upload local files | move the packages into Vivu | the user's own browser, or a browser tool that can attach local files (Claude in Chrome takes up to 10 MB per upload call) |
Inputs to collect
Ask for anything missing, most important first.
- The story and its needs (required): 2 to 6 things the editor must pull, each in plain words, for example "lower thirds that name Sea Bright or Rumson", "every shot with an outside source credit", "the original flood footage we reused".
- The package folder and the slug and air date list (required).
- Which packages to index. Default: all of them if the total fits what is left of the plan this month; otherwise the ones whose scripts mention the story's places or events (Step 2).
- Script or caption files. Default: none, quotes stay NOT TRANSCRIBED.
- The Vivu project name. Default: "Archive pull STORY_SLUG", private.
Files and state
Keep the working files in their own folder next to the packages:
archive-pull/
config.json story slug, needs and their search wording, package folder, project_id
packages.csv file, slug, air_date, duration_s, uploaded_name, video_id
results/ raw result of each need search without its result page link, one JSON file per need
frames/ strips, half second contact sheets and full frames Claude checked
pull_sheet.csv one row per checked moment (Step 8)
coverage.md needs with no checked row, rejected results, flags for the producer
state.json uploaded files with video_id, searches run with job_id, results judged
A rerun reads state.json first and skips what is done: packages already in the project, needs already searched, results already judged. When the producer adds packages, only the new ones are uploaded; the need searches run again because a search covers the whole project, and judged results are kept.
Step 1: Check the Vivu connector and the setup
Goal: every row of What you need is present, or the user knows exactly what is missing.
- Call vivu_get_account. If the Vivu tools are missing, tell the user to add the Vivu connector in Claude (https://mcp.vivu.ai/mcp) and stop. The account must show can_create_projects: true. If a later write call fails with "has not granted vivu.write", ask the user to reconnect Vivu and allow write access, then retry.
- Run ffmpeg -version and ffprobe -version. Without them the packages cannot be measured or checked; stop and say so.
- List the package folder and read the slug and air date list. Say which files have no air date.
Done when vivu_get_account shows can_create_projects: true, ffmpeg and ffprobe answer, and the folder and the list are in hand.
Step 2: Pick the packages and size the job
Goal: the user approves which packages get indexed and what it costs, before anything is uploaded.
If the folder holds more than the story needs, narrow it with text first: search the scripts or rundown export for the story's places, names and events, and keep the packages that mention them. A ten year piece rarely needs more than 15 to 25 packages.
Choosing packages from a rundown was not exercised in our test run; the test packages were picked by hand.
Measure each file (FILE is the package):
ffprobe -v error -show_entries format=duration -of csv=p=0 "FILE"
- Searches: one precise search per need and per place name. A precise search uses 5 credits in total. As an estimate, 20 packages of about 2.5 minutes are 50 index minutes, and 5 needs are 25 credits; label the credit figure as an estimate.
- Call vivu_get_usage for the plan and what remains. The plans: 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 a month and 500 search credits a month.
- Show one table:
| This job | Remaining this month | Fits | |
|---|---|---|---|
| Index minutes | measured sum | from vivu_get_usage | yes or no |
| Search credits (estimate) | needs and place names x 5 | from vivu_get_usage | yes or no |
- If it does not fit, offer these levers in order: index only the packages whose scripts mention the story's places; drop packages the producer already knows they will not pull from; split the needs into two sessions; move to a larger plan. Name every package that is left out.
If vivu_get_usage returns no remaining figures (some admin or team accounts return null), show the needed minutes and credits anyway and ask the user to confirm the allowance.
Done when the user approves the package list and the cost table.
Step 3: Upload and index
Goal: every approved package is ready in one private Vivu project and matched to its row in packages.csv.
- Call vivu_list_projects. Reuse this story's project if one exists. Otherwise call vivu_create_project with the project name and visibility "private"; the default is "organization", which every member of the Vivu workspace can see, and archive packages often hold material the station licensed only for air.
- Call vivu_open_upload_page with the project_id right before the upload. The link expires in 180 seconds, so request it only when the user or the browser tool is ready, and never paste it into a file or a message.
- Give the link to the user to open in their own browser and select the packages (the page takes several files at once), or open it with a browser tool that can attach local files. Claude in Chrome accepts at most 10 MB per upload call; most packages are larger, so they go through the user's browser or the Vivu web app. Never split, trim or recompress a package to fit.
- Poll vivu_list_videos about every 30 seconds until every package shows status ready. Vivu replaces spaces and brackets in file names with underscores; match each video back to packages.csv by the normalized name and by duration_ms against duration_s, and write video_id into packages.csv and state.json.
The upload through the user's own browser was not exercised in our test run; the test packages reached Vivu through the same upload page opened by an automated browser. In our test run all 12 packages (28.96 minutes) were ready about 10 minutes after the upload began.
Done when vivu_list_videos shows every package as ready and every row of packages.csv has a video_id.
Step 4: Turn the needs into searches
Goal: one search per need, written as what is on screen, approved by the user.
Lower thirds are text on the picture, so search for the words of the title line. Use one search per place name: in our test run a single search for "any caption with a place in it" found 8 of the 17 captions whose title line names a place, while the searches for one named place at a time missed only one caption (see the worked example below).
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| lower third naming PLACE (one search per place) | a name caption in the lower third of the screen whose title line includes the place name PLACE | precise | 20 |
| outside footage credit | a small on-screen credit in a corner of the picture naming where outside footage came from, such as "Courtesy of", a news agency name like Reuters, AP or AFP, or a social media source | precise | 40 |
| older footage reused (candidate) | older archive footage reused in the story: black and white film, or earlier disaster footage of flooded streets and rooftop rescues that looks older than the rest of the report | precise | 30 |
| reporter standup (candidate, recall untested) | the reporter stands on location and talks straight to the camera holding a microphone, as a news standup | precise | 20 |
PLACE is the name exactly as the station's graphics would print it. Add the abbreviation the graphics use ("New Jersey or NJ"). A caption whose title line does not print the place (MAYOR OF HOBOKEN for a New Jersey search) is not found by that search; search the town too. Rewrite the older footage query for the story's event (for example "earlier earthquake footage of collapsed buildings").
The chain: the place searches find who was captioned where, from the words on screen; the credit search turns the same packages from "who said it" to "whose picture is it", which is what the rights column needs; the older footage search marks material the station itself reused, which often carries its own credit or rights question; the transcript then gives the exact words for a sound bite.
maximum_results is also the ceiling on what a search can return. 20 is far above the captions one place gets in 25 packages; 40 for credits because wire footage runs through many packages. If a search returns exactly its maximum, raise it and search again.
Show the user the needs, the place names and the wording, and wait for approval.
Done when the user approves the list of searches.
Step 5: Search each need
Goal: a saved result for every approved search.
- Run each search with vivu_search_videos (project_id, query, mode "precise", maximum_results as in the table). Only precise returns a time range and a reason Claude can check; fast returns the whole file with an empty reason, so it is not used here.
- Call vivu_get_search_results with the job_id until complete is true; each status call can wait up to 45 seconds, so a pending search is not a stalled one.
- Save the result as results/FIELD.json with its result_page_url field removed. The result page link may go in the live reply only, because it expires after four hours.
Done when every approved search has a results file.
Step 6: Check every result in frames
Goal: for every result, the lower third or credit read from a frame, the picture described, and a keep or reject decision.
- For every result, extract a strip of three frames at the start, middle and end of the window (FILE is the package; START, MID and END are seconds inside the window; FIELD and N name the output):
ffmpeg -v error -ss START -i "FILE" -ss MID -i "FILE" -ss END -i "FILE" -filter_complex "[0:v]scale=640:-2[a];[1:v]scale=640:-2[b];[2:v]scale=640:-2[c];[a][b][c]hstack=inputs=3" -frames:v 1 archive-pull/frames/FIELD_hN_strip.png
- A lower third is on screen for only a few seconds and the window is wider, so the three frames can all miss it. When the strip does not show the caption, make a half second contact sheet over the window (LENGTH is the window length in seconds); tile K is at START + (K - 1) / 2 seconds:
ffmpeg -v error -ss START -t LENGTH -i "FILE" -vf "fps=2,scale=320:-2,tile=6x4" -frames:v 1 archive-pull/frames/FIELD_hN_sheet.png
- Extract one full frame where the caption or credit is fully on screen and copy its text exactly, every line, with the graphic's own spelling and capitals. Corner credits are small; read them from the full frame, not the sheet:
ffmpeg -v error -ss SECONDS -i "FILE" -frames:v 1 -q:v 3 archive-pull/frames/FIELD_hN_read.png
- Keep a place result only when a frame shows a name caption whose title line prints that place. Keep a credit result only when a frame shows the credit. Keep an older footage result only when the frames show footage older than the package's own shoot (film, a different aspect ratio, an earlier event); Vivu's search by what a picture shows is rated weak, so this column is always a candidate for the producer to confirm.
- Rejected results go into coverage.md with the reason text and what the frames showed, and are counted as false positives. A need with no kept result is listed too: an empty result does not prove the packages have no such moment.
- Report to the user per search: results returned, kept, rejected, and needs left uncovered.
Worked example from our test run
The test corpus was 12 public storm and flood packages (28.96 minutes) from a U.S. government broadcaster's TV news service, standing in for a station's own archive. They carry name captions in an older and a newer graphic style, corner credits for agency, courtesy and social media footage, reused film and earlier flood footage, and no reporter standups. Truth was written from contact sheets before any search, with look alike text as distractors (after the search, full frames corrected one caption time and added two events the sheets had not shown: an AFP corner credit and earlier storm footage at the start of a later rebuilding package; both are counted as real below): a full screen film title card reading NEW ORLEANS, a place name lettered on a fire station, a backdrop behind a briefing, and a control place that no package names.
In our test run the searches for one named place each (New Orleans, Brooklyn, Louisiana, New Jersey) returned 10 results: 10 real, 0 false, and 1 caption missed of the 11 whose title line names those places. The missed caption used the newer graphic style, a white box in title case. The control place returned nothing, and none of the distractors was returned. The reason text read every kept title line correctly. None of the wordings was changed after the first run.
In the same run the credit search returned 10 results, 10 real and 0 false, with 1 small agency credit missed; the older footage search returned 6, 5 real and 1 false (the package's own flood rescues), with 1 missed; counted against the truth written before the search, it found 4 of 5; the standup search returned nothing on a corpus with no standups, so its recall is untested. This is one small corpus from one broadcaster; other stations' graphics, burned in tickers and low resolution proxies were not tested.
Done when every result has been judged from frames and the user has seen the per search counts.
Step 7: Take quotes from the station's transcript
Goal: the exact words for each kept sound bite, or NOT TRANSCRIBED.
- Open the package's script or caption file and find the lines whose time falls inside the kept window. For a WebVTT or SRT file (CAPTIONS_FILE is the package's caption file), list every cue that starts in the window's minute (MM is the two digit minute of the window start; run it again with the next minute if the window crosses into it), then keep the cues whose start time falls inside the window:
grep -n -A2 "^00:MM:" "CAPTIONS_FILE"
- Copy the line into quote_from_transcript. If the source is an automatic caption track, add "(auto captions, check by ear)": in our test run the auto captions turned a spoken number into "9t". The reason text is a paraphrase and is never used as a quote.
- Without a script or caption file, write NOT TRANSCRIBED. Local speech to text was not exercised in our test run.
Done when every kept caption row has a quote or NOT TRANSCRIBED.
Step 8: Write the pull sheet
Goal: pull_sheet.csv the editor can work from, and coverage.md for the producer.
- Write one row per kept moment, needs in the order the producer gave them:
need,package_file,air_date,window_mmss,on_screen_mmss,lower_third_text_from_frame,source_on_screen,picture_from_frames,quote_from_transcript,frame_path,flags,third_party_rights_checked
caption naming New Orleans,PKG_FILE.mp4,AIR_DATE,00:31-00:42,00:34-00:38,"NAME / DEPUTY MAYOR, NEW ORLEANS",station (no outside credit in frames),"seated interview, painted map on the wall","QUOTE FROM THE CAPTION FILE (auto captions, check by ear)",frames/place_h3_sheet.png,,
PKG_FILE and AIR_DATE come from packages.csv; NAME and QUOTE are copied from the frame and the transcript. Caption lines are separated by " / ". on_screen_mmss is where the caption is on screen, read from the contact sheet when one was made; otherwise write WINDOW. source_on_screen is the credit as printed, or "station (no outside credit in frames)". flags marks a minor on camera, a victim's photo, a private contributor or a wire credit. third_party_rights_checked is always left empty. 2. Show the user the first rows and the field mapping, and wait for a yes before writing the rest:
| Field | Source | If unavailable |
|---|---|---|
| window_mmss | search window (start_ms to end_ms) | the row is not written |
| on_screen_mmss | where the caption or credit is fully on screen in the strip or contact sheet | WINDOW (the caption is somewhere inside window_mmss; make the half second sheet if the editor needs the exact second) |
| lower_third_text_from_frame, source_on_screen | full frame | [illegible] for unreadable words |
| picture_from_frames | frames | UNCERTAIN |
| quote_from_transcript | script or caption file | NOT TRANSCRIBED |
| air_date | packages.csv | UNKNOWN |
- Write coverage.md: needs without a kept row, rejected results with what the frames showed, and the flags.
- Tell the user how to find a moment on the master: the package file, air date and on_screen_mmss are enough. The Vivu result page link from Step 5 works for four hours and is not stored.
In our test run the sheet had 25 rows from the kept results, with names replaced by placeholders in our copy.
Done when pull_sheet.csv and coverage.md exist and the user has seen the counts of rows, rejected results and uncovered needs.
Compliance
- Rights. Use only packages the station has the right to use. Footage with an outside credit (an agency, a courtesy line, a viewer or social media source) is flagged and left for a person to clear; the skill never fills third_party_rights_checked and never removes a credit or logo. Ask the user to confirm this before Step 3.
- People on camera. Names are copied only from what a lower third prints. No face recognition, and no attempt to identify anyone who is not captioned.
- Minors and victims. Flag every row where a child is on camera or a victim's personal photo appears, and remind the producer to apply the station's own policy before reuse. If the story would reuse a minor's interview without that policy check, leave the row flagged and do not recommend it.
- Where the videos go. The packages are stored in the user's Vivu project until the user deletes them. Create the project as private; the default "organization" visibility shows it to every member of the workspace. The skill never calls vivu_delete_project or vivu_delete_video unless the user asks, and confirms first.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) a lower third that names the place is not returned | the station changed its graphics; our test missed a caption in a white box with a title case "New Orleans Resident" line | search each graphic style's wording if known; for a key place, look through the packages that mention it on a contact sheet |
| (observed) a search for any caption with a place in it found 8 of the 17 such captions | a category search finds about half; it does not read every title line | search one place name at a time, as in Step 4 |
| (observed) the reason says "Archive disaster footage" for the package's own flood rescues | the reason repeats the query's idea when the picture looks similar | judge older footage from frames and let the producer confirm |
| (observed) a small agency credit in the top left corner is not returned | small corner text is easy to miss | look at the first and last seconds of each package that contains wire footage on a full frame |
| (observed) auto captions read "got nothing to worry about cuz it's 9t" | automatic captions mishear numbers and names | mark auto caption quotes to check by ear; spell names from the lower third, not the captions |
| a search for a state does not return a caption that names only the town | the search finds the words printed on the title line | search the town names too |
| the frame strip shows no caption although the result is right | the caption is on screen for a few seconds of a wider window | make the half second contact sheet |
| "has not granted vivu.write" | Vivu connected read only | the user reconnects Vivu and allows 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 package is rejected by the browser upload tool | the file is above the tool's limit (Claude in Chrome takes up to 10 MB per call) | the user opens the upload link in their own browser or adds the file in the Vivu web app; never split or recompress it |
| a result's file name does not match packages.csv | Vivu replaced spaces or brackets with underscores | match on the normalized name and on duration_ms |
| a search returns exactly maximum_results results | the search reached its ceiling | raise maximum_results and search again |
| the allowance runs out partway | more packages were indexed than the month allows | stop, keep state.json, and continue next month or on a larger plan |