{"id":3296,"library":"torchcodec","title":"TorchCodec","description":"TorchCodec is a Python library developed by PyTorch that provides efficient video and audio decoding and encoding capabilities, tightly integrated with PyTorch tensors. It aims to simplify video and audio processing for machine learning workflows, supporting both CPU and GPU operations. The current version is 0.11.0, with new releases occurring approximately every 1-2 months.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/pytorch/torchcodec","tags":["video","audio","pytorch","ffmpeg","decoding","encoding","multimedia","machine-learning"],"install":[{"cmd":"pip install torchcodec","lang":"bash","label":"Stable Release"},{"cmd":"conda install torchcodec -c conda-forge","lang":"bash","label":"Conda for Windows GPU"}],"dependencies":[{"reason":"Core PyTorch tensor integration; specific PyTorch versions are compatible with specific TorchCodec releases.","package":"torch","optional":false},{"reason":"Backend for video and audio processing; must be installed and accessible in the system PATH.","package":"ffmpeg","optional":false}],"imports":[{"symbol":"VideoDecoder","correct":"from torchcodec.decoders import VideoDecoder"},{"symbol":"AudioDecoder","correct":"from torchcodec.decoders import AudioDecoder"},{"symbol":"VideoEncoder","correct":"from torchcodec.encoders import VideoEncoder"},{"symbol":"AudioEncoder","correct":"from torchcodec.encoders import AudioEncoder"},{"symbol":"transforms","correct":"from torchcodec.transforms import Resize, RandomCrop"},{"note":"Used to enable the experimental faster CUDA decoder backend.","symbol":"set_cuda_backend","correct":"from torchcodec.decoders import set_cuda_backend"}],"quickstart":{"code":"import torchcodec\nfrom torchcodec.decoders import VideoDecoder\nimport os\n\n# Replace 'path/to/your/video.mp4' with the actual path to your video file.\n# For demonstration, we use an environment variable or a placeholder.\nvideo_path = os.environ.get('TORCHCODEC_DEMO_VIDEO', 'path/to/your/video.mp4')\n\ntry:\n    decoder = VideoDecoder(video_path)\n    print(f\"VideoDecoder initialized for: {video_path}\")\n    print(f\"Video width: {decoder.width}\")\n    print(f\"Video height: {decoder.height}\")\n    \n    # Uncomment the following lines to decode frames:\n    # frames = decoder.next_chunk(num_frames=10)\n    # print(f\"Decoded 10 frames with shape: {frames.shape}\")\n\nexcept FileNotFoundError:\n    print(f\"Error: Video file not found at '{video_path}'. Please replace with a valid path.\")\nexcept Exception as e:\n    print(f\"An error occurred during decoder initialization or usage: {e}\")\nprint(\"\\nTo decode frames, ensure a valid video_path is provided and uncomment the 'frames = decoder.next_chunk...' line.\")","lang":"python","description":"This quickstart demonstrates how to initialize a `VideoDecoder` for a given video file path. It prints basic video metadata and provides commented-out lines for decoding frames. Remember to replace the placeholder `video_path` with an actual video file on your system."},"warnings":[{"fix":"Always check the official TorchCodec release notes or documentation for the compatible PyTorch version. For example, v0.11.0 is compatible with torch 2.10.","message":"TorchCodec versions are often tied to specific PyTorch versions. Installing an incompatible PyTorch version can lead to runtime errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"This issue was largely resolved in v0.8.1. Ensure you are on v0.8.1 or later. If using the 'beta' backend, make sure your CUDA installation is complete and `libnvcuvid.so` is accessible.","message":"When using the 'beta' CUDA backend (available from v0.8.0 onwards) on certain systems, a hard dependency on `libnvcuvid.so` might cause import issues if the library is not present.","severity":"gotcha","affected_versions":"0.8.0"},{"fix":"Upgrade to TorchCodec v0.9.1 or later. Ensure FFmpeg is correctly installed and its binaries are added to your system's PATH environment variable.","message":"Users on Windows might encounter issues where FFmpeg cannot be found by TorchCodec, even if installed.","severity":"gotcha","affected_versions":"Prior to 0.9.1, particularly on Windows."},{"fix":"Consider installing TorchCodec via `conda install torchcodec -c conda-forge` if you are on Windows and plan to use GPU acceleration.","message":"For GPU decoding on Windows, `pip install` might not always provide the necessary CUDA-enabled binaries directly. The `conda-forge` channel often provides a more stable setup for GPU support.","severity":"gotcha","affected_versions":"All versions, specifically for Windows GPU users."},{"fix":"Call `torchcodec.decoders.set_cuda_backend(\"beta\")` before initializing your `VideoDecoder` to leverage the performance improvements.","message":"The faster CUDA decoder backend, introduced as 'beta' in v0.8.0, needs to be explicitly enabled for improved performance.","severity":"gotcha","affected_versions":"0.8.0 and later when using CUDA decoding."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}