bradautomates/claude-video PR #40 — High-density frame sampling — PR #40
bradautomates/claude-video · pull request #40 ·
Transcript
PlainEnglish
Let's walk through pull request 40 for claude-video. This one adds high-density sampling modes so we can catch fast transitions that the default two frames per second ceiling would miss.
PlainEnglish
Here's what we're tackling. First, we're enabling frame-by-frame sampling at the video's native frame rate so transition analysis can catch cuts and fades that are shorter than half a second. Second, we're letting users pass an explicit frames per second value without the old two fps ceiling getting in the way. Along the way, we're raising the hard limit to a thousand frames as a runaway guard, adding native fps detection from ffprobe, and surfacing warnings when high-density mode could drive up token costs. And importantly, we're preserving all the default behavior — existing calls won't change.
PlainEnglish
Let's look at what prompted this change. Before this PR, the auto-mode ceiling of two frames per second meant that fast visual transitions — cuts, fades, wipes shorter than about half a second — would fall between the extracted frames. That made fine-grained transition analysis impossible. After this PR lands, users can opt into high-density mode, sampling at the video's native frame rate with a new every-frame flag. The default behavior stays the same, and so do the token costs for existing workflows.
Architecture
The change touches five files. The core logic lives in frames dot py and watch dot py — that's where we add the constants, the native frame rate parser, and the new CLI flag. The readme and skill doc get updated to document the high-density mode and token cost guidance. And the changelog captures the new features in an unreleased section.
Architecture
Here's where we define the new constants in frames dot py. MAX_FPS stays at two for auto-mode — that's the ceiling for sparse scans. But explicit fps parameters and the new every-frame flag deliberately bypass that ceiling so native-rate sampling is possible. The hard max frames limit rises from a hundred to a thousand. That's a runaway guard, not a working limit. The comment makes it clear that high-density runs should pair with start and end parameters to stay under budget.
Architecture
Next we add parse_frame_rate, a helper that turns ffprobe's frame rate strings into usable floats. It handles fractions like thirty thousand over one thousand and one, which evaluates to twenty nine point nine seven. It handles decimal strings, None, and invalid inputs gracefully, falling back to zero when things go wrong. This is how we detect the video's native frame rate from metadata.
Architecture
Here's the CLI change in frames dot py. The default max frames drops from a hundred to eighty for auto-mode. We add a new every-frame flag that samples at native fps. The fps selection logic now checks every-frame first, then focused mode, then full mode. And crucially, when the user passes an explicit fps parameter, we honor it verbatim — no more clamping to two fps. That's the unlock for high-density sampling.
Architecture
Watch dot py adds two warnings to help users avoid runaway token consumption. If the target frame count exceeds a hundred fifty, we print an estimated token cost range and suggest narrowing the window with start and end parameters. If high-density mode is detected on a long video without a focused window, we warn that only the first max frames will be captured. These warnings are there to guide users toward pairing high-density sampling with narrow time windows.
PlainEnglish
So what does the codebase look like after this PR? Users can now sample at the video's native frame rate using the every-frame flag or an explicit fps parameter. Fast transitions that used to fall between frames are now catchable. The default behavior is completely unchanged — auto-mode still caps at two fps for sparse scans. The hard limit at a thousand frames acts as a runaway guard, not a working budget. And the new warnings surface token cost risks before extraction starts, so users can adjust their parameters accordingly.
CodeQuality
The agent looked at several areas and found them clean. Parameter precedence is correct — if both every-frame and fps are provided, fps wins. The parse frame rate function handles invalid denominators and non-numeric strings gracefully. The default max frames versus the extract function parameter is correctly clamped. When native fps is zero, the code falls back to the max fps constant of two. And timestamp calculations correctly handle the start parameter offset. No concerns here.
PlainEnglish
So that's pull request 40. A focused feature that unlocks native-rate sampling for transition analysis while preserving all the default behavior and token costs. The new every-frame flag lives in both frames and watch scripts. Native fps detection happens through the parse frame rate helper. And token cost warnings kick in when the target exceeds a hundred fifty frames. This is a clean opt-in enhancement that solves the fast-transition gap without disrupting existing workflows.
How this was made
Lenzon read bradautomates/claude-video at pull request #40 and generated this walkthrough automatically. The narration above is the transcript of what it says.
Explain a pull request from your own repo
Point Lenzon at a repo or a pull request and get a narrated walkthrough like this one.
Try it