ColorConverter

class torchcodec.decoders.ColorConverter(device: str | device | None = None, output_dtype: dtype | Literal['auto'] = torch.uint8)

Turn a RawFrame (typically YUV) into an RGB Frame.

This is a low-level API: for straightforward decoding, use VideoDecoder instead.

converter = ColorConverter()

for packet in demuxer:
    for raw_frame in packet_decoder.decode(packet):
        frame = converter.convert(raw_frame)
        frame.data  # uint8 [3, height, width], RGB

Unlike the other stages this one isn’t tied to a specific video stream. Everything it needs (dimensions, pixel format, color space, rotation) comes from the RawFrame itself, so the same converter instance can process frames from any video stream, provided that they share the same device.

Parameters:

• device (str or torch.device, optional) – The device to convert on. If None (default), the current default device is used (see torch.set_default_device). It has to be the device the frames are already on, i.e. it must match what was passed to the VideoPacketDecoder that produced the RawFrame.

• output_dtype (torch.dtype or "auto", optional) – torch.uint8 (default) for values in [0, 255], torch.float32 for [0, 1], or "auto" for uint8 from 8-bit sources and float32 from deeper ones. Since this block isn’t tied to a stream, "auto" is resolved per frame rather than once per video, so feeding it a mix of SDR and HDR frames gives you a mix of dtypes.

Examples using ColorConverter:

Build your own decoding pipeline

Build your own decoding pipeline

Low-level APIs and CUDA streams synchronization

Low-level APIs and CUDA streams synchronization

Multi-threaded decoding pipelines

Multi-threaded decoding pipelines

Raw frames and raw audio samples

Raw frames and raw audio samples

convert(raw_frame: RawFrame) → Frame

Convert one RawFrame to an RGB Frame.

RawFrame.rotation is applied, so the output is upright and matches what a VideoDecoder gives you.

If you run this on a different CUDA stream than the one the frame was decoded on, refer to Low-level APIs and CUDA streams synchronization for pitfalls and how to avoid them.

Parameters:

raw_frame (RawFrame) – The frame to convert. It has to be on this converter’s device.

Returns:

The RGB [3, height, width] frame in the converter’s output_dtype.

Raises:

RuntimeError – If the frame is not on this converter’s device.