{"id":1988,"library":"decord","title":"Decord Video Loader","description":"Decord is an efficient and user-friendly Python library for loading and processing video data. It provides fast, GPU-accelerated video frame access, leveraging underlying decoders like FFmpeg and NVIDIA's NVDEC. Decord supports various video formats, integrates seamlessly with deep learning frameworks like PyTorch and TensorFlow, and offers features such as random frame access and batch reading. The current version, 0.6.0, includes stability fixes and introduces an `AudioReader` for audio frame access within its wheels. It maintains an active development pace with frequent bug fixes and performance improvements.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/dmlc/decord","tags":["video","media","ffmpeg","gpu","machine-learning","video-processing","computer-vision"],"install":[{"cmd":"pip install decord","lang":"bash","label":"Install Decord"}],"dependencies":[],"imports":[{"symbol":"VideoReader","correct":"from decord import VideoReader"},{"note":"Requires Decord v0.6.0 or newer.","symbol":"AudioReader","correct":"from decord import AudioReader"},{"note":"Context functions (`cpu`, `gpu`) are directly under the `decord` package.","wrong":"from decord.cpu import cpu","symbol":"cpu","correct":"from decord import cpu"},{"note":"Context functions (`cpu`, `gpu`) are directly under the `decord` package.","wrong":"from decord.gpu import gpu","symbol":"gpu","correct":"from decord import gpu"},{"note":"Used for configuring Decord's internal logging level.","symbol":"DECORD_LOG_STREAM","correct":"from decord import DECORD_LOG_STREAM"}],"quickstart":{"code":"import os\nfrom decord import VideoReader, cpu, gpu, AudioReader\nfrom decord import DECORD_LOG_STREAM, logging\n\n# Configure Decord's logging level to suppress verbose FFmpeg messages\nDECORD_LOG_STREAM.set_level(logging.ERROR)\n\n# --- Quickstart requires a video file ---\n# Replace 'path/to/your/video.mp4' with an actual video file path.\n# You can also set this via an environment variable for easier testing:\n# export DECORD_VIDEO_PATH=\"/path/to/your/video.mp4\"\nvideo_file_path = os.environ.get('DECORD_VIDEO_PATH', 'path/to/your/video.mp4')\n\nif not os.path.exists(video_file_path):\n    print(f\"WARNING: Video file not found at '{video_file_path}'. Please provide a valid path.\")\n    print(\"Skipping Decord quickstart execution.\")\nelse:\n    try:\n        print(f\"Processing video: {video_file_path}\")\n        # 1. Initialize VideoReader with CPU context\n        # Use gpu(0) for GPU context if available and Decord is built with CUDA support.\n        vr = VideoReader(video_file_path, ctx=cpu(0))\n\n        # Get video properties\n        print(f\"Total frames: {len(vr)}\")\n        print(f\"Frame rate: {vr.get_avg_fps()} fps\")\n        print(f\"Video resolution: {vr.width}x{vr.height}\")\n\n        # Read a single frame (e.g., the first frame)\n        frame_0 = vr[0].asnumpy() # Returns a NumPy array (H, W, C) in RGB\n        print(f\"Shape of first frame (NumPy): {frame_0.shape}\")\n\n        # Read a batch of frames (e.g., frames at index 10, 20, 30)\n        if len(vr) > 30:\n            frames_batch = vr.get_batch([10, 20, 30]).asnumpy() # Returns (N, H, W, C)\n            print(f\"Shape of batch frames (NumPy): {frames_batch.shape}\")\n        else:\n            print(\"Video too short to get a batch of frames.\")\n\n        # Iterate through frames (e.g., first 5 frames)\n        print(\"\\nIterating through first 5 frames:\")\n        for i, frame in enumerate(vr):\n            if i >= 5:\n                break\n            print(f\"  Frame {i} shape: {frame.shape}\")\n\n        # 2. Initialize AudioReader (available from Decord v0.6.0+)\n        # Requires the video file to contain audio tracks.\n        if hasattr(decord, 'AudioReader'):\n            try:\n                ar = AudioReader(video_file_path, ctx=cpu(0))\n                print(f\"\\nTotal audio samples (frames): {len(ar)}\")\n\n                # Read a chunk of audio samples (e.g., first 1024 samples)\n                audio_chunk = ar[:1024].asnumpy() # Returns (Samples, Channels)\n                print(f\"Shape of first audio chunk (NumPy): {audio_chunk.shape}\")\n            except Exception as e:\n                print(f\"Could not initialize AudioReader: {e}. Ensure video has audio tracks.\")\n        else:\n            print(\"\\nAudioReader not available in this Decord version (requires v0.6.0+).\")\n\n    except Exception as e:\n        print(f\"An error occurred during Decord processing: {e}\")\n        print(\"Common issues include corrupted video files, missing FFmpeg dependencies, or incorrect Decord installation.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always pass a context object like `ctx=cpu(0)` or `ctx=gpu(0)` to the `VideoReader` or `AudioReader` constructor.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to the latest `decord` version: `pip install --upgrade decord`.","message":"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.","severity":"deprecated","affected_versions":"<0.5.0"},{"fix":"Ensure you are using Decord `v0.6.0` or newer to use `AudioReader` functionality. Upgrade using `pip install --upgrade decord`.","message":"`AudioReader` was introduced in Decord `v0.6.0`. Attempting to import or use `AudioReader` in older versions will result in an `ImportError` or `AttributeError`.","severity":"gotcha","affected_versions":"<0.6.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.5.1, 0.5.2, 0.6.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}