---
name: equipment-rounds-reading-log
description: "Turn plant room round videos into a reading log with Vivu: find each panel display, read its values from frames, and write a CSV for the supervisor to check. Use when round sheets are blank."
---Equipment rounds reading log from walk videos
This skill takes a week of plant room round videos (the phone or head camera clips shift technicians record while they walk the chillers, drives and electrical panels) plus the supervisor's list of checkpoints, and returns a reading log: one row per value read, with the round file, the date, the checkpoint, the minute and second the display is on screen, the label, value and unit as shown, a saved frame of the display, whatever the technician said about the equipment, and an empty column for the supervisor to tick after checking. Checkpoints that never appear in a round go on a separate list. Claude measures the videos, prices the indexing against the user's Vivu plan, indexes them in a private Vivu project, runs one precise search per checkpoint type, extracts frames every half second inside each window, confirms which equipment the display belongs to, reads the values from a zoomed full frame, scans any round where a checkpoint has no window, and writes rounds_readings.csv.
The value is in numbers that exist only on a lit display for a few seconds. Technicians often film the panel and never say the number, so the paper round sheet stays empty, and the transcript of the video has nothing to offer. Vivu finds the seconds where a display fills the frame; the frames, not Vivu, decide which machine it is and what it reads. A value that cannot be read with certainty goes in as NOT LEGIBLE, never as a best guess. The skill does not judge whether a value is normal or a machine is safe; the supervisor does that against the plant's operating procedures.
When to use
Use when a chief engineer, facilities manager or shift supervisor says "pull the chiller and drive readings from this week's round videos", "the techs filmed the panels but the log sheet is blank", "make me a reading table from the walk videos", or "which rounds skipped the VFD". For one round, open the video and pause on the panel yourself. For defects, leaks or damage on a walk, use an inspection or site walk skill instead. For nameplate serial numbers, use a warranty serial skill. This skill reads only digital displays; it does not read analog dial gauges.
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, confirmed the machine, and read every character of the value on the frame. Anything else is NOT LEGIBLE, with the readable part only.
- Stop and tell the user when a required capability or file is missing (no ffmpeg, no write access in Vivu, no checkpoint list). 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 log.
- Read equipment, not people. People on camera never go into the log, and the log has no column that scores the technician.
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 videos | measure minutes, read the recording date, extract frames and crops | ffmpeg -version and ffprobe -version |
| The round videos as local files | every value is read from the user's own files; Vivu has no export tool | ls ROUNDS_FOLDER |
| The supervisor's checkpoint list | the searches are written per checkpoint type, and the log is checked against it | ask for it; a starting list is in Inputs to collect |
| 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 from YouTube or anywhere else, 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 week's round videos (ROUNDS_FOLDER). Required.
- The checkpoint list: each checkpoint type and, when there are several of a kind, how they are told apart (for example "Chiller 1 and Chiller 2, the screen title says which"). Required. Default to offer: chiller control screen, drive keypad, panel meter.
- Which values to copy per checkpoint (for example condenser entering and leaving temperature and condenser pressure on the chiller screen). Default: every labeled value on the page shown.
- The Vivu project name. Default: "Plant rounds WEEK", private, where WEEK is the week's start date.
Files and state
Keep everything in one working folder next to the videos:
rounds-log/
rounds.csv file, recording date, minutes, video id
results/ raw search results, one JSON file per search
frames/ half second sheets, scan sheets and the read crops
rounds_readings.csv one row per value, with read_status and an empty supervisor_checked column
not_found.txt checkpoints with no confirmed display per round
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 read keep their verdicts, so an interrupted run resumes where it stopped. A video already in the project from an earlier week is skipped by video id, so the same round is never logged 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 ROUNDS_FOLDER and create the working folders; ffmpeg does not create an output folder:
mkdir -p rounds-log/results rounds-log/frames
Run every later command from inside rounds-log/ (cd rounds-log), with ROUNDS_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: Agree the checkpoints and price the indexing
Goal: the checkpoint list is fixed and the user has seen the cost before anything is uploaded.
- Ask Compliance items 1 and 2 first.
- Confirm the checkpoint list and the values to copy (Inputs 2 and 3).
- For each video, measure the length and read the recording date. ffprobe takes one input file per call (VIDEO_FILE is a file in ROUNDS_FOLDER):
ffprobe -v error -show_entries format=duration:format_tags=creation_time -of default=noprint_wrappers=1 ROUNDS_FOLDER/VIDEO_FILE
When creation_time is missing, use a date in the file name if the user confirms it, otherwise write the date as UNCERTAIN; a copied or edited file often loses the camera date. 4. Call vivu_get_usage for the plan and what remains this month. 5. Estimate search credits: one precise search per checkpoint type per batch, 5 credits each. Label the total as an estimate. With the default three display checkpoints plus the optional tech_said search, that is 4 precise searches, about 20 credits per weekly batch (estimate). Show one table and wait for approval:
| This batch | 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, six rounds of 15 minutes a week is 90 index minutes a week, which is about two weeks of Premium, so a full month of rounds does not fit. If a batch does not fit, offer these levers in order: index only the rounds whose log sheet is blank, or only the first and last round of each shift, and only then a larger plan. Never drop a round 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. The spliced test files carried no camera date, so reading the date from metadata was not exercised in our test run either.
Done when the user has approved the checkpoint list, the minutes and the credit estimate.
Step 3: Upload and index
Goal: every round video 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". Plant room videos show the building's equipment and sometimes staff; 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 a 15 minute phone clip is far larger; the user adds those in the Vivu web app. Never split or recompress a video to fit.
- Poll vivu_list_videos about every 30 seconds until every file shows ready. Match each video back to rounds.csv by file name; Vivu turns spaces and punctuation in names into "_", so compare names with those characters replaced. Record the video IDs in state.json.
In our test run the files went up through a script, not through a user's browser or Claude in Chrome; that upload path was not exercised in our test run.
Done when vivu_list_videos shows every file in rounds.csv as ready.
Step 4: Find each checkpoint's panel moments
Goal: a list of candidate windows per checkpoint type.
One precise search per checkpoint type covers every round, because one search covers the whole project. Describe what the display looks like and where it sits, never the values, because the values are what we do not know yet:
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| chiller_panel | the camera is close on a chiller's control panel: a lit screen built into the machine's control box, filled with rows of temperature and pressure numbers or menu buttons; a printed nameplate, a handheld meter or a phone does not count | precise | 20 |
| vfd_keypad | the camera is close on a motor drive's keypad: a small backlit LCD above a grid of number keys on a drive cabinet, showing a status line with hertz, volts or amps | precise | 20 |
| panel_meter | a small square meter about the size of a pilot light, glowing with three short lines of digits marked V, A and Hz, with no keypad around it; a motor drive keypad with a grid of buttons or a large touchscreen does not count | precise | 20 |
| tech_said (optional) | the person filming says out loud which piece of equipment they are at, naming it, such as the chiller, the generator, the pump or the drive | precise | 20 |
- Adapt each display query to the user's own equipment (brand, size, color, where it is mounted) and add one for each other checkpoint type in the list, written the same way. The panel_meter wording above is the second version; the first, which only said "a small square digital panel meter lit up with bright digits", also returned a drive keypad.
- Run each with vivu_search_videos (project_id, query, mode "precise", maximum_results 20). 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 in results/. Show the result page link in the live reply only; it expires after four hours, so it never goes into the log or any file.
- maximum_results is also the ceiling on what comes back. Set it to at least twice the number of rounds, since a technician may stop at the same panel twice; when a list stops at exactly that number, raise it and rerun.
- Why this chain: the precise search turns a 15 minute round into a window of a few seconds per display, the half second sheet in Step 5 confirms the machine and finds the sharpest frame, and the Step 6 scan catches a round the search left out. The tech_said search goes the other way, from what is shown to what is said: it fills the tech_said column and helps tell two identical machines apart, but it cannot place a reading, because technicians name a machine and look at its display at different moments.
- Before writing anything into tech_said, read the summary segments around that window with vivu_get_video_summary (project_id, video_id, include_segments true, start_ms and end_ms around the window). The reason text and the segments are paraphrases, not a transcript, so tech_said holds a paraphrase marked NOT VERIFIED unless the user has a transcript or captions to quote from.
- Write every window into state.json as a candidate.
Done when each checkpoint search has a saved result in results/ and every window is in state.json.
Step 5: Check each window and read the display
Goal: every window is confirmed or rejected against frames, and every confirmed display has its values read from a zoomed frame or marked NOT LEGIBLE.
A search returns the nearest lit equipment screen, not necessarily the checkpoint it was asked for: a drive keypad can come back for a chiller search, and a search for a display that is not in the footage at all returns other screens instead of nothing. Which search returned a window says nothing reliable about which machine it shows. The frames decide.
- Make a sheet of one frame every half second across the window (START is start_ms / 1000, DURATION is (end_ms - start_ms) / 1000; ROUND is the file's short name, HIT is h plus the window's number; the 8x6 grid holds 24 seconds, so for a longer window raise the second number):
ffmpeg -v error -ss START -t DURATION -i ROUNDS_FOLDER/VIDEO_FILE -vf "fps=2,scale=320:-2,tile=8x6" -frames:v 1 frames/ROUND_HIT_sheet.png
Keep the quotes around the filter. Windows start and end a second or two outside the display, so the first and last cells often show the next room or another device. 2. Confirm the machine from what the frame shows: the screen title (Chiller 1), the brand on the bezel, the keypad layout, the cabinet around it. Reject the window if it shows a different checkpoint type, a printed nameplate, a handheld meter, a picture of a display on a box, an unlit display, or numbers written on equipment by hand. When two machines of the same model have identical screens and nothing on screen tells them apart, use the tech_said window if it overlaps; otherwise mark the machine UNCERTAIN. 3. Pick the cell where the display is sharpest and least covered by a hand, a pen or reflection. Extract that second at full size, cropped to the display and enlarged two times (SECONDS is the window start plus half the cell's index; CROP_W, CROP_H, CROP_X and CROP_Y frame the display in pixels of the full frame):
ffmpeg -v error -ss SECONDS -i ROUNDS_FOLDER/VIDEO_FILE -frames:v 1 -vf "crop=CROP_W:CROP_H:CROP_X:CROP_Y,scale=iw*2:-2" frames/ROUND_HIT_read.png
- Copy each requested label, value and unit exactly as shown, signs and decimal points included. A running machine's screen updates every second, so the reading belongs to that exact second; record it in mm_ss. When reflection, blur or a finger hides any character, write NOT LEGIBLE for that value, try the neighboring cells once, and never fill a gap from what the value usually is.
- The reason text is a description, not a reading. It sometimes quotes values correctly and sometimes invents them; never copy a value from it.
- Rejected windows stay in state.json with the reason; they are counted, not dropped silently.
Worked example from our test run
In our test run we used 6 public videos, 23.59 minutes in total: mock rounds spliced from Creative Commons clips of a chiller plant walk, an indoor centrifugal chiller touchscreen, an outdoor air cooled chiller touch panel under strong reflection, a motor drive keypad, a square volt and amp panel meter, a data center generator and pump room tour, and a boiler service with handheld meters. Before searching we wrote down every display moment and copied the values from a full frame. The distractors were printed nameplates, handheld meters, a product box printed with a picture of a meter, an unlit meter, a generator controller small in the background, and walks with no readable display. From the upload to all 6 videos ready took about 3.8 minutes.
The chiller_panel search, first wording on this corpus, returned 8 windows: 7 real, 1 false and 0 missed. Every chiller display we had written down came back, the glare covered outdoor panel as well as the indoor touchscreen, plus a real chiller service screen inside a nameplate clip that our own notes had missed. The false window was the drive keypad. The vfd_keypad search returned 3 real windows and missed none. The first panel_meter wording returned 3 windows, including the drive keypad; after 1 rewording on the same corpus the panel_meter search returned 2 real windows and missed none. A control search for a boiler display, which the corpus does not have, returned 3 chiller screens rather than nothing. Chiller windows had a median of 24 seconds and usually ran into the next scene. The tech_said search returned 7 windows, which we could not check without a transcript, so that column is not exercised in our test run beyond the search itself.
Reading from the zoomed crops, the drive keypad lines, the lit panel meter and the indoor chiller values were clear, and every value matched what we had copied before searching, except live values on the running chiller screen that had changed between the seconds we compared. The outdoor panel under reflection gave legible tiles on a single page and nothing on the others, and the meter seen small and turned on the bench was not legible; those went in as NOT LEGIBLE. The same person wrote the notes and checked the readings, so this is not an independent check. A real week of head camera rounds, night lighting, and identical machines side by side were not exercised in our test run.
Done when every window in state.json has a verdict and every confirmed display has a read frame in frames/.
Step 6: Scan rounds where a checkpoint has no window
Goal: every checkpoint in every round is either found by a scan or listed in not_found.txt.
- For each round where a checkpoint has no confirmed window, make sheets of one frame every two seconds, one sheet per 100 seconds (START is 0, then 100, 200 and so on up to the round's length; the 10x5 grid holds 100 seconds):
ffmpeg -v error -ss START -t 100 -i ROUNDS_FOLDER/VIDEO_FILE -vf "fps=1/2,scale=192:-2,tile=10x5" -frames:v 1 frames/ROUND_scan_START.png
Use one sheet per chunk with -ss, not one sheet over the whole file. In our test run a single sheet over a whole spliced round silently left out the start of the round. 2. If a cell shows the checkpoint's display, go back to Step 5 with a window around that second. Otherwise add the round and checkpoint to not_found.txt with what the round shows instead. 3. Tell the user which checkpoints were not found. An empty search result does not prove the technician skipped the panel; the scan is what decides.
In our test run this scan was run on some of the rounds without a drive keypad window and showed no keypad; not every such round was scanned, so the scan was not exercised in our test run for every round.
Done when every checkpoint in every round has a row in rounds_readings.csv or a line in not_found.txt.
Step 7: Assemble the reading log and confirm the sample
Goal: one table the supervisor can check and enter into the maintenance system.
- Build one row per value:
round_file,round_date,checkpoint,mm_ss,reading_label,value,unit,read_status,frame_path,tech_said,supervisor_checked
ROUND_D1.mp4,UNCERTAIN,chiller control screen (Chiller 1),01:51,Cond Press,71.3,psi,read,frames/D1_h2_read.png,,
ROUND_D4.mp4,UNCERTAIN,outdoor chiller panel,00:50,values,NOT LEGIBLE (reflection),,NOT LEGIBLE,frames/D4_h3_sheet.png,,
- Field mapping:
| Field | Source | If unavailable |
|---|---|---|
| round_file | the original file name in rounds.csv | none |
| round_date | creation_time from Step 2, or a confirmed date in the file name | UNCERTAIN |
| checkpoint | the machine confirmed on the frame in Step 5 | UNCERTAIN, with what is visible |
| mm_ss | the second of the read frame | none |
| reading_label, value, unit | copied from the read frame | NOT LEGIBLE |
| read_status | read or NOT LEGIBLE | none |
| frame_path | the read crop or sheet | none |
| tech_said | the tech_said window overlapping this display, checked against a transcript | NOT VERIFIED, or blank when nothing was said |
| supervisor_checked | left empty for the supervisor | blank |
- Show two or three sample rows, the mapping and not_found.txt, and wait for a yes before writing the full table. Say which parts are Claude's reading: every value is copied by Claude from a frame, so the supervisor opens frame_path and confirms each one before it goes into the maintenance system; the checkpoint name is Claude's identification of the machine from the frame.
- Write rounds_readings.csv and not_found.txt, and give the user the counts: values read, NOT LEGIBLE, rejected windows, and checkpoints not found.
In our test run the log and the not found list were written from the checked windows and the scans; the supervisor's approval of the sample rows was not exercised in our test run.
Done when rounds_readings.csv and not_found.txt exist and the user has approved the sample rows.
Compliance
- Use only your own organization's round videos. Ask before Step 2 whether company policy allows uploading plant room footage to a third party service; some sites treat equipment rooms as restricted.
- Rounds can show staff and contractors. Before Step 3, ask whether the people who appear in the rounds know they are recorded and agree to the videos being uploaded to a Vivu project, as your site's recording policy requires; if they have not, stop and do not upload. Create the Vivu project as private (the default visibility is the whole organization). People never go into the log, and the log does not score technicians. The videos 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.
- The log records what the displays showed. It does not judge whether a value is out of range or whether equipment is safe to run; the supervisor does that against the operating procedures.
- No face, voice or identity recognition. Vivu only finds when a display is on screen; the values are read by Claude from frames extracted by the user's own ffmpeg from their own files.
- The skill writes only local files. The supervisor enters the checked rows into the maintenance system.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) a drive keypad comes back for the chiller screen search | the search finds lit equipment screens in general and does not tell one machine type from another | confirm the machine on the half second sheet in Step 5 and reject windows of another type |
| (observed) a search for a display the footage does not have returns other screens instead of nothing | the nearest lit screen is returned for a missing checkpoint | never take the checkpoint from which search returned the window; the frames decide, and an empty checkpoint goes to the Step 6 scan |
| (observed) the reason text lists volts, amps and hertz for a drive menu page | the reason describes what the query asked for, not what the screen shows | read every value from the zoomed frame; never copy from the reason |
| (observed) an outdoor touch panel is unreadable apart from a tile or two | sunlight and the technician's reflection cover the screen | write NOT LEGIBLE for each hidden value and ask the technicians to shade the screen or film it at an angle |
| (observed) the same chiller value differs between frames a second apart | the running screen updates live | record the exact second of the read frame in mm_ss and read every value on the page from that frame |
| (observed) a scan sheet over a whole round is missing the start of the video | a single tile sheet over a long or spliced file can drop frames without an error | make the scan sheets per chunk with -ss START as in Step 6 |
| (observed) windows run into the next room or device | windows are wider than the display on screen | find the display on the half second sheet and read only from a frame inside it |
| two identical machines cannot be told apart | the screens look the same and the title does not name the unit | use the tech_said window or a unit label in frame; otherwise mark the checkpoint UNCERTAIN |
| a checkpoint comes back empty although the technician stopped there | finding a display by how it looks can miss | run the Step 6 scan before listing it as not found |
| a list stops at exactly maximum_results | the cap cut the list short | raise maximum_results and rerun |
| "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 rounds.csv | Vivu replaced spaces or punctuation in the name | compare names with those characters replaced by "_" |