流媒体解码器¶

class torio.io.StreamingMediaDecoder(src: Union[str, Path, BinaryIO], format: Optional[str] = None, option: Optional[Dict[str, str]] = None, buffer_size: int = 4096)[source]¶

逐块获取并解码音频/视频流。

有关此类的详细用法，请参考教程。

参数：

src (str, 路径类, 字节或 文件类对象) –
媒体源。如果为字符串类型，它必须是 FFmpeg 可以处理的资源指示符。这包括文件路径、URL、设备标识符或过滤器表达式。支持的值取决于系统中找到的 FFmpeg。

如果为字节，它必须是连续内存中编码的媒体数据。

如果为文件类对象，它必须支持 read 方法，其签名为 read(size: int) -> bytes。此外，如果文件类对象具有 seek 方法，它在解析媒体元数据时使用该方法。这提高了编解码器检测的可靠性。seek 方法的签名必须为 seek(offset: int, whence: int) -> int。

有关 read 和 seek 方法的预期签名和行为，请参阅以下内容。
- https://docs.pythonlang.cn/3/library/io.html#io.BufferedIOBase.read
- https://docs.pythonlang.cn/3/library/io.html#io.IOBase.seek
format (str 或 None, 可选) –
覆盖输入格式或指定源声音设备。默认：None（无覆盖或设备输入）。

此参数用于两种不同的用例。
1. 覆盖源格式。当输入数据不包含头文件时，这很有用。
2. 指定输入源设备。这允许从硬件设备（如麦克风、相机和屏幕）或虚拟设备加载媒体流。
注意

此选项大致对应于 -f ffmpeg 命令的选项。有关可能的值，请参阅 ffmpeg 文档。

https://ffmpeg.org/ffmpeg-formats.html#Demuxers

请使用 get_demuxers() 列出当前环境中可用的解复用器。

对于设备访问，可用的值会根据硬件（AV 设备）和软件配置（ffmpeg 构建）而有所不同。

https://ffmpeg.org/ffmpeg-devices.html#Input-Devices

请使用 get_input_devices() 列出当前环境中可用的输入设备。
option (str 到 str 的字典, 可选) –
初始化格式上下文（打开源）时传递的自定义选项。

您可以使用此参数在将输入源传递给解码器之前对其进行更改。

默认：None。
buffer_size (int) –
内部缓冲区大小（以字节为单位）。仅在 src 为文件类对象时使用。

默认：4096。

属性¶

default_audio_stream¶

property StreamingMediaDecoder.default_audio_stream¶

默认音频流的索引。如果不存在音频流，则为 None

类型：: Optional[int]

default_video_stream¶

property StreamingMediaDecoder.default_video_stream¶

默认视频流的索引。如果不存在视频流，则为 None

类型：: Optional[int]

num_out_streams¶

property StreamingMediaDecoder.num_out_streams¶

由客户端代码配置的输出流数量。

类型：: int

num_src_streams¶

property StreamingMediaDecoder.num_src_streams¶

在提供的媒体源中找到的流数量。

类型：: int

方法¶

add_audio_stream¶

StreamingMediaDecoder.add_audio_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict[str, str]] = None, filter_desc: Optional[str] = None)[source]¶

添加输出音频流

参数：

frames_per_chunk (int) –
作为一组返回的帧数。如果源流在缓冲足够的帧之前耗尽，则按原样返回该组。

提供 -1 将禁用分组，并且 pop_chunks() 方法将连接所有缓冲的帧并将其返回。
buffer_chunk_size (int, optional) –
内部缓冲区大小。当缓冲的组数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则将丢弃早于 15 的帧。提供 -1 将禁用此行为。

默认值： 3。
stream_index (int or None, optional) – 源音频流索引。如果省略，则使用 default_audio_stream。
decoder (str or None, optional) –
要使用的解码器的名称。如果提供，则使用指定的解码器，而不是默认解码器。

要列出可用的解码器，请使用 get_audio_decoders() 用于音频，以及 get_video_decoders() 用于视频。

