Ablation-Lab/video-review

Video review

The tool turns a video file or a Remotion project into a review pack you can read: frames as PNGs, audio findings, the narration line and the OCR'd on-screen text at each frame, automatic checks, and what changed since the last review, all in report.md. Your job is to run it, then review the video from the pack.

1. Run the tool

Run it with this exact command (it works from both the Bash and the PowerShell tool), using the user's path in quotes:

powershell -NoProfile -ExecutionPolicy Bypass -File "${CLAUDE_SKILL_DIR}/review-video.ps1" "<video file or Remotion project folder>" [options]

• Video file (MP4, MOV and so on): frames every 2 s, around each scene change and at the end.
• Remotion project folder: stills rendered with npx remotion still (no full render needed) and the audio rendered on its own. It uses the first composition unless -Composition <id> is given; the output lists the others. It needs npm install already run in the project.

Useful options (all optional):

Option	Use
-Composition <id>	Remotion: which composition to render.
-Frames 0,90,450	Remotion: render only these frame numbers.
-Interval <s>	Seconds between regular frames (default 2). Use 4 or more for long videos.
-Narration <file>	Narration source if it isn't found automatically: .srt, .vtt, .csv, .md recording table or voiceover.json.
-Project <folder>	Folder to search for narration when the video sits outside its project.
-OutDir <folder>	Where to write the pack.
-CompareWith <folder>	Compare with an older review folder (e.g. of a previous file name). By default each run compares with the last run of the same video.
-ChangesPdf	Also make a PDF of only the changed frames, when the user wants just the changes.
-KeyFramesPdf	Make key-frames.pdf in the review folder: about 15 to 20 frames, one fully built frame per scene plus flagged frames, labelled with timestamp, scene and finding, under 10 MB. If the review folder already holds a complete review it is built from those frames and nothing else changes; otherwise the review runs first. Add -NoPdf to skip the full contact sheet.
-KeyFramesMaxMB <n>	Size limit for key-frames.pdf (default 10).
-WordsPerSecond <n>	Reading speed for the reading-time check (default 3).
-NumberWordsFrom <n>	Spoken number words are checked from this value up (default 10).
-SafeMargins t,r,b,l	Shorts safe-area margins at 1080x1920 (default 288,192,672,48, Google's cautious figures).
-WordList <file>	Extra words the spelling check accepts.
-SceneThreshold 0.3	For camera footage (the default 0.02 suits slides with fades).
-NoOcr	Skip the on-screen text checks.
-NoPdf	Skip the PDF when the user only wants your review.
-NoAudio	Remotion: skip the audio render.

Long videos take a while: about 2 minutes for 8 minutes of video, and about 4 s per Remotion still. Use a timeout of 10 minutes. The last lines of the output give the paths of report.md, the frames folder and the PDFs, plus one-line totals for the audio, text checks and changes. The pack goes in <video name>-review\ next to the video, or in out\<composition>-review\ inside a Remotion project, unless -OutDir was given. Each run keeps the previous one in previous\.

If the output ends with FAILED:, stop and tell the user the reason. If ffmpeg is missing, the fix is winget install --id Gyan.FFmpeg -e, then a new terminal. Lines starting with WARNING: also appear at the top of the report. Pass them on.

2. Skim or full review

Running the tool is cheap; opening frames is what uses the user's usage, because every frame you open is an image to read. A full review of a 15-minute video, with six Opus subagents opening every frame, once used up a whole usage session. So:

• Skim by default, unless the user asks for a full review (in words like "full review", "every frame", "go through all of it"). In a skim, work from report.md: the summary, the checks, the narration timeline and each frame's OCR text and flags. Look at the scene-change frames (end of scene and scene change) through their rows in the report, and open a frame image only where something looks wrong: a flagged check, a narration line that doesn't fit the text on screen, a changed frame, an audio problem at that moment, or OCR text that is empty or garbled where there should be a slide. Say at the end that it was a skim and how many frames you opened.
• Always open some real frames, in a skim, a text-only review or a timeline-only verdict alike: about one fully built slide per scene (the end of scene frame, once everything has appeared), or 15 to 20 spread across the video if there are no clear scenes. They show the visual style (layout, overlaps, overflowing boxes, contrast, blank frames) that the text can't. For a long video, have the Sonnet subagent that skims it open them. Always say at the end how many frames were opened.
• Full review only when asked. If the video is over 5 minutes (see Length and Frames in the summary of report.md), stop before opening any frames: tell the user how many frames there are and how many you would open, that a full review will use a lot of their usage, and ask whether to go ahead, offer a skim instead, or rerun with a larger -Interval for fewer frames (-Interval 4 halves the regular frames). Wait for the answer.
• When doing a full review: run at most two subagents at a time and open at most 100 frames in total, unless the user gave another number or said "every frame, no cap". Use Sonnet for the subagents unless the user asks for Opus; if they do, use it, but mention once that it uses much more usage. Give each subagent its own range of frames and the matching rows of report.md, and have it return only the problems it found.

Rough frame counts: -Interval 2 (the default) gives 30 regular frames per minute of video, -Interval 4 gives 15 and -Interval 10 gives 6, plus up to two per scene change.

How users ask

The user says	Do
"Review C:\path\to\video.mp4"	Skim.
"Do a full review of C:\path\to\video.mp4"	Full review, up to 100 frames (ask first if over 5 minutes).
"...full review..., every frame, no cap"	Full review of every frame. Ask first if over 5 minutes, saying it can use a whole usage session.
"...use Sonnet subagents" / "...use Opus"	That model for the subagents (Sonnet is the default anyway).
"Skim it with Sonnet and write a timeline file, then give me your overall opinion from the timeline"	Run the tool, then have one Sonnet subagent skim the pack, open the sample of key frames (one fully built slide per scene) and write timeline.md in the review folder: one entry per scene with its time range, the narration in brief, the on-screen text in brief, what the visuals look like and any problems. Read only that file (open no frames yourself) and give an overall opinion: structure, pacing, clarity, visual style, and whether the slides support the narration. Say how many frames were opened.
"Make the review PDF for C:\path\to\video.mp4 so I can attach it to a chat"	Run the tool and give the full path of the PDF. Don't review or open frames unless asked.
"Make a timeline file and a key-frames PDF ... so I can attach both to a chat"	Run the tool with -KeyFramesPdf (see "Sharing with a chat AI" below) and write the timeline as above.

Sharing with a chat AI

For a long video, don't attach the full contact-sheet PDF (hundreds of frames). Give the user two things: a text timeline file (timeline.md, as above) and the key-frames PDF, made with -KeyFramesPdf (add -NoPdf if the full PDF isn't wanted; on a folder that already has a review it reuses the frames and runs in seconds). It holds about 15 to 20 frames: one fully built frame per scene plus the frames the review flagged, each labelled with timestamp, scene name and the finding, under 10 MB, saved as key-frames.pdf in the review folder. Give its full path. If the tool couldn't find clear scenes (no numbered footer badge), it spreads the frames evenly and says so in the labels. It can't spot visual problems itself, so if you found some (an overlap, a blank frame), say which timestamps to look at when handing it over. The full PDF is best for short videos such as Shorts, or -ChangesPdf for just the changed frames.

