Skip to content

Sampling Methods

Sampling Methods

The sampling_method parameter provides fine-grained control over frame selection from video inputs. By selecting frames strategically, you can reduce data load, speed up processing, and improve accuracy.

Available Methods

Choose from four sampling strategies: "duration" (default), "middle", "rand", or "fps".

Method Description Use Case Parameters
"duration" (default) Selects frames based on video duration in seconds, evenly spaced across the timeline. Constrained by min_num_frames and max_num_frames.

- If duration < min_num_frames → samples min_num_frames
- If duration > max_num_frames → samples max_num_frames
- For very short videos, frame count is calculated from FPS and rounded down to nearest multiple of 8 (e.g., 1-second video at 30 FPS → 24 frames)		 Automatically scales frame selection based on video length min_num_frames, max_num_frames
"fps" Selects frames at a fixed rate (frames per second), evenly spaced throughout the video Consistent time-based sampling across videos of different lengths sampling_fps, max_num_frames
"middle" Divides video into evenly spaced intervals based on max_num_frames, selecting the middle frame from each interval. If video has fewer frames than max_num_frames, repeats the last frame Prioritizes center of each segment when key content appears mid-scene max_num_frames, min_num_frames
"rand" Similar to "middle", but selects a random frame within each interval instead of the middle frame Increases coverage diversity across video content max_num_frames, min_num_frames

Performance Considerations

  • Processing time increases with frame count. Balance min_num_frames and max_num_frames to optimize speed vs. quality
  • For "middle" and "rand" methods, ensure min_num_frames < max_num_frames (default is 64)

Sampling Information

When return_sampling_info=True, the response includes a dictionary with the following sampling details:

Key Data Type Value
sampling_method str User selected sampling method
fps float Input video FPS
duration float Input video duration in seconds
n_video_frames int Number of input video frames
min_num_frames int User-defined minimum number of frames
max_num_frames int User-defined maximum number of frames
n_sample_frames int Actual number of sampled frames
frame_indices list Selected frame indices
frame_seconds list Selected frame seconds

Example

Input:

  • Video duration: 21.56 seconds
  • FPS: 25
  • Total frames: 539
  • sampling_method: "duration"
  • min_num_frames: 64
  • max_num_frames: 512

Output (sampling_info):

{
  "sampling_method": "duration",
  "fps": 25.0,
  "duration": 21.56,
  "n_video_frames": 539,
  "min_num_frames": 64,
  "max_num_frames": 512,
  "n_sample_frames": 64,
  "frame_indices": [3, 11, 20, 28, 37, 45, 53, "...", 525, 534],
  "frame_seconds": [0.1, 0.4, 0.8, 1.1, 1.5, 1.8, 2.1, "...", 21.0, 21.4]
}