默认：None。
decoder_option (dict or None, optional) –
传递给解码器的选项。从 str 到 str 的映射。 (默认值： None)

要列出解码器的解码器选项，可以使用 ffmpeg -h decoder=<DECODER> 命令。

除了解码器特定的选项之外，您还可以传递与多线程相关的选项。它们仅在解码器支持它们的情况下有效。如果没有提供任何选项，StreamingMediaDecoder 默认使用单线程。

"threads": 线程数 (以 str 表示)。提供值 "0" 将让 FFmpeg 根据其启发式算法决定。

"thread_type": 要使用的多线程方法。有效值为 "frame" 或 "slice"。请注意，每个解码器都支持不同的方法集。如果未提供，则使用默认值。
- "frame": 同时解码多个帧。每个线程处理一帧。这将使解码延迟增加每个线程一帧。
- "slice": 同时解码单个帧的多个部分。
filter_desc (str or None, optional) – 过滤器描述。可在 https://ffmpeg.org/ffmpeg-filters.html 上找到可用过滤器的列表。请注意，不支持复杂的过滤器。

add_basic_audio_stream¶

StreamingMediaDecoder.add_basic_audio_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict[str, str]] = None, format: Optional[str] = 'fltp', sample_rate: Optional[int] = None, num_channels: Optional[int] = None)[source]¶

添加输出音频流

参数：

frames_per_chunk (int) –
作为一组返回的帧数。如果源流在缓冲足够的帧之前耗尽，则按原样返回该组。

提供 -1 将禁用分组，并且 pop_chunks() 方法将连接所有缓冲的帧并将其返回。
buffer_chunk_size (int, optional) –
内部缓冲区大小。当缓冲的组数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则将丢弃早于 15 的帧。提供 -1 将禁用此行为。

默认值： 3。
stream_index (int or None, optional) – 源音频流索引。如果省略，则使用 default_audio_stream。
decoder (str or None, optional) –
要使用的解码器的名称。如果提供，则使用指定的解码器，而不是默认解码器。

要列出可用的解码器，请使用 get_audio_decoders() 用于音频，以及 get_video_decoders() 用于视频。

默认：None。
decoder_option (dict or None, optional) –
传递给解码器的选项。从 str 到 str 的映射。 (默认值： None)

要列出解码器的解码器选项，可以使用 ffmpeg -h decoder=<DECODER> 命令。

除了解码器特定的选项之外，您还可以传递与多线程相关的选项。它们仅在解码器支持它们的情况下有效。如果没有提供任何选项，StreamingMediaDecoder 默认使用单线程。

"threads": 线程数 (以 str 表示)。提供值 "0" 将让 FFmpeg 根据其启发式算法决定。

"thread_type": 要使用的多线程方法。有效值为 "frame" 或 "slice"。请注意，每个解码器都支持不同的方法集。如果未提供，则使用默认值。
- "frame": 同时解码多个帧。每个线程处理一帧。这将使解码延迟增加每个线程一帧。
- "slice": 同时解码单个帧的多个部分。
format (str, optional) –
输出样本格式 (精度)。

如果为 None，则输出块的 dtype 与源音频的精度相对应。

否则，将转换样本并按以下方式更改输出 dtype。
- "u8p"：输出为 torch.uint8 类型。
- "s16p"：输出为 torch.int16 类型。
- "s32p"：输出为 torch.int32 类型。
- "s64p"：输出为 torch.int64 类型。
- "fltp"：输出为 torch.float32 类型。
- "dblp"：输出为 torch.float64 类型。
默认值："fltp"。
sample_rate (int 或 None, 可选) – 如果提供，则对音频进行重采样。
num_channels (int 或 None, 可选) – 如果提供，则更改通道数量。

add_basic_video_stream¶

StreamingMediaDecoder.add_basic_video_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict[str, str]] = None, format: Optional[str] = 'rgb24', frame_rate: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None, hw_accel: Optional[str] = None)[source]¶

添加输出视频流

参数：

frames_per_chunk (int) –
作为一组返回的帧数。如果源流在缓冲足够的帧之前耗尽，则按原样返回该组。

