---
name: eyewitness-location-clue-sheet
description: "Pull readable location clues (street signs, shop signs, bus stops, landmarks) out of eyewitness phone clips with Vivu into a CSV a verification desk checks against maps. Use for breaking news."
---Eyewitness location clue sheet
This skill takes the phone videos a newsroom has received or downloaded for one breaking story (a storm, a fire, a flood: usually 10 to 20 clips of 20 seconds to 3 minutes, already logged with their source and usage rights) and returns a location clue sheet: one CSV row per clue, with the source file, the minute and second, the clue type (street sign, shop or building sign, bus or tram stop, landmark), the text as Claude read it from a full frame (or NOT LEGIBLE), the path of that frame, and an empty column for the verifier's map check. Clue types a clip does not show are listed in a separate "not found" file. Claude measures the clips, prices the indexing against the user's Vivu plan, indexes them in a private Vivu project, runs one precise search per clue type, checks every returned window on a sheet of frames taken every half second, reads each clue from the sharpest full frame, scans the clips that returned nothing, and writes the sheet.
The value is in what only the picture shows. A submission says "downtown" or "outside my building", social platforms strip location metadata, and nobody reads street signs aloud while filming. The street name blade, the shop awning, the bus stop flag and the tower on the skyline pass in a second or two of shaky footage, and no transcript or caption has them. Vivu narrows each clip to a few seconds; the frames, not Vivu, decide what a sign says, and the verifier, not Claude, decides where the clip was filmed.
When to use
Use when a verification producer, open source investigator or social news editor says "find anything in these clips that tells us where they were filmed", "pull the street signs and shop names from the storm videos", "build a geolocation clue sheet for these eyewitness clips", or "which of these submissions show a readable street name". For one clip, open it and look, or ask Vivu directly. This skill does not decide where a clip was filmed, does not judge whether a clip is real, edited or recycled, does not identify the person filming or anyone on camera, and does not download clips from social platforms; the newsroom's own verification process covers those.
Working principles
- Report measured numbers, not estimates. When a number is an estimate, say so.
- Vivu's results are candidates. A row is written only after Claude has looked at the frames of the window. Every word in the sheet comes from a full frame, never from Vivu's reason text, which can name streets and shops that are not on screen.
- Stop and tell the user when a required capability or file is missing (no ffmpeg, no write access in Vivu, no record of usage rights). Do not guess around it.
- Ask the user before anything that is expensive to redo or that acts on their behalf: the indexing cost before upload, and the sample rows before the full sheet.
- Clues, not people. Faces, voices and the person filming are never described or matched. Frames showing injured or dead people are not exported and get no row.
What you need before starting
Check each item at the start of the run and tell the user plainly what is missing.
| 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). A write call failing with "has not granted vivu.write" means the connection is read only; the user reconnects Vivu and allows write access |
| A shell with ffmpeg and ffprobe on the machine that holds the clips | measure minutes, extract frames to read the signs | ffmpeg -version and ffprobe -version |
| The clips as local files in one folder | frames come from the local files; Vivu has no export tool | ls CLIP_FOLDER |
| A source and rights log for the clips | third party footage may only be used as its terms allow | the user confirms each clip has a logged source and permission, or names the ones that do not |
| A browser that can open the Vivu upload page | the connector has no direct upload tool | the user opens the link, or Claude in Chrome is connected |
The skill needs a shell and local files, so it runs in Claude Code on the user's computer (terminal or the Code tab of Claude Desktop). It downloads nothing, so no residential IP is needed. Nothing is scheduled and nothing is written outside the working folder.
Inputs to collect
Ask for anything missing, most important first.
- The folder with this story's clips (CLIP_FOLDER). Required.
- The rights status of each clip. Required; clips without a logged permission are left out until the user says otherwise.
- Which clue types to look for. Default: all four (street_sign, shop_sign, transit_stop, landmark).
- The Vivu project name. Default: "Verification STORY_NAME", private.
Files and state
Keep everything in one working folder next to the clips:
clue-sheet/
clips.csv file, minutes, rights status, video id
results/ raw search results, one JSON file per search
frames/ half second sheets, whole clip scans, and the full frames each clue was read from
location_clues.csv one row per clue, with an empty verifier_map_check column
not_found.txt clip and clue type pairs with nothing confirmed, to look at by hand
state.json uploaded files and video ids, searches with job ids, every window with its verdict, rows written
state.json is updated after every step. A rerun reads it first: files already uploaded are not uploaded again, searches already run are not rerun, and windows already checked keep their verdicts, so an interrupted run resumes where it stopped. A clip added later is matched by video id, and only its rows are added, so the same clue is never written twice.
Step 1: Check the Vivu connector and the setup
Goal: every row of What you need is confirmed before anything is uploaded.
- 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 not true, or a write call later fails with "has not granted vivu.write", ask the user to reconnect Vivu with write access and stop until they have.
- Run ffmpeg -version and ffprobe -version.
- List CLIP_FOLDER and create the working folders; ffmpeg does not create an output folder:
mkdir -p clue-sheet/results clue-sheet/frames
Run every later command from inside clue-sheet/ (cd clue-sheet), with CLIP_FOLDER given as a full path.
Done when vivu_get_account shows can_create_projects: true, ffmpeg and ffprobe print versions, and the working folders exist.
Step 2: Check rights and price the indexing
Goal: only cleared clips go in, and the user sees the cost before anything is uploaded.
- Ask Compliance items 1 to 3 first and mark each clip's rights status in clips.csv.
- Measure each cleared clip and sum the minutes. ffprobe takes one input file per call, so run it once per file (CLIP_FILE is a file in CLIP_FOLDER):
ffprobe -v error -show_entries format=duration -of csv=p=0 CLIP_FOLDER/CLIP_FILE
- Call vivu_get_usage for the plan and what remains this month.
- Estimate search credits: one precise search per clue type, and a precise search uses 5 credits in total, so as an estimate 20 credits per story for four types, plus 5 for each rerun after raising maximum_results.
- Show one table and wait for approval:
| This story | Remaining on the plan | |
|---|---|---|
| Index minutes | measured sum | from vivu_get_usage |
| Search credits | estimate | from vivu_get_usage |
For reference, the Free plan has 20 index minutes a month and 50 search credits a month; Premium is $30 a month with 180 index minutes and 500 search credits. As an estimate, 15 clips of a minute and a half are about 23 minutes, which is more than Free and fits Premium several times a month. If a story does not fit, offer these levers in order: index only the clips whose location is in question (skip clips already located by the sender's own photos or a reliable caption), trim nothing but leave out duplicates of the same scene, and only then a larger plan. Never drop a clip the user asked for without saying so.
In our test run the account was an admin account whose vivu_get_usage shows no remaining allowance, so the comparison against a real plan and the approval were not exercised in our test run.
Done when every clip has a rights status and the user has approved the minutes and the credit estimate.
Step 3: Upload and index
Goal: every cleared clip is ready in a private Vivu project.
- Call vivu_list_projects and reuse the project named in the inputs if it exists. Otherwise call vivu_create_project with that name and visibility "private". Eyewitness clips show bystanders and sometimes victims; the default visibility is the whole organization.
- Call vivu_open_upload_page with the project ID right before the upload. The link expires in 180 seconds and is a sign in link, so never paste it into a message or file. Give it to the user to open in their own browser and choose the files, or attach them with a browser tool that can upload local files. Claude in Chrome accepts at most 10 MB per upload call, and many phone clips are larger; the user adds those in the Vivu web app. Never split or recompress a clip to fit.
- Poll vivu_list_videos about every 30 seconds until every file shows ready. Match each video back to clips.csv by file name; Vivu turns spaces and brackets in names into "_", so compare names with those characters replaced. Record the video IDs in state.json and clips.csv.
The upload was not exercised in our test run: the test clips were already indexed in an earlier project, so neither the upload page nor the time to ready was measured.
Done when vivu_list_videos shows every cleared file in clips.csv as ready.
Step 4: Search each clue type
Goal: a list of windows per clue type, plus a list of clips with no window.
One precise search per clue type covers the whole project:
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| street_sign | a street corner where a street name sign is close enough to read: the words of a street, road or avenue name are legible on a flat rectangular sign on a pole or building corner. Return a moment only if the street name lettering itself can be seen; a bare pole, a warning diamond, a pedestrian or parking sign, a shop sign or a sign too small to read does not count | precise | 30 |
| shop_sign | a shop or restaurant name sign on a storefront or awning above street level, or a building number on a door or wall, large enough to read; posters, sandwich boards and writing on vehicles do not count | precise | 40 |
| transit_stop | a bus stop or tram stop sign or shelter with route numbers or a stop name, or a subway or train station entrance sign | precise | 20 |
| landmark | a distinctive tall landmark building, tower, monument or bridge visible in the distance or nearby, the kind that could identify the city or neighborhood | precise | 20 |
- Run each row with vivu_search_videos (project_id, query, mode "precise", maximum_results as in the table). It 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 each result as results/FIELD.json. Show the result page link in the live reply only; it expires after four hours, so it never goes into the sheet or any file.
- maximum_results is also the ceiling on what comes back. Street and shop signs can appear several times per clip, so street_sign gets about two per clip and shop_sign about three (up to 100); when a list stops at exactly that number, raise it and rerun.
- Describe clues by kind, size and place, never by a street or shop name you expect. A query that names a street invites the reason text to repeat that name for whatever sign is in the window.
- Write each window into state.json as a candidate and list the clips with no window per type. Those go to Step 6.
Why this chain: each search turns minutes of shaky walking into windows of a few seconds; the half second sheets in Step 5 find the sign inside the window and give a frame sharp enough to read; the scan in Step 6 covers what the searches did not return, so "not found" means somebody looked. Eyewitness speech ("this is downtown") is not a location clue anyone can check against a map, so no speech search is run and the chain stays on what is shown on screen.
Done when results/ has one JSON file per clue type searched and every window is in state.json.
Step 5: Check each window and read the clue
Goal: every window is confirmed or rejected against frames, and every confirmed clue has its text read from a full frame.
Vivu returns a time range that contains the sign, not the exact second, and reading signs in real street footage is a weak capability: the search can return a window with no sign in it, and the reason text can name a street or a shop that the frames do not show. So frames decide, never the search alone.
- Make a sheet of one frame every half second across the window (START is start_ms / 1000, DURATION is (end_ms - start_ms) / 1000; CLIP is the file name without extension, FIELD the clue type, HIT is h plus the window's number; the 8x5 grid holds 20 seconds, so for a longer window raise the second number):
ffmpeg -v error -ss START -t DURATION -i CLIP_FOLDER/CLIP_FILE -vf "fps=2,scale=320:-2,tile=8x5" -frames:v 1 frames/CLIP_FIELD_HIT_sheet.png
Keep the quotes around the filter. Look at the sheet. Reject the window if no cell shows a clue of that type: parking and pay signs, warning signs, posters, sandwich boards and lettering on vans and taxis do not count. 2. If a cell shows injured or dead people, skip the window, write "skipped: casualty footage" in not_found.txt, and extract nothing more from it. 3. On the sheet, pick the cell where the clue is largest and least blurred. Extract that moment at full resolution (SECONDS is the window start plus half the cell's index):
ffmpeg -v error -ss SECONDS -i CLIP_FOLDER/CLIP_FILE -frames:v 1 -q:v 3 frames/CLIP_FIELD_HIT_read.png
- Read the text exactly as printed. Write it only when every character is readable. When distance, blur or the sun hides characters, try the neighboring cells once; if it is still not certain, write the readable part with ? for each unread character, or NOT LEGIBLE. A street blade too small to read is still worth a row (NOT LEGIBLE): it tells the verifier where to look in the clip. Never fill a name from the reason text or from what the street "should" be.
- A landmark row says what is visible ("multi arch viaduct across a park"), not which building it is. Naming it is the verifier's call.
- Rejected windows stay in results/ and state.json with the reason; they are counted, not dropped silently.
Worked example from our test run
In our test run we used a test corpus of 10 public videos, 17.77 minutes in total: Creative Commons first person street footage (walks in New York, scooter rides in Australian cities, a snowy pedestrian street in Istanbul, a snowy supermarket car park and bus loop near Vancouver, a rainy downtown in Miami at low resolution, and a TV b-roll clip), sound removed. They are not breaking news submissions: only the snow and rain clips show weather, they are horizontal rather than vertical, and several clips are suburban paths with almost no readable clue. The clips were already indexed from an earlier project, so 0 index minutes were used. Before searching we wrote down every street sign, shop sign and bus stop we could see on sheets with a frame for every second, then checked doubtful ones on full frames. After the searches we added events we had missed on those sheets (a St Johns Rd blade, a neon burger chain sign and a blade too small to read), checked on full frames; the miss counts below include them.
The street_sign query in the table is the final wording, after 2 rewordings on the same corpus. The first wording returned 10 windows, 6 real and 4 false: empty suburban stretches and a parking sign that the reason text called "A blue rectangular street name sign". The second wording returned 10 windows, again 6 real and 4 false; one of the false windows was now a yellow warning diamond that the reason called a green street name blade. The final wording, which asks for lettering that can be read, returned 4 windows, 4 real, 0 false and 2 missed: it found PARK AV and Madison Ave, plus two blades too small to read, and lost a second Madison Ave corner and a St Johns Rd sign that the first wording had found. Street windows had a median of 8.5 seconds. Its reason text claimed signs for "Park Avenue and East 36th Street" where the frame shows PARK AV and a Lincoln Tunnel sign only.
The shop_sign search returned 10 windows: 9 real, 1 false and 8 missed shop sign moments. The false window came well after the signs its reason listed, and the reason misread a nail salon's name. It also called a restaurant "Ruby Chinese Restaurant" where the frame shows a name ending in ONG. Writing on delivery trucks and taxis never came back. Every shop sign moment in the Istanbul clip was missed, and the whole clip scan in the next step found them. Shop windows had a median of 16.5 seconds. The transit_stop search returned 3 windows, all 3 real; route numbers were too small to read. The landmark search returned 7 windows, each showing a tower or bridge, but we did not check the building names its reason gave. A control search for a subway entrance, which none of the clips show, returned 0 windows.
Done when every window in state.json has a verdict and every confirmed clue has a read frame in frames/.
Step 6: Scan the clips with nothing confirmed
Goal: every clip and clue type without a confirmed row is either found by a scan or listed in not_found.txt.
- For each clip with no confirmed row for some clue type, make sheets of the whole clip at one frame per second (each 6x5 sheet holds 30 seconds; the %d makes one numbered sheet per 30 seconds):
ffmpeg -v error -i CLIP_FOLDER/CLIP_FILE -vf "fps=1,scale=400:-2,tile=6x5" frames/CLIP_scan_%d.png
- If a cell shows a clue, go back to Step 5 with a window around that second. Otherwise add the clip and type to not_found.txt as "not found, look by hand", with what the clip shows instead (for example "suburban path, only traffic signs").
- Tell the user which clips are on the list. An empty result does not prove a clue is absent: at 400 pixels per cell a small street blade can be missed, so a clip that matters gets a look by hand at full size.
In our test run these scans found the Istanbul shop signs and a house number on a gate pillar that no search returned, and missed the St Johns Rd blade, which was too small on the scan sheet.
Done when every clip and clue type pair has a confirmed row in the sheet or a line in not_found.txt.
Step 7: Assemble the clue sheet and confirm the sample
Goal: one table the verifier can work through clip by clip.
- Build one row per confirmed clue:
source_file,mm_ss,clue_type,text_read,frame_path,verifier_map_check
IMG_4471.mp4,01:28,street_sign,"PARK AV",frames/IMG_4471_street_sign_h1_read.png,
IMG_4480.mp4,00:43,shop_sign,"?ONG CHINESE RESTAURANT",frames/IMG_4480_shop_sign_h3_read.png,
- Field mapping:
| Field | Source | If unavailable |
|---|---|---|
| source_file | the original file name in clips.csv | none |
| mm_ss | the second of the read frame | none |
| clue_type | street_sign, shop_sign, transit_stop or landmark | none |
| text_read | text read from the full frame, as printed; for a landmark, what is visible | partly legible with ? for unread characters, or NOT LEGIBLE |
| frame_path | the read frame | none |
| verifier_map_check | left empty for the verifier | blank |
- Show two or three sample rows, the mapping and not_found.txt, and wait for a yes before writing the full table. Say plainly that every text_read value is Claude's reading of a frame and is NOT VERIFIED against a map; the verifier opens frame_path before relying on it.
- Write location_clues.csv and not_found.txt, and give the user the counts: clips checked, windows returned and rejected per type (with the reason for each), clues confirmed, NOT LEGIBLE rows, and not found pairs.
In our test run the sheet and the not found list were written from the checked windows and the scans; the user's approval of the sample rows was not exercised in our test run.
Done when location_clues.csv and not_found.txt exist and the user has approved the sample rows.
Compliance
- Use only clips whose source and usage rights are logged (a submission agreement, the filmer's permission, or the platform's terms for the intended use). Ask before Step 2; clips without a logged permission stay out until the user decides.
- Ask before Step 3 whether newsroom policy allows uploading third party clips to a third party service. Create the Vivu project as private (the default visibility is the whole organization). The clips stay in the user's Vivu project until the user deletes them; the skill never calls vivu_delete_video or vivu_delete_project unless the user asks, and confirms first.
- Clips can show injured or dead people. Those frames are not extracted beyond the review sheet, get no row and are not exported.
- Bystanders, including children, can be on screen. They are never a subject of the sheet and nothing about them is recorded.
- No face, voice, logo or identity recognition, and no judgment on whether a clip is authentic or who filmed it. Vivu only finds when a kind of sign or structure is on screen; the text is read by Claude from frames extracted by the user's own ffmpeg, and the location conclusion belongs to the verifier.
- The skill sends nothing to anyone. The verifier works from the sheet.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) a street_sign window shows only fences, hedges or a bare pole | the search fills quiet suburban clips with candidate signs | reject on the half second sheet; the final wording asks for readable lettering, which cut these windows in our test run |
| (observed) the reason says "A blue rectangular street name sign" and the frame shows a parking pay sign | the search counts any small blue sign on a pole | read the sign on the full frame before writing a row |
| (observed) the reason claims signs for "Park Avenue and East 36th Street" but the frame shows only one of them | the reason text adds street names that are not on screen | copy names from the frame only; never from the reason |
| (observed) the reason names "Ruby Chinese Restaurant" while the frame shows a different, partly hidden name | the reason text guesses unreadable words | write the readable part with ? marks |
| (observed) a shop_sign window comes after the signs its reason lists | the window and the reason disagree on timing | check the sheet; if the sign is just outside, make a new window around it |
| (observed) a city clip with several shop signs gets no shop window | signs a handheld camera passes quickly can be missed | run the Step 6 scan for every clip and type without a confirmed row |
| (observed) the readable wording loses a street sign that a looser wording found | asking for legible text trades recall for precision | scan clips that matter by hand; a missing row is not proof of no sign |
| a list stops at exactly maximum_results | the cap cut the list short | raise maximum_results and rerun |
| a landmark row names the wrong building | the reason names buildings from general knowledge | describe what is visible; the verifier names it |
| "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 takes at most 10 MB per upload call | the user adds that file in the Vivu web app; never split or recompress it |
| a result's file name does not match clips.csv | Vivu replaced spaces or brackets in the name | compare names with those characters replaced by "_" |