Fix slow frame grabbing when max_fps is set on FileStreamFrameGrabber

[timmarkhuff]

Summary

_drop_frames() in FileStreamFrameGrabber used cv2.CAP_PROP_POS_FRAMES to seek past unwanted frames. On H.264/H.265 video, every seek forces the decoder to locate the nearest keyframe and decode forward to the target frame, producing a sawtooth timing pattern where grab times ramp up between keyframes. This made grabbing fewer frames (e.g. 5fps from a 30fps source) paradoxically much slower than reading every frame sequentially.

The fix replaces the seek with sequential capture.read() calls that discard unwanted frames. Sequential reads use the decoder's internal buffer and cost ~1ms each, while seeks were averaging ~40-120ms depending on distance from the nearest keyframe.

The bug

_drop_frames() called:

current_pos = self.capture.get(cv2.CAP_PROP_POS_FRAMES)
self.capture.set(cv2.CAP_PROP_POS_FRAMES, current_pos + frames_to_drop)

The fix

Replaced with:

for _ in range(frames_to_drop):
    self.capture.read()

How this bug was introduced

Git archeology shows this bug did not exist in the original implementation. The first commit on the feature branch (27a5f34, Dec 13, 2024) correctly used sequential capture.read() calls to discard frames. Four days later, a cleanup commit (f109a87, Dec 17, 2024) on the same branch replaced the sequential reads with CAP_PROP_POS_FRAMES seeking -- likely as a perceived optimization. The branch was then squash-merged to main as a4f1fd8 ("Add FileStreamFrameGrabber (#62)"), baking the regression into the mainline. The _drop_frames method has not been modified since.

Performance results (25fps H.264 source, max_fps=5, 200 frames)

Metric	Before (seek)	After (sequential read)
Mean grab time	39.5 ms	2.9 ms
Max grab time	98.2 ms	11.8 ms
Std deviation	18.4 ms	1.1 ms
Sawtooth pattern	Yes	No

[sunildkumar]

nit: some of this docstring reads as being very focused on this specific bug fix. (because claude thinks it is the center of the universe...) I would move this implementation detail to a comment instead.

[timmarkhuff]

I cleaned up the docstring. It was actually written by ChatGPT