TorchCodec 0.9.1

TorchCodec 0.9.1 is out! This version is compatible with torch 2.9.

This is primarily a bug-fix release which should resolve issues on Windows where FFmpeg couldn't be found.

TorchCodec 0.9

TorchCodec 0.9 is out! This comes with a new highly requested feature: video encoding!

Video Encoding

Video encoding on CPU is available. It provides a simple API to encode video frames to tensors or bytes, and optionally enables a set of key parameters.

from torchcodec.encoders import VideoEncoder

encoder = VideoEncoder(frames=frame_tensor, frame_rate=frame_rate)

encoder.to_file(dest="output.mp4") # encode to mp4 file
encoded_bytes = encoder.to_tensor(format="mp4") # encode to tensor of bytes

Additionally, several key parameters are exposed to control the encoded video:

# Utilize a specific codec, choose a pixel format to control quality
encoder.to_file(dest="output.mp4", codec="libx264", pixel_format="yuv420p")
 
# Set quality parameter `crf` to 0 for lossless encoding, use fast `preset`
encoded_bytes = encoder.to_tensor(format="mp4", crf=0, preset="fast")

Read more about the available features in the video encoding tutorial!

Enhancements

• This release adds support for Python 3.14!
• #989: Improved VideoDecoder metadata, enabling seek_mode=approximate for some videos with missing metadata.
• #1028: Enhanced video decoding speed up to 1.5x when decoding frames sequentially with seek_mode="approximate".
• #1078: Updated guidance on when to use approximate mode in the tutorial.

Bug fixes

• #1025: Fixed bug: passing device=None in VideoDecoder now uses the current torch device.

TorchCodec 0.8.1

We are releasing TorchCodec 0.8.1 which is bug-fix release, compatible with torch 2.9.

The fix

In 0.8 we introduced our new "beta" backend which is much faster than our existing CUDA decoder (try it!!). But we also introduced a hard dependency on libnvcuvid.so, which isn't always available on the users machine. This would cause issues when import torchcodec was run.

We have now removed the hard dependency on libnvcuvid.so: if it cannot be found at runtime, the VideoDecoder will gracefully fallback to the CPU. This should resolve a lot of the ongoing import torchcodec errors. We're working on exposing an API that allows the user to know whether they're falling back to the CPU.

Thanks again to @traversaro for the original diagnosis and for the help testing the fix on Windows!

Enhancement

We also added support for FFmpeg 8 on Windows - we now support FFmpeg 4, 5, 6, 7, and 8 across all platforms (Linux, MacOS and Windows).

TorchCodec 0.8

TorchCodec 0.8 is out, and is compatible with torch 2.9!

Faster GPU decoding!

Faster video decoding on GPU is available, with our new Beta CUDA backend! We have observed up to 3x speedups compared to our previous GPU decoding implementation, and up to 90% NVDEC utilization.

We are releasing it as a Beta feature that we will polish over time, but we are confident it is ready to use, and we are eager to hear your feedback! Eventually, this Beta backend will become the default.

To use it, you just need to specify the "beta" backend when creating the VideoDecoder instance:

from torchcodec.decoders import set_cuda_backend, VideoDecoder

with set_cuda_backend("beta"):
    dec = VideoDecoder("file.mp4", device="cuda")

# All existing methods are supported
batch = dec.get_frames_at(...)

Custom Frame Mappings

Video decoding now accepts pre-computed frame index data for faster VideoDecoder instantiation speeds, while maintaining exact frame seeking accuracy.

Read more about this feature in our tutorial!

Enhancements

• #935, #947 - Enabled compatibility with FFmpeg8 for Linux and Mac
• #899 - More robust support for 10-bit videos on CUDA.
• #915 - Added support for tensor indices in dec.get_frames_at(indices) and for timestamps in dec.get_frames_played_at(timestamps).

Bug fixes

• #901 - Fixed a rare floating point error in clips_at_regular_timestamps()

TorchCodec 0.7

TorchCodec 0.7 is out and it's compatible with torch 2.8!

Windows support

The main new feature is that TorchCodec now has BETA support for Windows! This is our most popular feature request to date. Windows users can try it out with pip install torchcodec for CPU, and use conda-forge for GPU support (thanks @traversaro !): conda install torchcodec -c conda-forge

