目录
快捷方式

StreamingMediaDecoder

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

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

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

参数:

  • src (str, path-like, bytes 或 类文件对象) –

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

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

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

    有关 read 和 seek 方法的预期签名和行为，请参阅以下内容。

  • format (str 或 None, 可选) –

    覆盖输入格式，或指定源声音设备。默认值：None（不覆盖也不使用设备输入）。

    此参数有两个不同的用例。

    1. 覆盖源格式。当输入数据不包含标头时，这很有用。

    2. 指定输入源设备。这允许从硬件设备（如麦克风、摄像头和屏幕）或虚拟设备加载媒体流。

    注意

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

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

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

    对于设备访问，可用值因硬件（AV 设备）和软件配置（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]] = None, filter_desc: Optional[str] = None)[source]

添加输出音频流

参数:

  • 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"：线程数（以 str 形式）。提供值 "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]] = 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, 可选) –

    内部缓冲区大小。当缓冲的块数超过此数量时，将删除旧帧。例如，如果 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"：线程数（以 str 形式）。提供值 "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]] = 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, 可选) –

    内部缓冲区大小。当缓冲的块数超过此数量时，将删除旧帧。例如，如果 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"：线程数（以 str 形式）。提供值 "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 张量。

    如果为 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)[源代码]

添加输出视频流

参数:

  • 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"：线程数（以 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 或 None, 可选) – 过滤器描述。可在 https://ffmpeg.cpp.org.cn/ffmpeg-filters.html 找到可用过滤器的列表。请注意，不支持复杂过滤器。

fill_buffer

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

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

参数:
返回值:

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

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

返回类型:

int

get_metadata

StreamingMediaDecoder.get_metadata() → Dict[str, str][源代码]

获取源媒体的元数据。

返回值:

dict

get_out_stream_info

StreamingMediaDecoder.get_out_stream_info(i: int) → OutputStream[源代码]

获取输出流的元数据

参数:

i (int) – 流索引。

返回值:

OutputStreamTypes

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

get_src_stream_info

StreamingMediaDecoder.get_src_stream_info(i: int) → InputStream[源代码]

获取源流的元数据

参数:

i (int) – 流索引。

返回值:

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

返回类型:

InputStreamTypes

is_buffer_ready

StreamingMediaDecoder.is_buffer_ready() → bool[源代码]

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

pop_chunks

StreamingMediaDecoder.pop_chunks() → Tuple[Optional[ChunkTensor]][源代码]

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

返回值:

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

返回类型:

Tuple[Optional[ChunkTensor]]

process_all_packets

StreamingMediaDecoder.process_all_packets()[源代码]

处理数据包直到到达 EOF。

process_packet

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

remove_stream

StreamingMediaDecoder.remove_stream(i: int)[源代码]

移除输出流。

参数:

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

seek

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], ...]][源代码]

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

参数:
返回值:

迭代器，产生对应于客户端代码定义的输出流的块的元组。如果输出流已耗尽，则块张量将替换为 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[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

帧率。

文档

访问 PyTorch 的综合开发者文档

查看文档

教程

获取面向初学者和高级开发者的深入教程

查看教程

资源

查找开发资源并获取您的问题解答

查看资源

为了分析流量和优化您的体验，我们在本网站上使用 Cookie。 通过点击或导航，您同意允许我们使用 Cookie。 作为本网站的当前维护者，Facebook 的 Cookie 政策适用。 了解更多信息，包括关于可用控件：Cookie 政策。