---
name: carrier-damage-claim-sheet
description: "Turn dock receiving videos into a carrier damage claim CSV with Vivu and ffmpeg: crushed cartons, tipped pallets, torn wrap, each with a checked frame. Use before a freight claim deadline."
---Carrier damage claim sheet with Vivu
This skill takes the receiving videos a dock crew recorded while unloading trucks (phone clips or fixed dock camera exports, usually named only by date and a sequence number) and returns a claim evidence sheet for the receiving lead: one row per confirmed damage moment with the source file, the time as MM:SS, the damage category (crushed or torn carton, pallet load tipped over or scattered, stretch wrap torn or hanging loose, wet or stained carton), the path of a frame that shows it, the waybill or PRO number when a label in the same clip is large enough to read, Vivu's description of the moment, and empty columns for the receiver's confirmation and the claim amount. Claude indexes the clips in Vivu, runs one search per damage category, checks every returned window on a contact sheet of frames, and writes the sheet the lead attaches to the carrier's claim form.
The value is in what only the footage shows. The receiving slip says "outer packaging damaged" or carries one OS&D line; it does not say which pallet, how bad, or whether the load was already down when the trailer doors opened. A carrier claim wants that picture. Search finds candidate windows across a week of clips in a few calls, and every window is checked on its frames before it reaches the sheet, because search for this kind of damage is unreliable (see Step 6).
When to use
Use when someone asks to pull damage evidence from receiving or unloading videos, build an OS&D or freight claim photo sheet, find which clips show the crushed pallet from Tuesday's truck, or check this week's dock videos for damaged loads before a claim deadline. For one clip you already know, open it and take a screenshot. This skill does not decide who is liable (carrier, shipper or the dock crew), does not rate receivers or drivers, does not estimate the value of the damage, and does not file the claim.
Working principles
- Report real counts. When a number is an estimate (credits, minutes for a future batch), say so.
- A Vivu result is a candidate until Claude has looked at the frames inside its window. Rejected candidates go to rejected.csv with the reason; they never reach the claim sheet.
- Stop and tell the user when a required tool or capability is missing. Do not guess around it.
- Ask the user before anything that costs index minutes or search credits (Step 3), before uploading (Step 4), and before the sheet leaves the working folder (Step 7).
- The sheet is about freight. It names no receiver, driver or carrier employee, and it never copies a consignee name, address or phone number from a label; only the large printed waybill, PRO or tracking number is read.
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). A write call failing with "has not granted vivu.write" means the connection is read only: ask the user to reconnect Vivu with write access |
| A shell on the machine that holds the clips, with ffmpeg and ffprobe | durations for pricing, frames and contact sheets for every window | ffmpeg -version and ffprobe -version |
| The receiving clips in one local folder (mp4, mov or another common format) | Vivu indexes video files; the file name is the only link back to the truck | ls the folder and ffprobe one file |
| A browser the user can open the upload page in, or a browser tool that can attach local files | moving files into Vivu | ask the user; for Claude in Chrome, check that it is connected |
The skill runs in Claude Code on the user's computer (terminal or the Code tab of Claude Desktop), because it needs a shell and the local clips. It needs no residential IP, since nothing is downloaded from YouTube, and it sets up no scheduled task: run it once per batch, or per truck when a claim comes up.
Inputs to collect
Ask for anything missing, most important first.
- The folder of receiving clips (required).
- Which trucks or days the claim is about (optional). Default: every clip in the folder. If the user has the OS&D log, ask for the dates and dock doors so Step 3 can offer a smaller scope.
- Categories. Default: crushed carton and tipped pallet. Torn wrap and wet carton are added on request (Step 6 explains why).
- The working folder. Default: damage-claims/ next to the clips folder.
- The Vivu project name. Default: "Receiving damage WEEK", created private.
Files and state
Keep everything in one working folder:
damage-claims/
config.json clips folder, scope, categories, Vivu project id
files.csv source_file, path, duration_s, stored_name, video_id
state.json uploaded video ids, finished searches with job ids, checked windows and their verdicts
results/CATEGORY.json raw result of each search, saved as returned
sheets/ contact sheets for every window
frames/ the full size evidence frame for each confirmed row
damage_claim_sheet.csv the claim sheet
rejected.csv candidates rejected on their frames, with the reason
state.json lets a rerun resume: skip uploads whose video id is recorded, skip searches that already have a saved result, and skip windows already checked. Each batch gets its own working folder, so the same damage is never listed twice.
Step 1: Check the Vivu connector and the tools
Goal: confirm that everything in the table above is in place.
- Call vivu_get_account. If the tool does not exist, tell the user to add the Vivu connector in Claude (https://mcp.vivu.ai/mcp) and stop. If can_create_projects is not true, or a later write fails with "has not granted vivu.write", ask the user to reconnect Vivu with write access and stop.
- Run ffmpeg -version and ffprobe -version. If either is missing, ask the user to install ffmpeg.
- Confirm the clips folder can be read and list the video files in it.
Done when vivu_get_account shows can_create_projects: true, both ffmpeg commands print a version, and the clip list is shown to the user.
Step 2: Line up the clips
Goal: files.csv with one row per clip and its length.
- Measure each file:
ffprobe -v error -show_entries format=duration -of csv=p=0 CLIP_FILE
CLIP_FILE is one clip in the clips folder.
- Write files.csv and show the user the clip count, the total minutes, and any file ffprobe could not read.
Done when files.csv has one row per clip with duration_s, and the user has seen the count and total minutes.
Step 3: Price the batch and ask
Goal: the user approves the cost before anything is uploaded.
- Index minutes = the sum of duration_s divided by 60 for the clips in scope. Search credits = one precise search per category plus one for labels; a precise search uses 5 credits. Label it an estimate, since a rewording costs another search.
- Call vivu_get_usage for the plan and what remains this month. For reference, Free is 20 indexing minutes a month and 50 search credits a month; Premium is $30 a month for 180 indexing minutes a month and 500 search credits a month.
- Show one table:
| This batch | Remaining this month | Fits | |
|---|---|---|---|
| Index minutes | sum of durations | from vivu_get_usage | yes or no |
| Search credits (estimate) | searches × 5 | from vivu_get_usage | yes or no |
- If it does not fit, offer these levers in order, each with its saving: index only the clips from the trucks with an OS&D note; index only the clips from the dock doors in question; search fewer categories; move to a larger plan last. For example, a week of 25 clips of 2.5 minutes is about 62 index minutes, more than a Free month and inside Premium; two categories plus labels is an estimated 15 credits.
Approval was not exercised in our test run (it ran unattended on an admin account that reports no remaining allowance).
Done when the user has seen the table and said yes to a scope.
Step 4: Create a private project and upload
Goal: every clip in the approved scope shows ready in Vivu.
- Ask the user to confirm the Compliance points before uploading.
- Call vivu_list_projects and reuse the project for this batch if one exists. Otherwise call vivu_create_project with the project name and visibility "private". The default visibility is the whole organization, and dock footage shows coworkers and drivers.
- Call vivu_open_upload_page with the project ID right before the upload. The upload_url is a one time sign in link that expires in 180 seconds, so request it only when the user or the browser tool is ready, never post it in a message, and request a new one if it lapses.
- Hand the link to the user to open in their own browser and select the files, or open it with a browser tool that can attach local files. Claude in Chrome takes at most 10 MB per upload call, so send files in batches under that; phone clips are often larger. If a file cannot go through, ask the user to add it in the Vivu web app. Never split or recompress a clip to fit.
- Poll vivu_list_videos until every video shows ready. Vivu replaces spaces and brackets in file names with underscores, so match rows back by name and check that duration_ms agrees with duration_s. Record stored_name and video_id in files.csv and the video ids in state.json.
In our test run the upload page link was opened by an automated browser on our machine, not by a user, and the compliance confirmation was not exercised.
Done when vivu_list_videos shows every approved clip as ready and each one is matched to a row in files.csv.
Step 5: Search each category
Goal: one saved result per category, plus one for labels.
The standing queries, one per output field. They describe the shape of the damage, not its cause, because the search matches what it sees, and they say what does not count, because intact boxes are what most frames show:
| Field | Query | Mode | Default |
|---|---|---|---|
| crushed or torn carton | damaged cardboard cases in a load: boxes that are crushed flat, ripped open with flaps hanging, or broken so the cans or product inside show through; neatly stacked boxes with straight square edges do not count | precise | on |
| pallet load tipped or scattered | a pallet load that has tipped over or collapsed, with boxes or cases fallen off the pallet and lying scattered on the trailer floor or the dock | precise | on |
| stretch wrap torn or loose | the plastic stretch wrap around a pallet is torn, cut or hanging loose so the boxes are no longer held together | precise | on request |
| wet or stained carton | cardboard boxes that are soaked or stained by liquid, with dark wet patches or a puddle under the pallet | precise | on request |
| label | a shipping label, pallet tag or bill of lading paper with a large printed tracking number or barcode visible on a box or pallet | precise | on |
The chain: one precise search per category finds candidate windows across the whole project; the contact sheet in Step 6 confirms or rejects each window; for confirmed rows, the label search points Claude at moments in the same clip where a waybill number may be readable (Step 7). There is no fast pass: fast returns whole files with an empty reason, and receiving clips are short enough to check directly. The clips usually have no useful speech, so the flip in this skill is from what the receiving slip says ("outer packaging damaged") to what the camera shows (which pallet, which cases, how bad).
- For each category in scope, call vivu_search_videos with project_id, query, mode "precise" and maximum_results 30 (or the number of clips if that is larger, at most 100). One damaged truck often comes back as several windows on the same clip, and the value is the recall ceiling: a smaller number silently drops damage.
- Call vivu_get_search_results with the job ID until complete is true. Each call can wait up to 45 seconds, so a pending search is not a stalled one. Save the returned JSON unchanged as results/CATEGORY.json and record the job ID in state.json. The Vivu result page link from a completed search can go in the live reply; it expires after four hours, so it never goes in the sheet.
Done when every category in scope and the label search have a saved result file and a job ID in state.json.
Step 6: Check every window on its frames
Goal: each returned window judged real, false or UNCERTAIN from its own frames.
- For every window, make a contact sheet with 24 tiles across the window (one frame every 0.5 seconds for windows up to 12 seconds):
ffmpeg -v error -y -ss START -t LENGTH -i CLIP_FILE -vf "fps=FPS,scale=320:-1,tile=6x4" -frames:v 1 damage-claims/sheets/NAME_FIELD_START.png
START and LENGTH are the window start and length in seconds (start_ms / 1000 and (end_ms - start_ms) / 1000). FPS is 2 for windows up to 12 seconds and 24/LENGTH for longer ones. NAME is the clip file name without the extension and FIELD is the field name in snake case.
- Look at every sheet. Judge from the frames, never from the reason text: in our test run the first crushed carton wording returned a window of square, intact produce cartons whose reason described a crushed corner. A row is real only when a tile shows the damage itself (a case ripped open, a stack fallen over, wrap hanging loose, a dark wet patch). Damage on a load that is already down when the doors open and damage that happens during unloading look different on the frames; describe what is visible and leave the judgement to the people filing the claim.
- When the sheet is dark or blurry (night, a flashlight, a phone swinging), extract the full size frame at the best tile and look again:
ffmpeg -v error -y -ss SECONDS -i CLIP_FILE -frames:v 1 -q:v 3 damage-claims/frames/NAME_FIELD_SECONDS.png
SECONDS is the time of the tile, START + K / FPS for tile K counting from 0 (every 0.5 seconds for windows up to 12 seconds, LENGTH / 24 apart for longer ones). If the damage still cannot be seen, mark the window UNCERTAIN and put it in rejected.csv with that reason; it never goes into the sheet as confirmed. 4. Save the full size frame for every real window; this is the evidence picture the claim needs. 5. Tell the user the counts per category: returned, real, false, UNCERTAIN.
How far to trust the search: finding damaged freight is visual search, which is weak for Vivu. It found large, obvious damage in our test run, but the damage there came from one crash recovery video, not from a dock door, and a single torn case on an otherwise intact pallet was missed by the wording we kept. That is why every window goes through its frames, why the sheet only lists what the frames show, and why an empty result is not proof the batch is clean: an empty result does not prove the footage has no such damage. If the user knows which truck had the problem, skim that clip's own contact sheet as well.
Worked example from our test run
In our test run on 11 clips (27.34 minutes) we used public CC BY footage, not dock receiving video, because we found no openly licensed receiving video with damage. The damaged freight came from a single crash recovery: night clips where beer cases had tumbled, torn and spilled inside a ripped trailer, and a daytime clip of the same load being moved off with a forklift. The rest were intact freight as distractors: produce cartons on pallets in a warehouse, loading a reefer trailer, wrapped food pallets with shipping labels, loose empty pallets in a box truck. Most clips were low resolution. We wrote down the damage moments before searching and added more after the frames showed torn cases we had not marked, all on the forklift clip and on the road at the end of a debris clip; the misses below count against the corrected list. All clips were ready about 6 minutes after the upload started.
The crushed carton wording above returned 7 windows: 7 real and 0 false, with 2 missed, after 1 rewording on the same corpus. The first wording returned 8 windows: 7 real and 1 false (the intact produce cartons) with 3 missed; describing the damaged shape and excluding square boxes removed that false positive. Among the misses was a single torn case at the corner of an intact pallet, the kind of damage a real claim is often about. The tipped pallet search returned 3 windows: 3 real, 0 false, with 1 missed (the night clip where the load fell through the trailer side; the crushed carton search did return that clip). The loose empty pallets and the intact pallets were never returned by either search.
The torn wrap search returned 3 windows: 2 real and 1 we could not judge (night footage where wrap and case plastic look the same). The wet carton search returned 0, and the corpus had no wet cartons, so its recall was not tested. A control search for a forklift fork through a carton, which the corpus did not have, returned 0. The label search returned 7 windows: 3 real and 4 false (product grade labels on produce boxes), with 1 missed (a paper bill of lading held up in front of a trailer). The run used 7 precise searches, an estimated 35 credits; a weekly batch with the two default categories and the label search is an estimated 15 credits.
Done when every returned window has a verdict in state.json, rejected.csv lists every rejected or UNCERTAIN window with its reason, and the user has seen the counts.
Step 7: Read the label numbers and build the claim sheet
Goal: damage_claim_sheet.csv with one row per confirmed damage moment, ready to attach to the carrier's claim form.
- For each clip with a confirmed row, check whether the label search returned a real label window in the same clip. If it did, extract the full size frame and read only the large printed waybill, PRO or tracking number. Write it in waybill_read only when every character is clear; otherwise write NOT LEGIBLE. Never read or copy the consignee name, address or phone number. Label reading is weak: in our test run the label search also returned product grade labels, and Claude could read the number only on a pallet label filmed close up in a sharp clip, while tags and carton labels in the low resolution clips stayed NOT LEGIBLE. The receiving slip or the bill of lading is the better source for the number; the frame only ties it to the right clip.
- Show the user one sample row and the field mapping below, and wait for a yes before writing the full sheet:
| CSV field | Source | If unavailable |
|---|---|---|
| source_file | files.csv | none; every row has one |
| time | the Vivu window as MM:SS-MM:SS; windows of the same category on one clip that are less than 30 seconds apart are merged into one row, and check_note says which parts show the damage | none |
| damage_category | the category of the search | none |
| frame_path | the full size evidence frame from Step 6 | blank, and say why |
| waybill_read | the number read in item 1 | blank or NOT LEGIBLE |
| search_reason | the reason text, quoted as returned; it is a description, not evidence | blank |
| check_note | what Claude saw on the frames, about the freight only | none |
| receiver_confirmed, claim_amount | the receiving lead | blank |
Sample row from our test run:
source_file,time,damage_category,frame_path,waybill_read,search_reason,check_note,receiver_confirmed,claim_amount
RD_06.mp4,00:35-01:24,crushed or torn carton,frames/crushed_carton_v1_h1_mid.png,,"Close-up view of crushed, ripped open cardboard beer cases with hanging flaps and cans visible in the truck's freight.","00:35-00:46 torn flaps and broken cases at the deck edge; 01:14-01:24 cases ripped open with cans showing",,
This row merges two windows on the same clip under the time rule in the mapping. Its frame_path uses the file names of our test run; a real run names the frame NAME_FIELD_SECONDS.png as in Step 6, for example frames/RD_06_crushed_carton_79.png.
- Write damage_claim_sheet.csv sorted by source file and time. File names are the only link to the video; no Vivu links, because the result page link expires.
- Tell the user the rows per category, the number rejected and UNCERTAIN, and which categories were searched and which were skipped.
- The sheet stays in the working folder. Attaching it to the carrier's claim portal or emailing it to the carrier acts on the user's behalf: name the destination, show the rendered file and wait for approval, and draft emails rather than sending them. That was not exercised in our test run; we only wrote the files.
Done when damage_claim_sheet.csv has one row per confirmed damage moment with an existing frame path, rejected.csv lists every rejected window, and the user has both files.
Compliance
- Rights to the footage: use it on recordings your company made and may process under its own policy. Confirm before Step 4.
- People on camera: receivers, drivers and other dock staff appear in the clips. Recording at work should follow your company's notice or consent rules; confirm before Step 4. The skill does not identify anyone, rate receivers or drivers, or decide who caused the damage, and check_note describes freight only.
- Labels: only the large printed waybill, PRO or tracking number is read. Consignee names, addresses and phone numbers on labels are never copied into any file.
- Minors: dock work does not involve minors; if a clip shows a child, leave that clip out.
- Where the videos go: uploaded files stay in the user's Vivu project until the user deletes them. The skill creates the project as private and never deletes projects or videos unless the user asks, and then confirms first.
- What the skill does not do: no liability decision, no damage valuation, no claim filing, and no face, logo or identity recognition.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) the crushed carton search returns intact cartons, reason "A cardboard box stacked on top of a pallet in the warehouse has its side and corner visibly crushed and caved in." | the reason text describes the query back | judge from the contact sheet; use the wording that excludes square intact boxes |
| (observed) a single torn case at the corner of an intact pallet is missed | small damage on a mostly intact load is weak for visual search | skim the contact sheet of the clip named in the OS&D note |
| (observed) the tipped pallet search misses a night clip that the crushed carton search returns | dark, shaky footage | run both default categories; a clip found by either gets checked for both |
| (observed) a night window cannot be judged: wrap and case plastic look the same | flashlight only, low resolution | mark it UNCERTAIN and leave it out of the sheet |
| (observed) the label search returns product labels, reason "Large printed shipping/product tags with QR codes and text labels are visible on stacked produce boxes in the warehouse." | grade and product labels look like shipping labels | keep only labels with a carrier or shipment field; take the number from the receiving paperwork |
| (observed) the label number is NOT LEGIBLE | the label is small or the clip is low resolution | leave waybill_read blank; ask the crew to film the label close up |
| an empty result for a category | visual search is weak; an empty result does not prove the footage has no such damage | page through the clips of the trucks with an OS&D note |
| "has not granted vivu.write" | Vivu connected read only | reconnect 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 phone clip is rejected by the browser upload tool | file above the tool's size limit | the user adds that file in the Vivu web app |
| rows do not line up with results | Vivu normalized the file name | match on the name and on duration_ms |