Support for Passing Codec-Specific Options

TorchCodec currently provides no way to forward codec-specific parameters to libavcodec when initializing a decoder via avcodec_open2. This limits advanced use cases that require control over backend behavior, decoding quality, or performance tuning.

TorchCodec embeds FFmpeg's libavcodec into its native C++ backend (_core). When a video stream is added, VideoStreamOptions is populated by custom_ops.cpp (Python binding) with preset fields:

Width, height

Thread count

Dimension order

Optional color-conversion library

Target device

These are passed to SingleStreamDecoder::addVideoStream, which sets up the decoder and calls:

avcodec_open2(codec_context, codec, /* options = */ nullptr);

Since no AVDictionary is passed, libavcodec uses default settings. This prevents codecs from receiving extra options.

Proposed Solution

To enable codec-specific parameter forwarding:

Extend VideoStreamOptions
Add new fields (or a generic options dictionary) for key-value parameters.

Update custom_ops.cpp
Modify the Python binding to accept and forward these additional options from Python to C++.

Update SingleStreamDecoder

    Construct an AVDictionary* from the new options.

    Pass it to avcodec_open2() as the third parameter.

Benefit

This enables users to:

Fine-tune codec behavior

Make TorchCodec more extensible and FFmpeg-aligned

Willing to Contribute

Yes – I’m interested in implementing this feature and can start with guidance or approval from maintainers.

Start with VideoStreamOptions population in custom_ops.cpp and follow it into SingleStreamDecoder::addVideoStream. Trace the existing avcodec_open2 call, then define how Python key-value options become an AVDictionary and verify that codec-specific options are forwarded when the decoder opens.