提供 -1 将禁用分组，并且 pop_chunks() 方法将连接所有缓冲的帧并将其返回。
buffer_chunk_size (int, optional) –
内部缓冲区大小。当缓冲的组数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则将丢弃早于 15 的帧。提供 -1 将禁用此行为。

默认值： 3。
stream_index (int 或 None, 可选) – 源视频流索引。如果省略，则使用 default_video_stream。
decoder (str or None, optional) –
要使用的解码器的名称。如果提供，则使用指定的解码器，而不是默认解码器。

要列出可用的解码器，请使用 get_audio_decoders() 用于音频，以及 get_video_decoders() 用于视频。

默认：None。
decoder_option (dict or None, optional) –
传递给解码器的选项。从 str 到 str 的映射。 (默认值： None)

要列出解码器的解码器选项，可以使用 ffmpeg -h decoder=<DECODER> 命令。

除了解码器特定的选项之外，您还可以传递与多线程相关的选项。它们仅在解码器支持它们的情况下有效。如果没有提供任何选项，StreamingMediaDecoder 默认使用单线程。

"threads": 线程数 (以 str 表示)。提供值 "0" 将让 FFmpeg 根据其启发式算法决定。

"thread_type": 要使用的多线程方法。有效值为 "frame" 或 "slice"。请注意，每个解码器都支持不同的方法集。如果未提供，则使用默认值。
- "frame": 同时解码多个帧。每个线程处理一帧。这将使解码延迟增加每个线程一帧。
- "slice": 同时解码单个帧的多个部分。
format (str, optional) –
更改图像通道的格式。有效值为：
- "rgb24"：8 位 * 3 通道（R、G、B）
- "bgr24"：8 位 * 3 通道（B、G、R）
- "yuv420p"：8 位 * 3 通道（Y、U、V）
- "gray"：8 位 * 1 通道
默认值："rgb24"。
frame_rate (int 或 None, 可选) – 如果提供，则更改帧速率。
width (int 或 None, 可选) – 如果提供，则更改图像宽度。单位：像素。
height (int 或 None, 可选) – 如果提供，则更改图像高度。单位：像素。
hw_accel (str 或 None, 可选) –
启用硬件加速。

当视频在 CUDA 硬件上解码时，例如 decoder=”h264_cuvid”，将 CUDA 设备指示器传递给 hw_accel（即 hw_accel=”cuda:0”）将使 StreamingMediaDecoder 将生成的帧直接放置在指定的 CUDA 设备上作为 CUDA 张量。

如果为 None，则将帧移至 CPU 内存。默认值：None。

add_video_stream¶

StreamingMediaDecoder.add_video_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict[str, str]] = None, filter_desc: Optional[str] = None, hw_accel: Optional[str] = None)[source]¶

添加输出视频流

参数：

frames_per_chunk (int) –
作为一组返回的帧数。如果源流在缓冲足够的帧之前耗尽，则按原样返回该组。

提供 -1 将禁用分组，并且 pop_chunks() 方法将连接所有缓冲的帧并将其返回。
buffer_chunk_size (int, optional) –
内部缓冲区大小。当缓冲的组数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则将丢弃早于 15 的帧。提供 -1 将禁用此行为。

默认值： 3。
stream_index (int 或 None, 可选) – 源视频流索引。如果省略，则使用 default_video_stream。
decoder (str or None, optional) –
要使用的解码器的名称。如果提供，则使用指定的解码器，而不是默认解码器。

要列出可用的解码器，请使用 get_audio_decoders() 用于音频，以及 get_video_decoders() 用于视频。

默认：None。
decoder_option (dict or None, optional) –
传递给解码器的选项。从 str 到 str 的映射。 (默认值： None)

要列出解码器的解码器选项，可以使用 ffmpeg -h decoder=<DECODER> 命令。

除了解码器特定的选项之外，您还可以传递与多线程相关的选项。它们仅在解码器支持它们的情况下有效。如果没有提供任何选项，StreamingMediaDecoder 默认使用单线程。

