Archival newsreel sourcing log

---
name: archival-newsreel-sourcing-log
description: "Turn newsreels you downloaded and your script into a sourcing log with Vivu: title card text, timecodes, footage after each card, rights as stated. Use when sourcing archive film for a history video."
---

Archival newsreel sourcing log with Vivu

This skill takes the newsreel or documentary reels a history creator has already downloaded from an archive that states its reuse terms, plus the script of the video, and returns a sourcing log: for every script beat, the reel and minute where the matching story starts, the title card text read from the frame, what the footage after the card shows, whether a logo or watermark is on screen, and the rights statement copied from the source page. Claude measures the reels, prices them against the user's Vivu plan, indexes them in a private Vivu project, runs one search per script beat, checks every result in frames from the user's own file, and writes sourcing_log.csv with an empty "use" column for the creator. Nothing is edited, downloaded or published by the skill.

The value is in what only the film shows. An archive catalog lists a reel by volume, release and date, and at best reproduces the original release sheet, a typed list of stories. The sheet gives no timecodes, lists stories the surviving copy no longer has, and words them differently from the card on screen. Silent reels have no transcript at all: the story titles are painted on intertitle cards, and whether a logo or watermark sits on the picture is only visible in the picture. Every row of the log says whether Claude checked it in frames, and card text always comes from a frame, never from Vivu's reason text.

When to use

Use when a creator says "I downloaded these newsreels, find the footage for each part of my script", "which reel has the Bonneville Dam story and where", "make me a source log with timecodes for my credits", or "read the title cards in these reels for me". It fits 6 to 10 reels of 5 to 10 minutes each, black and white, with title cards and sometimes narration.

Not for:

• Finding footage on archive websites. Vivu searches only files the user uploaded; the user picks and downloads reels from the archive's catalog first.
• Clips from other people's YouTube channels. Archive film re-uploaded by a channel often has unclear rights; the skill does not import YouTube links.
• Deciding whether a reel is public domain. The skill copies what the source says; the creator decides.
• Naming the people in a shot. The skill copies names printed on cards and nothing else.
• One quick question about one reel. Open it, or search the Vivu project directly.

Working principles

1. Report measured numbers, not estimates. When a number is an estimate, say so.
2. A search result is a candidate until Claude has looked at frames from the user's file inside the result window. Only checked rows are marked checked.
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: the reel list and the cost (before upload), and the beats with their search wording (before searching).
5. Card text is read from a full frame. Vivu's reason text is a paraphrase and can add words the card does not have, such as a city or year taken from the search.
6. Rights are copied from the source page word for word into rights_as_stated. Claude never writes "public domain" unless the source says it.

What you need before starting

