feat(utils): add prefetch to get_video_frames_generator

[Ace3Z]

Closes #1411.

@LinasKo asked for a worked threading example that produces a real FPS improvement for the get_video_frames_generator path. This PR adds an opt-in prefetch: int = 0 argument: when > 0, frames are decoded in a background thread and buffered in a bounded queue, so a CPU-bound consumer can overlap with decode I/O.

for frame in sv.get_video_frames_generator("video.mp4", prefetch=8):
    run_inference(frame)

Default stays 0 (synchronous, behaviour unchanged). The threaded path is a thin wrapper that drives the existing sync generator on one daemon=True thread and pushes frames through a Queue(maxsize=prefetch). No new dependencies, ~30 added lines in video.py. Pattern matches the reader-thread already in process_video further down the same file.

Benchmark

150-frame 1080p h.264 video, fixed CPU consumer simulated with time.sleep:

consumer work per frame	sync	prefetched=8
10 ms	63.8 fps	78.3 fps (+23%)
20 ms	38.2 fps	39.6 fps (+4%)
40 ms	21.4 fps	22.1 fps (+3%)

Decode alone on this video is ~10 ms/frame, so the speed-up is largest when the consumer cost is roughly decode-bound. Heavier consumers asymptote to no benefit, which is the right behaviour.

Test

test_get_video_frames_generator_prefetch_matches_sync runs the generator twice on the same dummy video with prefetch=0 and prefetch=4 and asserts the two outputs are frame-for-frame identical. Full pytest src/ tests/ is green (1859 passed). Pre-commit clean.

[codecov]

Codecov Report

❌ Patch coverage is 80.43478% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 87%. Comparing base (25e879e) to head (c0d942e).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2273   +/-   ##
=======================================
- Coverage       87%     87%   -0%     
=======================================
  Files           85      85           
  Lines        11855   11901   +46     
=======================================
+ Hits         10277   10315   +38     
- Misses        1578    1586    +8     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds an opt-in prefetch parameter to get_video_frames_generator to overlap frame decoding with CPU-bound consumers by decoding frames on a background thread and buffering them in a bounded Queue. This targets the FPS bottleneck raised in #1411 while keeping the default (prefetch=0) behavior unchanged.

Changes:

• Extend get_video_frames_generator(..., prefetch: int = 0) with a threaded prefetch path when prefetch > 0.
• Add internal _prefetched_frames_generator that drives the existing synchronous generator from a daemon thread and yields frames from a queue.
• Add a regression test ensuring prefetched output matches the synchronous frame sequence exactly.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/supervision/utils/video.py	Adds prefetch option and a new internal queued background-reader generator.
tests/utils/test_video.py	Adds a test asserting prefetched iteration matches the synchronous generator frame-for-frame.

[Ace3Z]

Friendly ping. @Borda, would you have a moment to take a look? Happy to address any feedback.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.