Decord2

Warnings

• breaking Version 2.0.0 introduced significant updates to underlying dependencies, including FFmpeg 8.0 (from 7.x) and CUDA 13.x (from 12.x). Projects building from source or with specific local FFmpeg/CUDA installations may encounter build failures or runtime issues if not updated to compatible versions.
  Fix: Ensure your FFmpeg and CUDA installations are compatible with Decord2 v2.0.0 and later. For source builds, explicitly specify paths or versions during `cmake` configuration (e.g., `-DFFMPEG_DIR=/path/to/ffmpeg`).
• gotcha Achieving GPU acceleration requires a source build of Decord2 with CUDA enabled, which can be complex due to dependency linking (e.g., `libnvcuvid.so` on Linux). Pre-built wheels for PyPI are typically CPU-only unless specific CUDA versions are explicitly indicated (e.g., `decord2-cu130`).
  Fix: For GPU, follow the detailed source build instructions in the GitHub README, ensuring all system dependencies (FFmpeg, CUDA toolkit, CMake) are correctly installed and linked. Verify `libnvcuvid.so` is discoverable or explicitly linked if errors occur.
• gotcha When using `decord` (the original project, which `decord2` is forked from) with deep learning frameworks that employ multiprocessing data loaders (e.g., PyTorch `DataLoader` with `num_workers > 0`), users have reported issues with the process hanging or deadlocking. This indicates potential concurrency issues in the underlying C++ components.
  Fix: If experiencing hangs with multiprocessing, try setting `num_workers=0` in your data loader to isolate the issue. Investigate if the specific version of Decord2 has known patches or workarounds for multithreading stability, or consider using alternative video loading strategies within your data pipeline.
• gotcha Videos with imprecise or corrupted metadata (e.g., incorrect duration) can lead to issues with accurate frame counting or random access operations, potentially yielding incorrect frames or unexpected behavior, especially in older versions of the underlying Decord library.
  Fix: Ensure video files have correct and complete metadata if possible. Decord aims for robustness, but problematic files may still cause issues. Validate frame content, especially when performing random access or dealing with videos from unreliable sources.

Install

• pip install decord2 CPU-only installation
• pip install decord2[cu130] # Example for CUDA 13.0, check available wheels for your CUDA version GPU (CUDA) installation via wheels (if available)
• git clone --recursive https://github.com/johnnynunez/decord2.git cd decord2 mkdir build && cd build cmake .. -DUSE_CUDA=ON -DCMAKE_BUILD_TYPE=Release # Or -DUSE_CUDA=0 for CPU make cd ../python pip install . Source installation (required for custom GPU setups or specific FFmpeg versions)

Imports

• VideoReader

  from decord import VideoReader

  Main class for video file access
• cpu

  from decord import cpu

  Context for CPU processing
• gpu

  from decord import gpu

  Context for GPU processing (requires GPU-enabled installation)

Quickstart

Initialize a `VideoReader` to load frames from a video file. This example demonstrates accessing individual frames, slicing a batch of frames, and retrieving frames by specific indices. It defaults to CPU context but can be switched to GPU if the library is installed with CUDA support.

import os
import numpy as np
from decord import VideoReader, cpu

# Create a dummy video file for demonstration
# In a real scenario, you would have an actual video file
dummy_video_path = 'dummy_video.mp4'
# For a real application, ensure ffmpeg is installed and generate a simple video:
# import subprocess
# try:
#     subprocess.run(['ffmpeg', '-f', 'lavfi', '-i', 'testsrc=s=1280x720:r=30', '-vframes', '30', dummy_video_path], check=True)
# except FileNotFoundError:
#     print('FFmpeg not found. Cannot create dummy video.')
#     print('Please replace "dummy_video.mp4" with a path to an actual video file.')
#     exit()

# Placeholder for a real video file
# Assume 'your_video.mp4' exists or create one as above
video_file = 'your_video.mp4' # Replace with your video file path

# Initialize VideoReader with CPU context
# Use 'cpu(0)' for the first CPU context
# For GPU, use 'gpu(0)' if installed with GPU support
try:
    vr = VideoReader(video_file, ctx=cpu(0))
    print(f"Successfully opened video: {video_file}")
    print(f"Number of frames: {len(vr)}")

    # Access a single frame by index
    frame_0 = vr[0].asnumpy()
    print(f"Shape of first frame: {frame_0.shape}") # (H, W, C)

    # Access a batch of frames (e.g., frames 10 to 20)
    frames_batch = vr[10:20].asnumpy()
    print(f"Shape of frames batch: {frames_batch.shape}") # (N, H, W, C)

    # Access frames at specific indices
    random_frames = vr.get_batch([5, 15, 25]).asnumpy()
    print(f"Shape of random frames batch: {random_frames.shape}") # (N, H, W, C)

except Exception as e:
    print(f"Error processing video: {e}")
    print("Please ensure 'your_video.mp4' exists and is a valid video file.")
    print("You may also need to install FFmpeg on your system if installing from source.")