StreamingMediaDecoder

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

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

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

参数：:

• src (str, path-like, bytes 或 file-like object) –

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

  如果为 bytes 类型，则必须是连续内存中的编码媒体数据。

  如果为类文件对象，则必须支持签名 read(size: int) -> bytes 的 read 方法。此外，如果类文件对象具有 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. 指定输入源设备。这允许从硬件设备（如麦克风、摄像头和屏幕）或虚拟设备加载媒体流。

  注意

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

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

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

  对于设备访问，可用值因硬件（音视频设备）和软件配置（ffmpeg 构建）而异。

  https://ffmpeg.cpp.org.cn/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)

添加输出音频流

参数：:

• frames_per_chunk (int) –

  作为一块返回的帧数。如果在缓冲足够的帧之前源流已耗尽，则按原样返回该块。

  提供 -1 将禁用分块，并且 pop_chunks() 方法将连接所有已缓冲的帧并返回。

• buffer_chunk_size (int, 可选) –

  内部缓冲区大小。当缓冲的块数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则早于 15 的帧将被丢弃。提供 -1 将禁用此行为。

  默认值：3。

• stream_index (int 或 None, 可选) – 源音频流索引。如果省略，则使用 default_audio_stream。

• decoder (str 或 None, 可选) –

  要使用的解码器名称。如果提供，则使用指定的解码器而不是默认解码器。

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

  默认值：None。

• decoder_option (dict 或 None, 可选) –

  传递给解码器的选项。从 str 到 str 的映射。（默认值：None）

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

  
  

  除了特定于解码器的选项外，您还可以传递与多线程相关的选项。它们仅在解码器支持时有效。如果两者都未提供，StreamingMediaDecoder 默认为单线程。

  "threads": 线程数（字符串）。提供值 "0" 将让 FFmpeg 根据其启发式方法决定。

  "thread_type": 要使用的多线程方法。有效值为 "frame" 或 "slice"。请注意，每个解码器支持的方法集不同。如果未提供，则使用默认值。

  • "frame": 一次解码多个帧。每个线程处理一个帧。这将增加每个线程的解码延迟一个帧。

  • "slice": 一次解码单个帧的多个部分。

  
  

• filter_desc (str 或 None, 可选) – 滤波器描述。可用滤波器的列表可在 https://ffmpeg.cpp.org.cn/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)

添加输出音频流

参数：:

• frames_per_chunk (int) –

  作为一块返回的帧数。如果在缓冲足够的帧之前源流已耗尽，则按原样返回该块。

  提供 -1 将禁用分块，并且 pop_chunks() 方法将连接所有已缓冲的帧并返回。

• buffer_chunk_size (int, 可选) –

  内部缓冲区大小。当缓冲的块数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则早于 15 的帧将被丢弃。提供 -1 将禁用此行为。

  默认值：3。

• stream_index (int 或 None, 可选) – 源音频流索引。如果省略，则使用 default_audio_stream。

• decoder (str 或 None, 可选) –

  要使用的解码器名称。如果提供，则使用指定的解码器而不是默认解码器。

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

  默认值：None。

• decoder_option (dict 或 None, 可选) –

  传递给解码器的选项。从 str 到 str 的映射。（默认值：None）

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

  
  

  除了特定于解码器的选项外，您还可以传递与多线程相关的选项。它们仅在解码器支持时有效。如果两者都未提供，StreamingMediaDecoder 默认为单线程。

  "threads": 线程数（字符串）。提供值 "0" 将让 FFmpeg 根据其启发式方法决定。

  "thread_type": 要使用的多线程方法。有效值为 "frame" 或 "slice"。请注意，每个解码器支持的方法集不同。如果未提供，则使用默认值。

  • "frame": 一次解码多个帧。每个线程处理一个帧。这将增加每个线程的解码延迟一个帧。

  • "slice": 一次解码单个帧的多个部分。

  
  