"threads": 线程数 (以 str 表示)。提供值 "0" 将让 FFmpeg 根据其启发式算法决定。

"thread_type": 要使用的多线程方法。有效值为 "frame" 或 "slice"。请注意，每个解码器都支持不同的方法集。如果未提供，则使用默认值。
- "frame": 同时解码多个帧。每个线程处理一帧。这将使解码延迟增加每个线程一帧。
- "slice": 同时解码单个帧的多个部分。
hw_accel (str 或 None, 可选) –
启用硬件加速。

当视频在 CUDA 硬件上解码时，例如 decoder=”h264_cuvid”，将 CUDA 设备指示器传递给 hw_accel（即 hw_accel=”cuda:0”）将使 StreamingMediaDecoder 将生成的帧直接放置在指定的 CUDA 设备上作为 CUDA 张量。

如果为 None，则将帧移至 CPU 内存。默认值：None。
filter_desc (str or None, optional) – 过滤器描述。可在 https://ffmpeg.org/ffmpeg-filters.html 上找到可用过滤器的列表。请注意，不支持复杂的过滤器。

fill_buffer¶

StreamingMediaDecoder.fill_buffer(timeout: Optional[float] = None, backoff: float = 10.0) → int[source]¶

持续处理数据包，直到所有缓冲区至少包含一个块。

参数：

timeout (float 或 None, 可选) – 参见 process_packet()。(默认: None)
backoff (float, 可选) – 参见 process_packet()。(默认: 10.0)

返回值:

0 数据包处理正常，缓冲区已准备好被弹出。

1 流媒体已到达 EOF。所有输出流处理器已将待处理帧刷新。调用者应停止调用此方法。

返回值类型:

int

get_metadata¶

StreamingMediaDecoder.get_metadata() → Dict[str, str][source]¶

获取源媒体的元数据。

返回值:: 字典

get_out_stream_info¶

StreamingMediaDecoder.get_out_stream_info(i: int) → OutputStream[source]¶

获取输出流的元数据

参数：

i (int) – 流索引。

返回值:

OutputStreamTypes: 有关输出流的信息。如果输出流是音频类型，则返回 OutputAudioStream。如果它是视频类型，则返回 OutputVideoStream。

get_src_stream_info¶

StreamingMediaDecoder.get_src_stream_info(i: int) → InputStream[source]¶

获取源流的元数据

参数：: i (int) – 流索引。
返回值:: 有关源流的信息。如果源流是音频类型，则返回 SourceAudioStream。如果它是视频类型，则返回 SourceVideoStream。否则返回 SourceStream 类。
返回值类型:: InputStreamTypes

is_buffer_ready¶

StreamingMediaDecoder.is_buffer_ready() → bool[source]¶: 如果所有输出流都至少填充了一个块，则返回 True。

pop_chunks¶

StreamingMediaDecoder.pop_chunks() → Tuple[Optional[ChunkTensor]][source]¶

从所有输出流缓冲区中弹出单个块。

返回值:: 缓冲区内容。如果缓冲区不包含任何帧，则返回 None。
返回值类型:: Tuple[Optional[ChunkTensor]]

process_all_packets¶

StreamingMediaDecoder.process_all_packets()[source]¶: 处理数据包直到到达文件末尾。

process_packet¶

StreamingMediaDecoder.process_packet(timeout: Optional[float] = None, backoff: float = 10.0) → int[source]¶

读取源媒体并处理一个数据包。

如果成功读取一个数据包，则数据包中的数据将被解码并传递给相应的输出流处理器。

如果数据包属于未连接到输出流的源流，则数据将被丢弃。

当源到达文件末尾时，它将触发所有输出流处理器进入排水模式。所有输出流处理器将刷新待处理的帧。

参数：

timeout (float or None, optional) –
超时时间，单位为毫秒。

当由于底层媒体资源暂时不可用导致处理数据包失败时，此参数将改变重试行为。

当使用麦克风等媒体设备时，存在底层缓冲区未准备好的情况。在这种情况下调用此函数会导致系统报告 EAGAIN (资源暂时不可用)。
- >=0: 持续重试直到给定的时间过去。
- 0<: 永久重试。
- None : 不重试并立即抛出异常。
默认：None。

注意

重试行为仅适用于资源不可用的情况。如果失败的原因是其他原因，则不会调用它。
backoff (float, optional) –
重试前等待的时间，单位为毫秒。

此选项仅在 timeout 有效时才有效。（不为 None）

当 timeout 有效时，此 backoff 控制函数在重试之前应等待多长时间。默认值为 10.0。

返回值:

0 数据包已正确处理。调用者可以继续调用此函数以缓冲更多帧。

1 流媒体已到达 EOF。所有输出流处理器已将待处理帧刷新。调用者应停止调用此方法。

返回值类型:

int

remove_stream¶

StreamingMediaDecoder.remove_stream(i: int)[source]¶

删除输出流。

参数：: i (int) – 要删除的输出流的索引。

seek¶

StreamingMediaDecoder.seek(timestamp: float, mode: str = 'precise')[source]¶

将流定位到给定的时间戳 [秒]

参数：

timestamp (float) – 目标时间，单位为秒。
mode (str) –
控制 seek 的执行方式。有效选择包括：
- ”key”: 定位到给定时间戳之前最近的关键帧。
- ”any”: 定位到给定时间戳之前的任何帧（包括非关键帧）。
- ”precise”: 首先定位到给定时间戳之前最近的关键帧，然后解码帧，直到到达最接近给定时间戳的帧。
注意

所有模式都会使解码器的内部状态失效并重置。当使用 "any" 模式时，如果最终定位到非关键帧，则解码的图像可能由于缺少关键帧而无效。使用 "precise" 将通过从之前的关键帧解码帧来解决此问题，但这会比较慢。

stream¶

StreamingMediaDecoder.stream(timeout: Optional[float] = None, backoff: float = 10.0) → Iterator[Tuple[Optional[ChunkTensor], ...]][source]¶

返回一个生成输出张量的迭代器

参数：

timeout (float 或 None, 可选) – 参见 process_packet()。(默认: None)
backoff (float, 可选) – 参见 process_packet()。(默认: 10.0)

返回值:

迭代器，它生成与客户端代码定义的输出流相对应的块元组。如果输出流已耗尽，则块张量将被 None 替换。如果所有输出流都已耗尽，则迭代器将停止。

返回值类型:

Iterator[Tuple[Optional[ChunkTensor], …]]

支持结构¶

ChunkTensor¶

class torio.io._streaming_media_decoder.ChunkTensor[source]¶

带有元数据的解码后的媒体帧。

此类的实例表示带有元数据的解码后的视频/音频帧，并且实例本身的行为类似于 Tensor。

客户端代码可以将此类的实例作为 Tensor 类传递，或者调用在 Tensor 类上定义的方法。

示例

>>> # Define input streams
>>> reader = StreamingMediaDecoder(...)
>>> reader.add_audio_stream(frames_per_chunk=4000, sample_rate=8000)
>>> reader.add_video_stream(frames_per_chunk=7, frame_rate=28)
>>> # Decode the streams and fetch frames
>>> reader.fill_buffer()
>>> audio_chunk, video_chunk = reader.pop_chunks()

>>> # Access metadata
>>> (audio_chunk.pts, video_chunks.pts)
(0.0, 0.0)
>>>
>>> # The second time the PTS is different
>>> reader.fill_buffer()
>>> audio_chunk, video_chunk = reader.pop_chunks()
>>> (audio_chunk.pts, video_chunks.pts)
(0.5, 0.25)