The skill runs in Claude Code on the computer that holds the reels (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 video project; 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.

Inputs to collect

Ask for anything missing, most important first.

1. The script (required). One beat per line is best; Claude numbers the beats.
2. The reel folder and each reel's source page (required).
3. Which reels to include. Default: all of them if the total fits what is left of the plan this month; otherwise the reels whose release sheets mention the script's events (Step 3).
4. Whether any reel has narration. Default: check in Step 7 by listening points the user confirms.
5. The Vivu project name. Default: "Sourcing VIDEO_TITLE", private.

Files and state

Keep the working files next to the reels, in their own folder:

sourcing-log/
  config.json         reel folder, project_id, script file, beats and their search wording
  reels.csv           file, duration_s, bytes, source_url, rights_as_stated, release_sheet_stories, uploaded_name, video_id
  results/            raw result of each beat search without its result page link, one JSON file per beat
  frames/             strips, contact sheets and card frames Claude checked
  asr/                audio cuts and transcripts for narration quotes (Step 7, optional)
  sourcing_log.csv    one row per checked story (Step 8)
  coverage.md         beats with no checked row, rejected results and what the frames showed
  state.json          uploaded files with video_id, searches run with job_id, rows checked

A rerun reads state.json first and skips what is done: reels already in the project, beats already searched, rows already checked. When the user adds reels later, only the new reels are uploaded; beat searches run again because a search covers the whole project, and checked rows 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.

1. 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.
2. Run ffmpeg -version and ffprobe -version. Without them the reels cannot be measured or checked; stop and say so.
3. List the reel folder and read the script. If the script has no clear beats, ask the user to mark them rather than guessing.

Done when vivu_get_account shows can_create_projects: true, ffmpeg and ffprobe answer, and the script and reel folder are in hand.

Step 2: List the reels and their rights as stated

Goal: reels.csv with one row per reel, its length, its source page and the rights text copied from that page.

1. For each file (FILE), measure the length:

ffprobe -v error -show_entries format=duration -of csv=p=0 "FILE"

2. Open each reel's source page. Copy into rights_as_stated the page's own words about reuse (a license line, a rights statement, "no known restrictions", or "no license statement on the page"). Do not summarize it into "public domain". If the page shows the original release sheet or story list, copy the story titles into release_sheet_stories: they help write the search wording, but they are not proof of what the copy contains.
3. Tell the user which reels have no reuse statement at all. Those can still be searched for research, but the creator decides before any of their footage goes into the video.

Release sheets and surviving copies often disagree. Item names that list story numbers (for example s1_3-9) mean some stories were cut from the copy, and the card on screen may be worded differently from the sheet, so the log records the card text from the frame.

Done when reels.csv has duration_s, source_url and rights_as_stated for every reel and the user has confirmed the list.

Step 3: Size the job and get approval

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

1. Sum duration_s to minutes.
2. Searches: one precise search per script beat, plus one per beat that needs a narration check (Step 7). A precise search uses 5 credits in total. As an estimate, 6 beats with 3 narration checks is 45 credits; label the credit figure as an estimate.
3. 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. As an estimate, 8 reels of about 8 minutes fit Premium, while Free covers only two or three reels.
4. Show one table:

5. If it does not fit, offer these levers in order: index only the reels whose release sheets mention the script's events; drop reels the user already knows they will not use; split the beats into two sessions; move to a larger plan. Name every reel 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 reel list and the cost table.

Step 4: Upload and index

Goal: every approved reel is ready in one private Vivu project and matched to its row in reels.csv.

1. Call vivu_list_projects. Reuse this video'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.
2. 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.
3. Give the link to the user to open in their own browser and select the reels (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; archive transfers are usually far larger, so they go through the user's browser or the Vivu web app. Never split, trim or recompress a reel to fit.
4. Poll vivu_list_videos about every 30 seconds until every reel shows status ready. Vivu replaces spaces and brackets in file names with underscores; match each video back to reels.csv by the normalized name and by duration_ms against duration_s, and write video_id into reels.csv and state.json.

The upload through the user's own browser was not exercised in our test run; the test reels reached Vivu through a different upload path. In our test run all 6 reels (42.8 minutes) were ready about 7 minutes after the upload began.

Done when vivu_list_videos shows every reel as ready and every row of reels.csv has a video_id.

Step 5: Search each script beat

Goal: one search per beat that lands on the story's title card and the footage after it.

1. Write one query per beat that names what the card would announce and what the footage would show, in plain words: "a newsreel title card about engineers closing the gates of the Bonneville power dam, followed by footage of the dam and spillway". Use the release sheet wording as a hint for the event and the place, but do not paste the sheet's headline: the card may say something else.
2. Show the user the numbered beats and their wording, and wait for approval.
3. Run each beat with vivu_search_videos (project_id, query, mode "precise", maximum_results 5). 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. 5 is enough because one event rarely appears in more than a couple of stories across a batch of reels, and a small ceiling keeps wrong stories visible instead of burying them; raise it for a beat that returns exactly 5.
4. 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/BEAT.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.

The chain: the card search finds the story on screen; frames from the user's file confirm the card and describe the footage after it; for sound reels the spoken detail search and a local transcript turn "shown on the card" into "said on the soundtrack".

Done when every approved beat has a results file.

Step 6: Check every result in frames

Goal: for every result, the card text read from a full frame, the footage after the card described, and a watermark check.

1. For every result, extract a strip of three frames at the start, middle and end of the window (FILE is the reel, START, MID and END are seconds inside the window, BEAT and NAME 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 sourcing-log/frames/BEAT_NAME_strip.png

2. Look at the strip. A result counts only when the window holds a card about the beat's event or footage that the card introduces. Windows usually include the card and the whole story, and often start a second or two early on the previous story and end on the next story's card, so find the card itself with a half second contact sheet over the window (LENGTH is the window length in seconds):

ffmpeg -v error -ss START -t LENGTH -i "FILE" -vf "fps=2,scale=320:-2,tile=6x6" -fps_mode vfr "sourcing-log/frames/BEAT_NAME_sheet_%02d.png"

Tile K of sheet P (both counted from 1) is at START + ((P - 1) x 36 + K - 1) / 2 seconds. 3. Extract one full frame in the middle of the card and read the card from it, every line including the dateline, sub-titles and any narrator credit:

ffmpeg -v error -ss CARD_SECONDS -i "FILE" -frames:v 1 -q:v 3 sourcing-log/frames/BEAT_NAME_card.png

Copy the text exactly, with the card's own spelling and punctuation. If a word is not legible, write it as [illegible] rather than filling it in from the reason or the release sheet. 4. From the sheet, describe the footage after the card in plain words (what is in the picture, not who): "spillway gates, workers in a cage on a cable over the rapids". Vivu's search by what a picture shows is rated weak in general, so this description comes from frames only. 5. Look for a logo, a watermark or a burned in time code on the story's frames and note it in watermark_or_logo. Archive transfers often start with the archive's own slate; note it, and say whether it appears inside the story. 6. Results the frames reject go into coverage.md with the reason text and what the frames showed, and are counted as false positives. A beat with no checked result is listed in coverage.md too: an empty result does not prove the reels have no such story. 7. Report to the user per beat: results returned, rows kept, false positives, and beats left uncovered.

Worked example from our test run

The test corpus was 6 public reels of a U.S. newsreel series from the years before the Second World War (42.8 minutes), digitized by a national archive and posted on a public archive site whose item pages carry no license line; the rights column recorded exactly that. The early reels have plain silent style intertitles with sub-titles, the later ones decorative cards printed over drawings and a narrator credit. Truth was written from contact sheets before any search: one card per script beat, plus look alike cards (a forest fire card next to the White House fire beat, a visit by Mexico's president-elect next to a Mexican land reform beat) and a control place name that no reel contains.

In our test run the title card searches (one per beat) returned 6 results, 6 real and 0 false, and 0 cards were missed; neither look alike card was returned, and the control place returned nothing. Windows were 33 to 64 seconds long, each covering the card and the story; most started on the previous story and several ended on the next story's card. The reason text quoted most cards correctly, paraphrased the Bonneville card, and said the Olympics card introduces the "Berlin Olympics" and added the year, although that card names no city and no year. Every card, decorative ones included, was legible in a full frame without zooming.

This is one small corpus of clean transfers from one newsreel series; scratched prints, faded or flickering cards and other series were not tested, and a real batch of reels on one topic will have more look alike stories per beat than this.

Done when every result has been judged from frames and the user has seen the per beat counts.

Step 7: Narration and speech (sound reels only)

Goal: for a beat whose script needs a spoken line, the exact words, or a clear statement that they were not found.

1. Run the spoken detail query from the table in Step 5 for that beat. Word it by what was said, not the exact words.
2. In our test run, searches for details only the narration would carry (the cost of a dam, an athlete's name, how long a road treatment lasts) returned no results, while a search for a line spoken on camera in a sync sound speech returned the right moment. Whether those reels' narration says those details was not checked. So treat an empty spoken detail search as "not found", never as "not said", and use the checked story window from Step 6 instead.
3. For an exact quote, cut the audio of the checked story window and transcribe it locally (BEAT is the beat name; START and LENGTH come from Step 6):

ffmpeg -v error -ss START -t LENGTH -i "FILE" -vn -ac 1 -ar 16000 sourcing-log/asr/BEAT.wav
whisper sourcing-log/asr/BEAT.wav --model small --language en --output_format srt --output_dir sourcing-log/asr

Copy the line from the transcript into narration_quote, and have the user listen once before it goes into the video. Local transcription was not exercised in our test run. Without a transcription tool, narration_quote stays NOT TRANSCRIBED; the reason text is a paraphrase and is never used as a quote.

Done when every beat that needs a spoken line has a quote from a transcript, or NOT TRANSCRIBED, or "not found" in coverage.md.

Step 8: Write the sourcing log

Goal: sourcing_log.csv the creator can edit, credit and fact check from.

1. Write one row per checked story, beats in script order:

beat,reel_file,source_url,rights_as_stated,window_mmss,card_mmss,card_text_from_frame,narration_quote,picture_after_card,frame_path,watermark_or_logo,verified,use
B5,REEL_FILE.mp4,SOURCE_URL,"RIGHTS TEXT FROM THE SOURCE PAGE",02:13-03:06,02:14-02:20,"BONNEVILLE, WASH. / ENGINEERS CLOSE HUGE WATER GATES AT BIG POWER DAM / NARRATOR CREDIT AS PRINTED",NOT TRANSCRIBED,"spillway gates, workers in a cage on a cable",frames/B5_REEL_card.png,"none inside the story",yes,

REEL_FILE is the user's own file name; SOURCE_URL and RIGHTS TEXT come from reels.csv. NARRATOR CREDIT AS PRINTED stands for the credit line exactly as the card shows it; card lines are separated by " / ". card_mmss is where the card is on screen in the contact sheet, not the window start. verified is yes only when Claude read the card in a frame and looked at the footage after it. use is left empty for the creator. 2. Show the user the first rows and the field mapping, and wait for a yes before writing the rest:

3. Write coverage.md: beats without a checked row, rejected results with what the frames showed, and stories on a release sheet that the copy does not contain.
4. Tell the user how to find a row again: the reel name and card_mmss are enough in any editor. The Vivu result page link from Step 5 works for four hours and is not stored.

In our test run the log had one checked row for each of the six beats, with card text read from frames and the narration column NOT TRANSCRIBED.

Done when sourcing_log.csv and coverage.md exist and the user has seen the counts of rows, rejected results and uncovered beats.

Compliance

1. Reuse rights. Use only reels from a source that states its reuse terms, and copy those terms per reel. The skill does not judge whether footage is public domain, does not remove logos or watermarks, and does not import clips from other people's YouTube channels. Ask before Step 4.
2. People on camera. People in the footage are described, not identified; names are copied only from what a card prints. No face recognition, and no attempt to identify anyone, children in historical footage included. If the user asks to add their own family films of living people, ask whether those filmed (or a parent or guardian for minors) agreed, and leave them out otherwise.
3. Sensitive footage. Newsreels include war, riots and the dead. Tell the user before Step 6 when a beat's reels contain such stories, and remind them that YouTube's policies on violent and graphic content apply to historical footage too; age restriction or context may be needed.
4. Facts and wording. Cards are the newsreel's claims at the time, sometimes wrong and sometimes in offensive period language. The log quotes them as printed; the creator checks the facts against other sources before using them in narration.
5. Where the videos go. The reels 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