• format (str, 可选) –

  输出采样格式（精度）。

  如果为 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)

添加输出视频流

参数：:

• frames_per_chunk (int) –

  作为一块返回的帧数。如果在缓冲足够的帧之前源流已耗尽，则按原样返回该块。

  提供 -1 将禁用分块，并且 pop_chunks() 方法将连接所有已缓冲的帧并返回。

• buffer_chunk_size (int, 可选) –

  内部缓冲区大小。当缓冲的块数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则早于 15 的帧将被丢弃。提供 -1 将禁用此行为。

  默认值：3。

• stream_index (int 或 None, 可选) – 源视频流索引。如果省略，则使用 default_video_stream。

• decoder (str 或 None, 可选) –

  要使用的解码器名称。如果提供，则使用指定的解码器而不是默认解码器。

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

  默认值：None。

• decoder_option (dict 或 None, 可选) –

  传递给解码器的选项。从 str 到 str 的映射。（默认值：None）

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

  
  

  除了特定于解码器的选项外，您还可以传递与多线程相关的选项。它们仅在解码器支持时有效。如果两者都未提供，StreamingMediaDecoder 默认为单线程。

  "threads": 线程数（字符串）。提供值 "0" 将让 FFmpeg 根据其启发式方法决定。

  "thread_type": 要使用的多线程方法。有效值为 "frame" 或 "slice"。请注意，每个解码器支持的方法集不同。如果未提供，则使用默认值。

  • "frame": 一次解码多个帧。每个线程处理一个帧。这将增加每个线程的解码延迟一个帧。

  • "slice": 一次解码单个帧的多个部分。

  
  

• format (str, 可选) –

  更改图像通道的格式。有效值包括：

  • "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 tensor。

  如果 None，帧将被移至 CPU 内存。默认值: None。

添加视频流

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)

添加输出视频流

参数：:

• frames_per_chunk (int) –

  作为一块返回的帧数。如果在缓冲足够的帧之前源流已耗尽，则按原样返回该块。

  提供 -1 将禁用分块，并且 pop_chunks() 方法将连接所有已缓冲的帧并返回。

• buffer_chunk_size (int, 可选) –

  内部缓冲区大小。当缓冲的块数超过此数量时，旧帧将被丢弃。例如，如果 frames_per_chunk 为 5 且 buffer_chunk_size 为 3，则早于 15 的帧将被丢弃。提供 -1 将禁用此行为。

  默认值：3。

• stream_index (int 或 None, 可选) – 源视频流索引。如果省略，则使用 default_video_stream。

• decoder (str 或 None, 可选) –

  要使用的解码器名称。如果提供，则使用指定的解码器而不是默认解码器。

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

  默认值：None。

• decoder_option (dict 或 None, 可选) –

  传递给解码器的选项。从 str 到 str 的映射。（默认值：None）

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

  
  

  除了特定于解码器的选项外，您还可以传递与多线程相关的选项。它们仅在解码器支持时有效。如果两者都未提供，StreamingMediaDecoder 默认为单线程。

  "threads": 线程数（字符串）。提供值 "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 tensor。

  如果 None，帧将被移至 CPU 内存。默认值: None。

• filter_desc (str 或 None, 可选) – 滤波器描述。可用滤波器的列表可在 https://ffmpeg.cpp.org.cn/ffmpeg-filters.html 找到。请注意，不支持复杂滤波器。

填充缓冲区

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

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

参数：:

• timeout (float 或 None， 可选) – 参见 process_packet()。(默认值: None)

• backoff (float， 可选) – 参见 process_packet()。(默认值: 10.0)

返回值:

0 数据包已正确处理，并且缓冲区已准备好弹出一次。

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

返回类型:

int

获取元数据

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

获取源媒体的元数据。

返回值:

dict

获取输出流信息

StreamingMediaDecoder.get_out_stream_info(i: int) → OutputStream

获取输出流的元数据

参数：:

i (int) – 流索引。

返回值:

OutputStreamTypes

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

获取源流信息

StreamingMediaDecoder.get_src_stream_info(i: int) → InputStream

获取源流的元数据

参数：:

i (int) – 流索引。

返回值:

关于源流的信息。如果源流是音频类型，则返回 SourceAudioStream。如果是视频类型，则返回 SourceVideoStream。否则返回 SourceStream 类。

返回类型:

InputStreamTypes

缓冲区是否准备就绪

StreamingMediaDecoder.is_buffer_ready() → bool

如果所有输出流都至少填充了一个块，则返回 true。

弹出块

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

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

返回值:

缓冲区内容。如果缓冲区不包含任何帧，则返回 None。

返回类型:

Tuple[Optional[ChunkTensor]]

处理所有数据包

StreamingMediaDecoder.process_all_packets()

处理数据包直到到达 EOF。

处理数据包

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

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

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

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

当源到达 EOF 时，它将触发所有输出流处理器进入排空模式。所有输出流处理器都会刷新待处理的帧。

参数：:

• timeout (float 或 None， 可选) –

  超时时长，单位毫秒。

  当因底层媒体资源暂时不可用而未能处理数据包时，此参数会改变重试行为。

  使用媒体设备（如麦克风）时，有时底层缓冲区尚未准备好。在这种情况下调用此函数会导致系统报告 EAGAIN (资源暂时不可用)。

  • >=0: 一直重试直到给定时间过去。

  • 0<: 永远重试。

  • None : 不重试并立即引发异常。

  默认值：None。

  注意

  仅当原因为资源不可用时，重试行为才适用。如果失败原因为其他，则不触发重试。

• backoff (float， 可选) –

  重试前等待时间，单位毫秒。

  此选项仅当 timeout 有效时才生效。（不是 None）

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

返回值:

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

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

返回类型:

int

移除流

StreamingMediaDecoder.remove_stream(i: int)

移除一个输出流。

参数：:

i (int) – 要移除的输出流的索引。

定位

StreamingMediaDecoder.seek(timestamp: float, mode: str = 'precise')

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

参数：:

• timestamp (float) – 目标时间，单位秒。

• mode (str) –

  控制定位方式。有效选项为；

  • ”key”: 定位到给定时间戳之前的最近关键帧。

  • ”any”: 定位到给定时间戳之前的任何帧（包括非关键帧）。

  • ”precise”: 首先定位到给定时间戳之前的最近关键帧，然后解码帧直到到达最接近给定时间戳的帧。

  注意

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

stream

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

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

参数：:

• timeout (float 或 None， 可选) – 参见 process_packet()。(默认值: None)

• backoff (float， 可选) – 参见 process_packet()。(默认值: 10.0)

返回值:

生成一个元组的迭代器，该元组包含客户端代码定义的输出流对应的块。如果一个输出流耗尽，则块 Tensor 会被替换为 None。如果所有输出流都耗尽，迭代器将停止。

返回类型:

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

支持结构

ChunkTensor

class torio.io._streaming_media_decoder.ChunkTensor

解码后的媒体帧及元数据。

此类的实例表示解码后的视频/音频帧及元数据，实例本身的行为类似于 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

源流的元数据，由 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

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

此类用于表示音频流。

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

sample_rate: float

音频采样率。

num_channels: int

通道数。

SourceVideoStream

class torio.io._streaming_media_decoder.SourceVideoStream

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

此类用于表示视频流。

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

width: int

视频帧的宽度，单位像素。

height: int

视频帧的高度，单位像素。

frame_rate: float

帧率。

OutputStream

class torio.io._streaming_media_decoder.OutputStream

配置在 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

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

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

sample_rate: float

音频采样率。

num_channels: int

通道数。

OutputVideoStream

class torio.io._streaming_media_decoder.OutputVideoStream

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

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

width: int

视频帧的宽度，单位像素。

height: int

视频帧的高度，单位像素。

frame_rate: float

帧率。