Implementation:NVIDIA DALI Fn Readers Video

Knowledge Sources	NVIDIA DALI
Domains	Video_Processing, GPU_Computing, Data_Loading
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete GPU-accelerated video reader operator for decoding compressed video files into frame sequence tensors, provided by the NVIDIA DALI library.

Description

fn.readers.video is a DALI pipeline operator that reads compressed video files (e.g., MP4 containers) and decodes them directly on the GPU using NVIDIA's hardware video decoder (NVDEC). It produces fixed-length sequences of consecutive video frames as GPU-resident tensors, ready for downstream processing within the DALI pipeline.

The operator accepts a list of video file paths and, for each pipeline iteration, yields a batch of frame sequences. Each sequence contains sequence_length consecutive frames from a single video file. When random_shuffle is enabled, the operator randomly selects which video file and which starting frame to read from, providing stochastic data access essential for training. The initial_fill parameter controls the size of the internal prefetch buffer: before the first output, the operator pre-decodes this many sequences to populate a reservoir from which random selections are drawn.

The output tensor has shape [sequence_length, H, W, 3] in FHWC layout, where H and W are determined by the video resolution. When normalized=False and dtype=types.UINT8, pixel values are in the standard [0, 255] integer range. The pad_last_batch=True option ensures that the final batch of each epoch is padded to the full batch size, preventing shape mismatches in downstream operations.

The name parameter assigns an identifier to the reader for epoch size queries (pipeline.epoch_size("Reader")) and for use with DALIGenericIterator's reader_name parameter.

Usage

Use fn.readers.video as the first operator in a DALI pipeline when the training data consists of compressed video files and GPU-accelerated decoding is desired. It replaces CPU-based video reading (e.g., OpenCV VideoCapture) with a hardware-decoded, pipeline-integrated solution.

Code Reference

Source Location

Repository: NVIDIA DALI
File: docs/examples/use_cases/video_superres/dataloading/dataloaders.py (lines 18-29)

Signature

fn.readers.video(
    device="gpu",
    filenames=files,
    sequence_length=sequence_length,
    normalized=False,
    random_shuffle=True,
    image_type=types.RGB,
    dtype=types.UINT8,
    initial_fill=16,
    pad_last_batch=True,
    name="Reader"
)

Import

import nvidia.dali.fn as fn
import nvidia.dali.types as types

I/O Contract

Inputs

Name	Type	Required	Description
device	str	Yes	Execution device; "gpu" for hardware-accelerated decoding via NVDEC
filenames	list of str	Yes	Paths to MP4 video files to read
sequence_length	int	Yes	Number of consecutive frames per output sequence
normalized	bool	No	If True, normalize pixel values to [0.0, 1.0]; defaults to False
random_shuffle	bool	No	If True, randomly shuffle sequences across files; defaults to True
image_type	types.DALIImageType	No	Color space of output frames; defaults to types.RGB
dtype	types.DALIDataType	No	Output data type; defaults to types.UINT8
initial_fill	int	No	Number of sequences to prefetch into the shuffle buffer; defaults to 16
pad_last_batch	bool	No	If True, pad the last batch to full batch size; defaults to True
name	str	No	Operator name for epoch size queries and iterator binding

Outputs

Name	Type	Description
images	DALI TensorGPU	GPU-resident video tensor with shape [sequence_length, H, W, 3] in FHWC layout, dtype UINT8

Usage Examples

Basic Video Reader Pipeline

from nvidia.dali.pipeline import pipeline_def
import nvidia.dali.fn as fn
import nvidia.dali.types as types

@pipeline_def
def create_video_reader_pipeline(sequence_length, files, crop_size):
    images = fn.readers.video(
        device="gpu",
        filenames=files,
        sequence_length=sequence_length,
        normalized=False,
        random_shuffle=True,
        image_type=types.RGB,
        dtype=types.UINT8,
        initial_fill=16,
        pad_last_batch=True,
        name="Reader"
    )
    return images

Instantiation Within DALILoader

import os

container_files = os.listdir(file_root)
container_files = [file_root + '/' + f for f in container_files]

pipeline = create_video_reader_pipeline(
    batch_size=4,
    sequence_length=3,
    num_threads=2,
    device_id=0,
    files=container_files,
    crop_size=[256, 256]
)
pipeline.build()
epoch_size = pipeline.epoch_size("Reader")

Related Pages

Implements Principle

Principle:NVIDIA_DALI_Video_Reading

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment