VideoPacketDecoder

class torchcodec.decoders.VideoPacketDecoder(*args, **kwargs)

Decodes the compressed Packets of one video stream into RawFrames.

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

You should not build one yourself: VideoStream.make_decoder() is what creates it. Frames come out on the device given there.

Feed it one packet at a time, and drain it at the end:

demuxer = Demuxer("video.mp4")
decoder = demuxer.streams[0].make_decoder()

for packet in demuxer:
    for raw_frame in decoder.decode(packet):
        ...
for raw_frame in decoder.drain():
    ...

It is stateful. It holds the codec’s reference-frame buffer, so it expects the packets of its own stream, in the order the demuxer produced them.

Examples using VideoPacketDecoder:

Build your own decoding pipeline

Build your own decoding pipeline

Low-level APIs and CUDA streams synchronization

Low-level APIs and CUDA streams synchronization

Raw frames and raw audio samples

Raw frames and raw audio samples

decode(packet: Packet) → list[RawFrame]

Send one Packet to the codec and return the RawFrames that are ready.

This can return zero, one, or more than one RawFrame. What comes back is not the decoding of the packet you just passed: a codec that is buffering B-frames, or still priming itself, will emit what it owes you on a later call.

Parameters:

packet (Packet) – A packet of this decoder’s own stream.

Returns:

The possibly empty list of RawFrames that the codec has ready, in presentation order.

Raises:

RuntimeError – If this decoder has been drained, or if the demuxer seeked without it being reset() afterwards.

drain() → list[RawFrame]

Tell the codec the stream has ended, and return the RawFrames it was still holding.

Skipping this loses the tail of the stream. A drained decoder refuses any further packet; reset() makes it usable again.

Returns:

The possibly empty list of RawFrames that the codec was still holding, in presentation order.

reset() → None

Drop the codec’s buffered state and start over.

Needed after a Demuxer.seek(), and after drain().