video-shots

name	video-shots
description	Extract coarse shot and scene-change segments from a local video, with optional representative frames for each part.

Video Shots

Use this when an agent needs to split a video into reviewable temporal parts before deeper storyboard or OCR analysis.

This skill owns:

• detecting scene-change boundaries with ffmpeg
• writing video.shots.json
• optionally extracting one representative frame per shot
• giving downstream tools a reusable list of video parts

Inputs

Required:

{
  "videoPath": "./output/example-run/output.mp4"
}

Optional fields:

• outputDir: directory for video.shots.json; defaults next to the video.
• sceneThreshold: ffmpeg scene-change threshold, default 0.08.
• minShotDurationSeconds: minimum segment duration, default 0.5.
• extractRepresentativeFrames: whether to write video-shots/shot-*.jpg, default true.

Outputs

The result contains manifestPath and manifest. The manifest lists each shot with start/end seconds, duration, boundary type, representative timestamp, and representative frame path when frames were extracted.

Sequencing Guidance

Run this before or alongside storyboard-extract when you need a coarse map of the video. Use storyboard-extract for selected visual evidence and video-shots for segment boundaries.

Interpretation Notes

Shot boundaries are heuristic. They are useful for finding parts to inspect, but they do not prove semantic scene changes or user actions. Fast cuts, fades, camera movement, and overlays can affect detection.

Abstention Rules

Do not infer what happened inside a shot from the boundary alone. Inspect the representative frame, storyboard frames, OCR, timeline evidence, or the source video before making content claims.

Failure Modes

The runner requires ffmpeg and ffprobe. Very static videos may produce one long shot. Very noisy videos may produce many short shots, which are merged by minShotDurationSeconds.

Repo-side runner:

node --import tsx scripts/harness/video-shots.ts

Installed-pack runner:

node ./.video-evaluator/agent/run-tool.mjs video-shots