Stream video frames to directory

Decode video frames directly from a raw stream using PyAV — bypasses server-side metadata requirements.

Supervisely SDK version ≥ v6.73.578

Introduction

Use stream_video_frames_to_dir to decode frames directly from the raw video stream using PyAV without requiring server-side metadata.

The standard api.video.frame.download_path requires video metadata (frame count, timestamps) to be pre-calculated on the server. If that metadata has not been computed yet, the call will fail. stream_video_frames_to_dir bypasses this limitation by opening the raw video stream directly with PyAV and demuxing it locally.

Performance depends on the video and the requested frame range. Use this function when server-side metadata is unavailable, not as a general-purpose speed optimization.

How to debug this tutorial

Step 1. Prepare ~/supervisely.env file with credentials. Learn more here.

Step 2. Set the required environment variables in local.env:

SERVER_ADDRESS=https://app.supervisely.com  # ⬅️ change value
API_TOKEN=your-token-here                   # ⬅️ change value
VIDEO_ID=12345                              # ⬅️ change value

Step 3. Run the script below.

Import libraries

Init API client

Save frames to directory

Download frames 0–9 (first 10 frames) and save as PNG files:

Output:

Files are named frame_<index:06d>.<ext>. The output directory is created automatically if it does not exist.

Progress bar

Pass a progress_cb callable — it is called with 1 after each frame is saved:

Decoding progress

Pass show_decoding_progress=True to display low-level tqdm progress bars for the demuxing phase (building the PTS map) and, for B-frame videos, the full-decode phase. Both bars count packets and are independent of progress_cb:

Tuning parallelism and memory

Two parameters control the internal pipeline:

  • max_write_workers (default 4) — number of threads writing frames to disk in parallel. Increase on fast NVMe storage.

  • queue_maxsize (default 32) — size of the decode prefetch buffer in frames. Peak RAM ≈ (queue_maxsize + max_write_workers + 1) × frame_bytes. Reduce if you hit OOM errors.

Async version

Use async_stream_video_frames_to_dir inside an async function:

Function reference

stream_video_frames_to_dir

Returns a List[str] of absolute paths to saved frame files.

async_stream_video_frames_to_dir

Same signature as stream_video_frames_to_dir (including max_write_workers, queue_maxsize, and show_decoding_progress), but async. Returns List[str].

async_stream_video_frames

Async generator. Yields (frame_index: int, image: np.ndarray) tuples. Image is in RGB format.

Last updated