3. Review the video

1. Read report.md. In order: warnings; changes since the last review (only when there was a previous run: the changed frames, with a link to the old frame and the words added and removed); a summary; audio findings; the narration timeline (each line with its start, end and match score); the on-screen text checks (spelling, reading time, numbers, Shorts safe areas); then a table of every frame with its time, why it was taken, its file in frames/, the narration at that moment, its OCR text and its flags. "(pause; last line)" means no one is speaking and the line shown was the one just spoken.
2. If the user asked what changed, or a changes section is present, start with the changed frames: open each one next to its previous frame and say what changed.
3. Compare each slide with its narration line. In a skim, do this from the OCR text in the report and open only the frames that look wrong (see section 2). In a full review, open the frames with the Read tool, within the agreed cap: the frames marked end of scene first (each is a finished slide just before it changes) and scene change (each is the next slide once it has settled), then every flagged frame, then the regular frames wherever the narration line changes or something builds up on screen.
4. Treat the automatic checks as leads, not verdicts, and confirm each one in the frame image:
   • Spelling: OCR can misread small, faint or monospaced text, and some flagged words are deliberate (names, misheard words shown on purpose). Report only the ones the image confirms.
   • Reading time: flagged slides have more new words than fit their time at the given words per second. Narrated diagrams with many labels trip it easily; say which slides really need more time.
   • Numbers: a spoken number not found on screen is either a real mismatch (the slide shows a different figure) or a number OCR missed, often big headline digits. Check the frame.
   • Safe areas: text inside YouTube's overlay margins on vertical videos. The default margins are the most cautious published ones, so prioritise text near the bottom and right edges.
5. In the frames you open, also check by eye for on-screen text, numbers, names or labels that disagree with the narration, cut-off or overlapping text, low contrast, empty or black frames, and placeholder or leftover content; narration lines marked "not found"; and audio problems in the report (clipping, true peak above -1 dBTP, clicks or pops, silences mid-video, loudness far from about -14 LUFS).
6. Report back briefly: the problems first, each with the frame number and timestamp (for example #14 00:22.00) and what is wrong, then the audio findings, then anything the tool couldn't check. Say plainly if everything matches. Don't change the project unless the user asks; if a flagged word is correct, you can suggest adding it to review-words.txt in the project folder.

The PDFs

<name>-review.pdf is in the same folder: a cover page with the audio findings, the checks and any changes, then 6 to 9 frames a page, each labelled with its timestamp, any problems found (red), the narration line and the OCR text (blue, misspellings underlined). It is kept under 20 MB. With -ChangesPdf there is also <name>-changes.pdf with only the changed frames. When the user wants something to attach to a Claude chat or send to someone, give them the full path. Use -MaxPdfMB <n> for a smaller limit. key-frames.pdf (with -KeyFramesPdf) is the one to attach for long videos.