Decord Video Loader

Warnings

• gotcha Both `VideoReader` and `AudioReader` require an explicit context (e.g., `ctx=cpu(0)` or `ctx=gpu(0)`) during initialization. Forgetting this will result in a `RuntimeError`.
  Fix: Always pass a context object like `ctx=cpu(0)` or `ctx=gpu(0)` to the `VideoReader` or `AudioReader` constructor.
• gotcha While `pip install decord` often includes GPU-enabled wheels, actual GPU acceleration depends on your system's CUDA setup and if a compatible wheel was installed. If `gpu(0)` fails, you might need to build Decord from source for your specific CUDA version or verify GPU support is compiled into your installed package.
  Fix: Check `decord` installation logs for CUDA support. If issues persist, consider installing a specific `decord-gpu` variant if available, or follow instructions for building from source for your CUDA version.
• deprecated Versions of Decord prior to `v0.5.0` had known performance issues (e.g., slow frame access) and could hang or crash when processing broken or malformed video files. It is highly recommended to upgrade to `v0.5.0` or newer for improved stability and performance.
  Fix: Upgrade to the latest `decord` version: `pip install --upgrade decord`.
• gotcha `AudioReader` was introduced in Decord `v0.6.0`. Attempting to import or use `AudioReader` in older versions will result in an `ImportError` or `AttributeError`.
  Fix: Ensure you are using Decord `v0.6.0` or newer to use `AudioReader` functionality. Upgrade using `pip install --upgrade decord`.
• breaking Several patch versions in `v0.5.x` and `v0.6.0` addressed issues with PyPI wheels (e.g., incorrect RECORD files leading to broken `pip` installations). Users might experience `pip` errors during installation or corrupted packages after installation. A clean reinstall might be needed.
  Fix: If installation issues occur, try `pip uninstall decord` and then `pip install --upgrade decord` to ensure the latest fixed wheel (if available) is installed. Consult the GitHub repository's issues for specific workarounds if problems persist on your platform.

Install

• pip install decord Install Decord

Imports

• VideoReader

  from decord import VideoReader

• AudioReader

  from decord import AudioReader

  Requires Decord v0.6.0 or newer.
• cpu

  from decord import cpu

  Context functions (`cpu`, `gpu`) are directly under the `decord` package.
• gpu

  from decord import gpu

  Context functions (`cpu`, `gpu`) are directly under the `decord` package.
• DECORD_LOG_STREAM

  from decord import DECORD_LOG_STREAM

  Used for configuring Decord's internal logging level.

Quickstart

This quickstart demonstrates how to initialize `VideoReader` and `AudioReader` (v0.6.0+), access video frames by index, retrieve batches of frames, and iterate through frames. It uses `cpu(0)` for context, but `gpu(0)` can be used if a CUDA-enabled Decord build is installed and a GPU is available. Remember to replace `path/to/your/video.mp4` with a real video file.

import os
from decord import VideoReader, cpu, gpu, AudioReader
from decord import DECORD_LOG_STREAM, logging

# Configure Decord's logging level to suppress verbose FFmpeg messages
DECORD_LOG_STREAM.set_level(logging.ERROR)

# --- Quickstart requires a video file ---
# Replace 'path/to/your/video.mp4' with an actual video file path.
# You can also set this via an environment variable for easier testing:
# export DECORD_VIDEO_PATH="/path/to/your/video.mp4"
video_file_path = os.environ.get('DECORD_VIDEO_PATH', 'path/to/your/video.mp4')

if not os.path.exists(video_file_path):
    print(f"WARNING: Video file not found at '{video_file_path}'. Please provide a valid path.")
    print("Skipping Decord quickstart execution.")
else:
    try:
        print(f"Processing video: {video_file_path}")
        # 1. Initialize VideoReader with CPU context
        # Use gpu(0) for GPU context if available and Decord is built with CUDA support.
        vr = VideoReader(video_file_path, ctx=cpu(0))

        # Get video properties
        print(f"Total frames: {len(vr)}")
        print(f"Frame rate: {vr.get_avg_fps()} fps")
        print(f"Video resolution: {vr.width}x{vr.height}")

        # Read a single frame (e.g., the first frame)
        frame_0 = vr[0].asnumpy() # Returns a NumPy array (H, W, C) in RGB
        print(f"Shape of first frame (NumPy): {frame_0.shape}")

        # Read a batch of frames (e.g., frames at index 10, 20, 30)
        if len(vr) > 30:
            frames_batch = vr.get_batch([10, 20, 30]).asnumpy() # Returns (N, H, W, C)
            print(f"Shape of batch frames (NumPy): {frames_batch.shape}")
        else:
            print("Video too short to get a batch of frames.")

        # Iterate through frames (e.g., first 5 frames)
        print("\nIterating through first 5 frames:")
        for i, frame in enumerate(vr):
            if i >= 5:
                break
            print(f"  Frame {i} shape: {frame.shape}")

        # 2. Initialize AudioReader (available from Decord v0.6.0+)
        # Requires the video file to contain audio tracks.
        if hasattr(decord, 'AudioReader'):
            try:
                ar = AudioReader(video_file_path, ctx=cpu(0))
                print(f"\nTotal audio samples (frames): {len(ar)}")

                # Read a chunk of audio samples (e.g., first 1024 samples)
                audio_chunk = ar[:1024].asnumpy() # Returns (Samples, Channels)
                print(f"Shape of first audio chunk (NumPy): {audio_chunk.shape}")
            except Exception as e:
                print(f"Could not initialize AudioReader: {e}. Ensure video has audio tracks.")
        else:
            print("\nAudioReader not available in this Decord version (requires v0.6.0+).")

    except Exception as e:
        print(f"An error occurred during Decord processing: {e}")
        print("Common issues include corrupted video files, missing FFmpeg dependencies, or incorrect Decord installation.")