>>> # Call PyTorch ops on chunk
>>> audio_chunk.shape
torch.Size([4000, 2]
>>> power = torch.pow(video_chunk, 2)
>>>
>>> # the result is a plain torch.Tensor class
>>> type(power)
<class 'torch.Tensor'>
>>>
>>> # Metadata is not available on the result
>>> power.pts
AttributeError: 'Tensor' object has no attribute 'pts'

pts: float¶

块中第一帧的呈现时间戳。

单位：秒。

SourceStream¶

class torio.io._streaming_media_decoder.SourceStream[source]¶

源流的元数据，由 get_src_stream_info() 返回。

此类用于表示除 audio 或 video 以外的媒体类型的流。

当源流是 audio 或 video 类型时，分别使用 SourceAudioStream 和 SourceVideoStream，它们分别报告了额外的特定于媒体的属性。

media_type: str¶: 流的类型。可能是 "audio"、"video"、"data"、"subtitle"、"attachment" 和空字符串。

注意

只有音频和视频流支持输出。

注意

静态图像，如 PNG 和 JPEG 格式被报告为视频。

codec: str¶: 编解码器的简称。例如 "pcm_s16le" 和 "h264"。

codec_long_name: str¶

编解码器的详细名称。

例如，“PCM signed 16-bit little-endian” 和 “H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10”。

format: Optional[str]¶

媒体格式。例如 "s16" 和 "yuv420p"。

常见的音频值是；

"u8", "u8p": 无符号 8 位无符号整数。
"s16", "s16p": 16 位有符号整数。
"s32", "s32p": 32 位有符号整数。
"flt", "fltp": 32 位浮点数。

注意

结尾处的 p 表示格式是 planar。通道分组在一起，而不是在内存中交错。

bit_rate: Optional[int]¶: 流的比特率，单位是比特每秒。这是一个根据流的前几帧估计的值。对于容器格式和可变比特率，它可以为 0。

num_frames: Optional[int]¶: 流中的帧数

bits_per_sample: Optional[int]¶: 这是每个输出样本中的有效位数。对于压缩格式，它可以为 0。

metadata: Dict[str, str]¶: 附加到源流的元数据。

SourceAudioStream¶

class torio.io._streaming_media_decoder.SourceAudioStream[source]¶

音频源流的元数据，由 get_src_stream_info() 返回。

此类用于表示音频流。

除了 SourceStream 报告的属性外，还会报告以下属性。

sample_rate: float¶: 音频的采样率。

num_channels: int¶: 声道数。

SourceVideoStream¶

class torio.io._streaming_media_decoder.SourceVideoStream[source]¶

视频源流的元数据，由 get_src_stream_info() 返回。

此类用于表示视频流。

除了 SourceStream 报告的属性外，还会报告以下属性。

width: int¶: 视频帧的宽度，以像素为单位。

height: int¶: 视频帧的高度，以像素为单位。

frame_rate: float¶: 帧率。

OutputStream¶

class torio.io._streaming_media_decoder.OutputStream[source]¶

在 StreamingMediaDecoder 上配置的输出流，由 get_out_stream_info() 返回。

source_index: int¶: 此输出流连接到的源流的索引。

filter_description: str¶: 应用于源流的过滤器图的描述。

media_type: str¶: 流的类型。 "audio" 或 "video"。

format: str¶

媒体格式。例如 "s16" 和 "yuv420p"。

常见的音频值是；

"u8", "u8p": 无符号 8 位无符号整数。
"s16", "s16p": 16 位有符号整数。
"s32", "s32p": 32 位有符号整数。
"flt", "fltp": 32 位浮点数。

注意

结尾处的 p 表示格式是 planar。通道分组在一起，而不是在内存中交错。

OutputAudioStream¶

class torio.io._streaming_media_decoder.OutputAudioStream[source]¶

使用 add_audio_stream() 或 add_basic_audio_stream() 配置的音频输出流的信息。

除了 OutputStream 报告的属性之外，还报告以下属性。

sample_rate: float¶: 音频的采样率。

num_channels: int¶: 声道数。

OutputVideoStream¶

class torio.io._streaming_media_decoder.OutputVideoStream[source]¶

使用 add_video_stream() 或 add_basic_video_stream() 配置的视频输出流的信息。

除了 OutputStream 报告的属性之外，还报告以下属性。

width: int¶: 视频帧的宽度，以像素为单位。

height: int¶: 视频帧的高度，以像素为单位。

frame_rate: float¶: 帧率。