This is currently in BETA support, so there may be rough edges. Let us know if you encounter any issue.

Enhancements

• #865 improves audio decoding coverage of the AudioDecoder on some wav files with FFmpeg 4

Bug fixes

This release also comes with a few bug fixes:

• #777 prevents silently wrong results for 10bit videos when decoding on the GPU. We'll be submitting more fixes for 10bit videos in the near future.
• #852 allows AudioEncoder.to_file() to accept a pathlib.Path instead of just a string
• #868 Fixes a stream synchronization issue between NVDEC (the decoder) and NPP (the color conversion). If you weren't explicitly specifying custom CUDA stream for decoding, this doesn't affect you.

TorchCodec 0.6.0

This version is the same as 0.5, but adds compatibility with the latest PyTorch 2.8.

TorchCodec 0.5

TorchCodec 0.5 is out! It is compatible with torch 2.7. This version comes with the highly requested feature: Audio Encoding!

Audio Encoding

You can now encode audio samples to a file or to raw bytes!

from torchcodec.encoders import AudioEncoder

encoder = AudioEncoder(samples=samples, sample_rate=sample_rate)

encoder.to_file("samples.mp3")  # encode to a file
encoded_bytes = encoder.to_tensor(format="mp3")  # encode to a tensor of bytes

Learn more in our tutorial.

Parallel video decoding

We added a new tutorial for workflows to enable parallel video decoding using multi-processing and multi-threading. Read more in our tutorial.

Additional features and improvements

• Added a field to the Stream Metadata struct to contain sample/pixel aspect ratio to support non-square pixels.

• Made changes to the VideoDecoder to be more resilient to missing metadata, specifically the number of frames in a stream or stream duration. It will use average FPS and other metadata to calculate these fields when they are missing.

Bug fixes

• A bug fix in VideoDecoder and AudioDecoder when they are instantiated from bytes or a Tensor: they now adopt the data representing the video to ensure the data's lifetime matches that of the decoder.

TorchCodec 0.4

TorchCodec 0.4 is out! It is a small release with:

• A new num_channels parameter to AudioDecoder, allowing you to directly specify whether you want to convert the audio to mono or stereo.
• A bug fix which fixes the time conversion in our time-based APIs, which used to be incorrect for some specific videos.
• A robustness improvement: TorchCodec is now able to decode poorly-encoded videos, when the PTS values are missing (it falls-back to DTS in that case). Previously, TorchCodec would fail on such videos.
• A bug fix in AudioDecoder.get_samples_played_in_range(): if stop_seconds was before the first sample's start, we would return all the samples. Now, we raise a loud error.
• A bug fix in AudioDecoder.get_samples_played_in_range() when start_seconds == stop_seconds: the shape of the output is now (num_channels, 0) instead of (0, 0).

TorchCodec 0.3

TorchCodec 0.3.0 is out! It comes with two new major features: Audio decoding, and Streaming.

Audio decoding

You can now decode audio streams from videos, or from audio files! The AudioDecoder looks a lot like the existing VideoDecoder:

from torchcodec.decoders import AudioDecoder

decoder = AudioDecoder(path_to_audio)
samples = decoder.get_all_samples()

print(samples)
# AudioSamples:
#  data (shape): torch.Size([2, 4297722])
#  pts_seconds: 0.02505668934240363
#  duration_seconds: 97.45401360544217
#  sample_rate: 44100

Lean more in our tutorial.

Streaming

You can now decode steaming videos and audio! That is, when files do not reside locally, TorchCodec now supports downloading only the data segments that are needed to decode the frames you care about. The API is generic and integrates nicely with existing file-like interfaces like fsspec and others.

Learn more in our tutorial.

---

Bug fixes

• VideoDecoder now accept a torch.device parameter (#607)
• Fix PTS of the first frame (#565)

TorchCodec 0.2.1

TorchCodec 0.2.1 is out! This version is compatible with pytorch 2.6. This is small release with two quality-of-life improvements:

• FFmpeg logs are deactivated, producing less verbose outputs.
• Compatibility with Google colab: GPU decoding now works with FFmpeg 4 (in addition to 5, 6, 7), which is the default version supported by Google Colab.