VideoStream

class torchcodec.decoders.VideoStream(demuxer: Demuxer, index: int)

A video stream followed by a Demuxer.

You should not build one yourself: a Demuxer creates one for you.

Variables:

index (int) – The stream’s index within the container, absolute across all media types. This is what a Packet’s stream_index can be compared against.

Examples using VideoStream:

Build your own decoding pipeline

Build your own decoding pipeline

make_decoder(device: str | device | None = None, *, num_ffmpeg_threads: int = 1) → VideoPacketDecoder

Build the VideoPacketDecoder for this stream.

Parameters:

• device (str or torch.device, optional) – The device to decode on (cpu or CUDA). If None (default), the current default device is used (see torch.set_default_device).

• num_ffmpeg_threads (int, optional) – The number of threads to use for CPU decoding. This has no effect when decoding on GPU. Use 1 for single-threaded decoding, which may be best if you are decoding multiple streams in parallel. Use a higher number for multi-threaded decoding, which is best for a single stream. Passing 0 lets FFmpeg decide on the number of threads. Default: 1.

Returns:

A decoder for this stream’s packets.

Return type:

VideoPacketDecoder

property metadata: VideoStreamHeaderMetadata

What the container header says about this video stream.

From the header only. This stream’s exact frame count, timestamps and keyframe positions aren’t in there - those come from scan(), and that is the distinction the _from_header and _from_content suffixes mark.

scan() → FrameIndex

Demux this stream from end to end, without decoding it (a scan), and return its FrameIndex.

This is the only way to know a stream’s exact frame count, timestamps and keyframe positions: the container header can be wrong about all three.

You can call this on multiple video streams from the same demuxer. The first call scans the entire video once, and subsequent calls on other streams are free.

Important

If called, then this must be called before any packets are read from the demuxer.

Returns:

the frame index for this stream, describing its keyframes and frame positions.

Return type:

FrameIndex