Add FPS to get_frames_played_in_range()

[mollyxu]

Add FPS to get_frames_played_in_range()

Context: #1133

This PR adds support for specifying a target frame rate when calling get_frames_played_in_range(). When target_fps is provided, the method resamples the video to output frames at evenly-spaced timestamps matching the target FPS.

def get_frames_played_in_range(
    self,
    start_seconds: float,
    stop_seconds: float,
    fps: float | None = None,
) -> FrameBatch:

The way to read this API if fps is:

• None, default: returns decoded frames between start_seconds and stop_seconds at the input frame rate. This is the existing behavior.
• float: returns decoded frames between start_seconds and stop_seconds where the output frame rate matches the value of fps.

Implementation

1. Frame count calculation: num_output_frames = round((stop - start) * fps)
2. Timestamp generation: For each output frame i, compute target_pts = start + i / fps
3. Source frame lookup: Find the source frame displayed at target_pts using lower-bound search
4. Decode optimization: When consecutive output frames map to the same source frame (common when upsampling), the already-decoded tensor is copied rather than re-decoded

[NicolasHug]

Thanks for the great PR @mollyxu ! Left a first pass, this looks good

[NicolasHug]

Thanks for the great work @mollyxu ! I left two comments below and followed-up on the FFmpeg 4 thing above (#1148 (comment)). But this LGTM!

[mollyxu]

Thank you everyone for your feedback and reviews!