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
(不覆盖也不使用设备输入)。此参数有两个不同的用例。
覆盖源格式。当输入数据不包含标头时,这很有用。
指定输入源设备。这允许从硬件设备(如麦克风、摄像头和屏幕)或虚拟设备加载媒体流。
注意
此选项大致对应于
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¶
default_video_stream¶
num_out_streams¶
num_src_streams¶
方法¶
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 [源代码]¶
保持处理数据包,直到所有缓冲区至少有一个块。
- 参数:
timeout (float 或 None, 可选) – 参见
process_packet()
。(默认值:None
)backoff (float, 可选) – 参见
process_packet()
。(默认值:10.0
)
- 返回值:
0
数据包已正确处理,缓冲区已准备好弹出一次。1
流媒体已到达 EOF。所有输出流处理器都刷新了挂起的帧。调用者应停止调用此方法。- 返回类型:
get_metadata¶
get_out_stream_info¶
- StreamingMediaDecoder.get_out_stream_info(i: int) OutputStream [源代码]¶
获取输出流的元数据
- 参数:
i (int) – 流索引。
- 返回值:
- OutputStreamTypes
关于输出流的信息。如果输出流是音频类型,则返回
OutputAudioStream
。如果是视频类型,则返回OutputVideoStream
。
get_src_stream_info¶
is_buffer_ready¶
pop_chunks¶
- StreamingMediaDecoder.pop_chunks() Tuple[Optional[ChunkTensor]] [源代码]¶
从所有输出流缓冲区中弹出一个块。
- 返回值:
缓冲区内容。如果缓冲区不包含任何帧,则返回 None。
- 返回类型:
Tuple[Optional[ChunkTensor]]
process_all_packets¶
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。所有输出流处理器都刷新了挂起的帧。调用者应停止调用此方法。- 返回类型:
remove_stream¶
seek¶
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
)
- 返回值:
迭代器,产生对应于客户端代码定义的输出流的块的元组。如果输出流已耗尽,则块张量将替换为
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'
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_long_name: str¶
编解码器的详细名称。
例如 “PCM signed 16-bit little-endian” 和 “H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10”。
SourceAudioStream¶
- class torio.io._streaming_media_decoder.SourceAudioStream[源代码]¶
音频源流的元数据,由
get_src_stream_info()
返回。此类用于表示音频流。
除了
SourceStream
报告的属性外,还报告以下属性。
SourceVideoStream¶
- class torio.io._streaming_media_decoder.SourceVideoStream[source]¶
视频源流的元数据,由
get_src_stream_info()
返回。此类用于表示视频流。
除了
SourceStream
报告的属性外,还报告以下属性。
OutputStream¶
- class torio.io._streaming_media_decoder.OutputStream[source]¶
在
StreamingMediaDecoder
上配置的输出流,由get_out_stream_info()
返回。
OutputAudioStream¶
- class torio.io._streaming_media_decoder.OutputAudioStream[source]¶
关于使用
add_audio_stream()
或add_basic_audio_stream()
配置的音频输出流的信息。除了
OutputStream
报告的属性外,还报告以下属性。
OutputVideoStream¶
- class torio.io._streaming_media_decoder.OutputVideoStream[source]¶
关于使用
add_video_stream()
或add_basic_video_stream()
配置的视频输出流的信息。除了
OutputStream
报告的属性外,还报告以下属性。