For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Python function

decode_video_frames

decode_video_frames()

max.pipelines.context.decode_video_frames(source, *, num_frames=None, target_fps=None, sampling='uniform', start_frame=None, end_frame=None, min_frames=1, max_frames=None, rounding='round', max_decoded_bytes=None, default_fps=30.0, threads=None, sample_indices=None)

source

Decodes a subsampled set of frames from a video.

Which frames to keep is decided before any pixels are produced, and the decode fetches only those, selecting each by its presentation timestamp so a damaged or variable-rate stream cannot silently yield the wrong frame. Peak memory is the sampled frames, bounded by max_decoded_bytes.

A container header that omits its frame count triggers a counting decode that retains no pixels; one that overcounts is corrected against the frames the decode actually produced.

Parameters:

• source (str | bytes) – The video to decode.
• num_frames (int | None) – Sample this many frames. Mutually exclusive with target_fps; when both are None every frame in range is kept, subject to the caps.
• target_fps (float | None) – Sample the clip as if it ran at this frame rate. Never upsamples past the source rate.
• sampling (Literal['uniform', 'walk']) – How target_fps selects frames – "uniform" spreads the resulting count evenly, "walk" guarantees the spacing and the final frame.
• start_frame (int | None) – First source frame eligible for sampling.
• end_frame (int | None) – Last source frame eligible for sampling.
• min_frames (int) – Never sample fewer than this many frames.
• max_frames (int | None) – Model-specific ceiling on the sampled count.
• rounding (Literal['round', 'floor']) – How to land fractional sample positions on real frame indices, for "uniform" sampling. Pick whichever matches the model’s reference implementation.
• max_decoded_bytes (int | None) – Ceiling on the decoded footprint of the sampled frames. The sampled count is reduced to fit.
• default_fps (float) – Frame rate assumed when the container declares none.
• threads (int | None) – Decode worker count; defaults to MODULAR_VIDEO_DECODE_THREADS or 16.
• sample_indices (Callable[[int, float, int | None], Sequence[int]] | None) – A model’s own frame-selection rule, for a reference whose rule none of the arguments above express. Called with the source frame count, the frame rate, and the most frames the decode may keep – max_frames and max_decoded_bytes combined, or None when neither applies – and returns ascending source indices, which may repeat. Replaces num_frames, target_fps and the other sampling arguments.

Returns:

The sampled frames, their source indices, and the stream metadata.

Raises:

InputError – If the source is not a decodable video, contains no decodable frames, or a single frame exceeds max_decoded_bytes.

Return type:

SampledVideo