---
name: campaign-ad-claim-citation-queue
description: "Turn a batch of local campaign ads into a fact-check queue CSV with Vivu: on-screen claims, the source line under each, the paid for by line and spoken numbers. Use in election season."
---Campaign ad claim and citation queue
This skill builds a fact-check queue from a batch of campaign ads. The reporter gives Claude a folder of ads from candidates, committees and issue groups in their coverage area (15 to 60 s spots, horizontal and vertical cuts). Claude indexes them in a private Vivu project, runs one search each for claim cards, the small source lines printed under them and the paid for by line on the end card, reads every one of those from full frames of the reporter's own files, sweeps each ad with a contact sheet for anything the searches missed, adds the numbers the narrator says out loud from a local transcript, and writes a queue CSV with an empty verdict column for the reporter.
The value is that the sourcing of an ad lives only in the picture. Ad libraries often carry a title or a thumbnail and no transcript; the narrator never reads the source line, which sits on screen for two to five seconds in small type; the paid for by line is fine print on the last card. The card and the narrator also tend to say different numbers, and both need checking. Nothing in the queue comes from Vivu's description of a moment: every claim, source and sponsor line is read from a frame, and every spoken number from a transcript.
When to use
Use when a reporter or editor asks to log the claims in this week's campaign ads, pull the on-screen sources from a set of political spots, build a fact-check queue from ads, find which ads cite a bill number or a newspaper, or list who paid for each ad. For one question about one ad ("what source does the tax ad cite"), open the file or run one Vivu search instead. This skill does not decide whether a claim is true, does not identify people, faces, voices or logos, and does not judge whether a disclaimer meets election law; those calls belong to the newsroom.
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 in the queue comes from a frame Claude read or a transcript line.
- 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, downloading, posting the queue anywhere).
- Never guess a word or a digit in a source line. When a frame is too small or blurred to read, the cell says UNREADABLE and the reporter checks the original upload.
- Treat every ad the same way. Run the same searches on every ad in the batch, whichever side it is from, and never filter by party.
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 ad folder | measure durations, extract frames, crops and contact sheets from the reporter's own files | ls ADS_DIR lists the ad files |
| ffmpeg and ffprobe | frames, crops and contact sheets | ffmpeg -version and ffprobe -version |
| A local transcript for each ad, or a way to make one | spoken numbers are quoted from a transcript, never from Vivu's reason text | captions downloaded with the ad (.vtt), or whisper --help answers |
| An upload path | moving the ads into Vivu | vivu_open_upload_page plus the user's own browser, or a browser tool that can attach local files |
| yt-dlp and node, on a residential IP (only if Claude downloads the ads) | YouTube blocks downloads from cloud IPs | yt-dlp --version and node --version; a one ad test download |
| 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 a residential IP only when Claude downloads the ads itself, and no scheduler: it is run once per batch of new ads.
Inputs to collect
Ask for anything missing, most important first.
- The ads (required): a folder of files (called ADS_DIR in the commands below), or the official channel or page links to download from into that folder.
- The race or coverage area, used only to name the project and the CSV. Default: "local ads DATE".
- Whether the user has confirmed with their editor that downloading and indexing the ads for internal checking is fine. Required before Step 2, because Step 2 downloads the ads.
- Where transcripts come from. Default: captions that came with the ad; otherwise a local whisper run.
- Where the queue goes. Default: the CSV in the working folder; no posting.
Files and state
Keep everything in one working folder next to the ads:
ad-claim-queue/
ads.tsv file name, origin link, sponsor as listed by the source, duration_s, width, height, Vivu video_id
state.json project_id, searches run (field, job_id), ads swept, transcripts done, rows written
results/FIELD.json each completed search result, saved without its result_page_url
transcripts/ one .vtt or .txt per ad
frames/ full frames and enlarged crops used for reading
sheets/ 0.5 s window sheets and 1 s ad sheets
claim_queue.csv the deliverable
state.json makes a rerun resume and keeps a new batch from repeating old rows: skip searches whose job_id already has a saved result, skip ads already swept, and never write the same (ad_file, on_screen_start, kind) row twice. When a new batch arrives, add the new files to the same project and sweep only the new ads. 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 ADS_DIR, or confirm yt-dlp and node if Claude is downloading.
- Check the transcript source for the ads.
Done when the account check passed, ffmpeg answered, and the ads folder (or the list of links to download) is in hand.
Step 2: Collect the ads
Goal: one local file per ad, with its origin and duration.
Before downloading or indexing anything, confirm that the user has cleared this use with their editor (Compliance 1). If they have not, stop here.
If the user gave links, download each ad from its official channel on the residential IP machine. One ad, one command (VIDEO_URL is the ad's page; ADS_DIR the ad folder):
yt-dlp --js-runtimes node --restrict-filenames -f "bv*[height<=720]+ba/b[height<=720]" --merge-output-format mp4 --match-filter "duration<=180" --download-archive ADS_DIR/archive.txt --write-subs --write-auto-subs --sub-langs "en.*" -o "ADS_DIR/%(id)s_%(title).60B.%(ext)s" "VIDEO_URL"
720p keeps an 18 px source line readable; many ads are posted at 360p, where it often is not (see Step 6). The youtube-competitor-watch skill (https://vivu.ai/skills/youtube-competitor-watch) covers channel verification and download troubleshooting in more depth. If a download fails with "HTTP Error 403: Forbidden", retry once with --extractor-args youtube:player_client=web_embedded.
- Measure each ad, one file per ffprobe call (FILE is one ad's file name):
ffprobe -v error -show_entries stream=width,height:format=duration -of csv=p=0 "ADS_DIR/FILE"
- Write ads.tsv. Flag vertical ads and anything under 720 pixels on the short side: source lines there may not be readable.
Downloading campaign ads was not exercised in our test run (the test ads were synthetic); the public control ads were re-downloaded with the same options plus the web_embedded client.
Done when ads.tsv lists every ad with a measured duration.
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 batch: three on-screen searches, one spoken search and one control, all precise.
- Call vivu_get_usage and show one table:
| This batch | 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. For example, 20 ads of about 40 s is roughly 14 minutes (an estimate), which fits the Free plan.
- If the batch does not fit, offer to index only the ads that are new since the last run, or only the ads in the races the desk is covering this week, then a larger plan. Never drop an ad the user asked for without naming it.
This step was not exercised in our test run: the test account has no plan allowance to compare against.
Done when the user approves the table.
Step 4: Upload and index
Goal: every ad ready in a private project.
- Call vivu_list_projects and reuse the project for this race if one exists. Otherwise call vivu_create_project with name "Ad claims RACE" and visibility "private". The default visibility is organization, which shows the newsroom's working material 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 ad 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 an ad to fit, because the frames you read must be the frames that aired.
- Poll vivu_list_videos until every ad is ready. Vivu replaces spaces and punctuation in file names with underscores, so match each video_id back to ads.tsv by the normalized name (the YouTube ID at the start of the name when there is one) and record it.
In our test run the 6 synthetic ads were all ready within 4.8 minutes of the upload starting (an upper bound; some waited in the queued state while the others were already ready). That upload used an internal uploader; the user browser path was not exercised in our test run.
Done when ads.tsv has a video_id for every ad and every one shows ready.
Step 5: Find claims, sources and sponsor lines with Vivu
Goal: a time window for each claim card, source line, paid for by line and spoken number that Vivu returns; Step 7 and Step 8 catch what it misses.
Each query describes the kind of text and where it sits, never a candidate's words, so every ad gets the same searches. Run them with vivu_search_videos (project_id, query, mode "precise", maximum_results as in the table). Precise is the only mode that returns a time window; fast returns whole files, and ads are short enough that picking files first saves nothing. maximum_results is the recall ceiling: 40 covers a batch of 20 ads with one to three claim cards each; 20 covers one sponsor line per ad.
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| claim_card | a text card on screen in a political ad that states a charge or a number about a candidate's record, such as a tax increase, a vote, a dollar amount or a percentage | precise | 40 |
| citation | a line of small source text printed under a claim on screen, naming where the claim comes from, such as a newspaper name and date, a report title and page, or a bill or roll call number | precise | 40 |
| sponsor | the paid for by disclaimer text on screen at the end of the ad that names the committee or group that paid for it | precise | 20 |
| spoken_claim | the narrator says a number, a dollar amount or a percentage about what an official did | precise | 20 |
| control | an on-screen reminder of election day, the voting date or polling place hours (change it to a category this batch does not have) | precise | 10 |
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.
The chain: claim_card gives the window of each card; citation points at the same cards from the source line's side, which matters because a source line is small and Vivu describes only part of a window; sponsor is a separate search because the paid for by line sits on the end card, away from the claims; spoken_claim flips from what is on screen to what is said, because the narrator often states a different number from the card. 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.53 minutes: 6 synthetic local campaign ads with fictional candidates, committees and sources, plus 12 public carrier ads reused as a real-ad control), the claim_card search returned 7 windows, 7 real and 0 false, with 0 cards missed against the ground truth. The longest window held both claim cards of one ad, and the reason named only the first. The citation search returned 7 real and 0 false with 0 source blocks missed; the sponsor search returned 6 real and 0 false with 0 missed; the spoken_claim search returned 4 real with 1 missed (the veterans ad's line about the wait for care). The control returned nothing. On the public ads the same citation wording returned 3 windows, and all 3 were real source lines (a speed test attribution under a network claim). The queries ran as first written, with no rewording.
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 claim, source and sponsor line from full frames
Goal: the exact on-screen text, read by Claude from the user's file.
Vivu's window holds the card, but it is wider than the card, a source block often has two lines, and the reason text names only part of what is there. Never copy wording from the reason; it has stated a source year Claude could not confirm from the frame.
- 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:
ffmpeg -v error -y -ss START -to END -i "ADS_DIR/FILE" -vf "fps=2,scale=240:-2,tile=8xROWS" -frames:v 1 sheets/FILE_START.png
- Pick the tile where the card is complete and the source line is visible, then extract that full frame at its time T:
ffmpeg -v error -y -ss T -i "ADS_DIR/FILE" -frames:v 1 -q:v 3 frames/FILE_T.png
- Crop the source line or the sponsor line and enlarge it before reading (X, Y, W, H in pixels of the source frame; 3x to 4x for a 360p ad):
ffmpeg -v error -y -ss T -i "ADS_DIR/FILE" -vf "crop=W:H:X:Y,scale=iw*4:-2" -frames:v 1 frames/FILE_T_source.png
- Write down the claim, every line of its source block and the sponsor line exactly as they appear, with on_screen_start and on_screen_end as MM:SS from the first and last tile that show them. A newspaper clipping counts as a claim with its masthead and date as the source. When a word or digit cannot be read with certainty, keep what is legible and mark the cell UNREADABLE. A claim card with no source line gets NO CITATION ON SCREEN.
- A window that holds nothing of the kind it was searched for (a slogan card, a name super, small print that is not a source such as "Dramatization") is a false result. Count it per search and keep it off the queue; Step 9 reports these counts.
The -y flag lets a rerun overwrite a frame; without it ffmpeg stops and asks.
In our test run every synthetic source line and every paid for by line was read from full frames without a misread, including the smaller lines of the vertical ad. On the public carrier ads, which were posted at low resolution, the source lines were only partly legible and belong under UNREADABLE; the reason text stated the analysis year with confidence, which the frame could not confirm. The start, middle and end frames of a window are not enough: for the longest claim window all of them landed on b-roll or the slogan card.
Done when every window has its text written down with times and a frame path.
Step 7: Sweep every ad with a 1 s contact sheet
Goal: catch cards and source lines the searches did not return.
ffmpeg -v error -y -i "ADS_DIR/FILE" -vf "fps=1,scale=320:-2,tile=6xROWS" -frames:v 1 sheets/FILE_1fps.png
Set ROWS = ceil(duration_s / 6) from ads.tsv. Look at each sheet from the first tile to the last. Every tile with a claim, a thin line of small type under it or an end card that is not already in the Step 6 list gets read from a full frame as in Step 6. On a contact sheet a source line shows as a thin line that cannot be read; treat it as text to read, not as noise. Update state.json with the swept ad.
In our test run the sweep was run on the ad with the newspaper clipping only. It showed the clipping on screen a few seconds before the returned window began, so on_screen_start comes from the sheet, not from the window. Sweeping the other ads was not exercised in our test run.
Done when every ad in ads.tsv is marked swept in state.json.
Step 8: Add the spoken numbers from a transcript
Goal: every number the narrator says, quoted from a transcript and placed in time.
- Use the captions that came with the ad, or run a local transcription (for example whisper ADS_DIR/FILE --model small --output_format vtt --output_dir transcripts). Uploader captions beat automatic ones; automatic captions mishear numbers, so check each number against the audio when it decides a row.
- For each spoken_claim window, read the transcript lines inside it and copy the sentence that states the number. Then read the summary segments around it (vivu_get_video_summary with include_segments true, start_ms and end_ms around the window) to confirm the window is about the same thing. Vivu's reason text is a paraphrase, not a transcript.
- Search the transcript itself for spoken numbers the search did not return (digits, number words, "percent", "million", "dollars").
In our test run the spoken_claim search missed the veterans ad's line about the wait for care, while the video summary of that ad mentioned it; the transcript search in item 3 is what catches such lines. A summary also restated the narrator's change in points as a percentage, which is why the queue quotes the transcript. Local transcription was not exercised in our test run: the synthetic narration script stood in for the transcript.
Done when every ad has a transcript and every spoken number in it is either in the queue or ruled out (a phone number, a year in a date).
Step 9: Write the queue
Goal: one row per claim, each with its source line and the ad's sponsor line, ready for the reporter.
- One row per on-screen claim (kind on_screen) and per spoken number (kind spoken). sponsor_from_frame is the paid for by line read from that ad's end card, repeated on every row of the ad, or NO SPONSOR LINE FOUND.
- Show the user the field mapping and the first rows, including one UNREADABLE or NO CITATION row if there is one, before writing the full queue:
ad_file,origin,sponsor_from_frame,on_screen_start,on_screen_end,kind,claim_text,citation_from_frame,frame,status,verdict
RIDGEFIELD_TAXES_30_v2.mp4,ADS_DIR,"Paid for by Citizens for Fair Taxes Ridgefield. Not authorized by any candidate or candidate's committee.",00:13,00:17,on_screen,"$480,000 FOR A PARKING STUDY","County Audit Report 24-117, p. 12 / Ridgefield Courier, June 9, 2025",frames/RIDGEFIELD_TAXES_30_v2_15.5.png,READ,
| Field | Source | If unavailable |
|---|---|---|
| ad_file, origin | ads.tsv (the user's own link, not a Vivu link) | none |
| sponsor_from_frame | full frame of the end card (Step 6 or 7) | NO SPONSOR LINE FOUND |
| on_screen_start, on_screen_end | first and last tile showing the card, or the transcript times for spoken rows | the Vivu window, labeled NOT VERIFIED |
| claim_text | full frame for on_screen rows; transcript sentence for spoken rows | UNREADABLE |
| citation_from_frame | full frame or enlarged crop, lines joined with " / " | UNREADABLE, or NO CITATION ON SCREEN |
| status | READ, UNREADABLE or NOT VERIFIED | NOT VERIFIED |
| verdict | left blank for the reporter | blank |
- Write claim_queue.csv. Report the counts plainly: claims, spoken numbers, rows with an unreadable or missing source, and false windows per search. If an ad has no claims, say so; do not pad the queue.
Done when the user has approved the sample rows and claim_queue.csv exists with one row per claim.
Step 10: Hand it to the desk
Goal: the reporter and editor have the queue.
- 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.
Ad claim queue, RACE, N ads (DATE)
M on-screen claims, K spoken numbers to check. Sources to pull:
- AD_FILE MM:SS "CLAIM" (source on screen: "CITATION")
Unreadable or missing source: LIST or none. Sponsors: SPONSOR LIST.
Full queue: claim_queue.csv. Verdicts are the desk's call; this list only records what each ad shows and says.
- Use file names, the user's own links 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
- Campaign ads are public, but downloading them may conflict with the platform's terms of service. Use them for internal checking only, do not republish the files, and have the user confirm with their editor before Step 2 that this use (and any quoting of the ads in coverage, under the newsroom's fair use policy) is fine.
- Run the same searches on every ad in the batch and do not filter by party or candidate. Confirm the list of ads with the user before Step 4 so the batch is complete.
- Neither Vivu nor Claude decides whether a claim is true; the verdict column stays empty for the reporter.
- The sponsor comes only from the paid for by text on screen. The skill does not recognize faces, voices or logos and does not infer who funds a group.
- People who appear in ads (actors, residents, children) are not identified. Ads that show minors are processed for on-screen text only.
- The ads stay in the user's Vivu project until they delete them. Create the project private (the default is visible to the whole organization) and confirm before Step 4.
- Posting the queue anywhere acts as the user and needs approval in Step 10.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| the start, middle and end frames of a claim window show no card (observed: "three-frame strip shows no claim card") | the window is several times longer than a card and can hold more than one card with b-roll between them | read the Step 6 sheet of the whole window |
| one window holds more than one claim card and the reason mentions only one (observed: "reason names only the first") | Vivu returns one window per run of cards | read every card and source line in the window from frames; never copy the reason |
| a card starts before the returned window (observed: "before the window") | window edges do not line up with the card | take on_screen_start from the Step 7 sheet |
| the source line on a low resolution ad cannot be read (observed: "UNREADABLE") | small type in a small file | mark UNREADABLE and check the original upload or a higher resolution copy |
| the reason names a source detail the frame does not show (observed: "the analysis year could not be confirmed from the frame") | the reason is a description, not a reading | quote only what the frame shows |
| the spoken search misses a number the narrator says (observed: 1 missed) | search recall is not complete for short ads | the transcript search in Step 8 |
| ffmpeg stops with "Overwrite? [y/N] Not overwriting - exiting" (observed) | the output file already exists and -y is missing | add -y, as in the commands above |
| yt-dlp warns "Some web_embedded client https formats have been skipped" and saves a low resolution file (observed) | YouTube limits the formats it serves to that client | keep the file, mark unreadable source lines, and ask the campaign or the station for a broadcast copy |
| "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 ads.tsv | Vivu replaced spaces and punctuation with underscores | match on the normalized name or the YouTube ID |
| "Sign in to confirm you're not a bot" during download | download attempted from a cloud IP | run Step 2 on the user's own machine |
| an empty claim_card result for an ad that clearly has cards | Vivu's recall is not complete and an empty result does not prove the ad has none | the Step 7 sweep reads every ad regardless |