StreamingMediaEncoder¶
- class torio.io.StreamingMediaEncoder(dst: Union[str, Path, BinaryIO], format: Optional[str] = None, buffer_size: int = 4096)[源代码]¶
已弃用
警告
此类已从 2.8 版本开始弃用。它将在 2.9 版本中移除。此弃用是大型重构工作的一部分，目的是将 TorchAudio 转移到维护阶段。PyTorch 对音频和视频的解码和编码功能正在整合到 TorchCodec 中。有关更多信息，请参阅 https://github.com/pytorch/audio/issues/3902。
逐块编码和写入音频/视频流
- 参数 (Args)
- dst (str、path-like 或文件-like 对象)：编码数据写入的目标。如果为字符串类型，则必须是 FFmpeg 可以处理的资源指示符。支持的值取决于系统中找到的 FFmpeg。
如果为字符串类型，则必须是 FFmpeg 可以处理的资源指示符。支持的值取决于系统中找到的 FFmpeg。
如果为文件-like 对象，则必须支持带有 write 方法的签名 write(data: bytes) -> int。
有关 write 方法的预期签名和行为，请参考以下内容。
- format (str 或 None，可选)
覆盖输出格式，或指定输出媒体设备。默认值：
None（不覆盖，也不输出到设备）。此参数用于两种不同的用例。
覆盖输出格式。这在写入原始数据或以不同于扩展名的格式写入时很有用。
指定输出设备。这允许将媒体流输出到硬件设备，例如扬声器和视频屏幕。
注意
此选项大致对应于
ffmpeg命令的-f选项。有关可能的值，请参阅 ffmpeg 文档。https://ffmpeg.net.cn/ffmpeg-formats.html#Muxers
请使用
get_muxers()列出当前环境中可用的复用器。对于设备访问，可用值因硬件（AV 设备）和软件配置（ffmpeg 构建）而异。有关可能的值，请参阅 ffmpeg 文档。
https://ffmpeg.net.cn/ffmpeg-devices.html#Output-Devices
请使用
get_output_devices()列出当前环境中可用的输出设备。- buffer_size (int)
内部缓冲区大小（以字节为单位）。仅当 dst 是文件-like 对象时使用。
默认值：4096。
方法¶
add_audio_stream¶
- StreamingMediaEncoder.add_audio_stream(sample_rate: int, num_channels: int, format: str = 'flt', *, encoder: Optional[str] = None, encoder_option: Optional[Dict[str, str]] = None, encoder_sample_rate: Optional[int] = None, encoder_num_channels: Optional[int] = None, encoder_format: Optional[str] = None, codec_config: Optional[CodecConfig] = None, filter_desc: Optional[str] = None)[源代码]¶
添加一个输出音频流。
- 参数
sample_rate (int) – 采样率。
num_channels (int) – 通道数。
format (str, optional) –
输入样本格式，它决定了输入张量的 dtype。
"u8": 输入张量必须是torch.uint8类型。"s16": 输入张量必须是torch.int16类型。"s32": 输入张量必须是torch.int32类型。"s64": 输入张量必须是torch.int64类型。"flt": 输入张量必须是torch.float32类型。"dbl": 输入张量必须是torch.float64类型。
默认值：
"flt"。encoder (str 或 None, optional) –
要使用的编码器名称。如果提供了该名称，则使用指定的编码器而不是默认编码器。
要列出可用的编码器，请使用
get_audio_encoders()（用于音频），和get_video_encoders()（用于视频）。默认值：
None。encoder_option (dict 或 None, optional) –
传递给编码器的选项。从 str 映射到 str。
要列出编码器的编码器选项，您可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。除了编码器特定的选项外，还可以传递与多线程相关的选项。这些选项仅在编码器支持时有效。如果两者均未提供，StreamReader 将默认使用单线程。
"threads": 线程数（字符串类型）。提供值"0"将让 FFmpeg 根据其启发式方法进行选择。"thread_type": 要使用哪种多线程方法。有效值为"frame"或"slice"。请注意，每个编码器支持的方法集不同。如果未提供，则使用默认值。"frame": 一次编码多个帧。每个线程处理一个帧。这将增加一个帧/线程的解码延迟。"slice": 一次编码单个帧的多个部分。
encoder_sample_rate (int 或 None, optional) –
覆盖用于编码时间的采样率。某些编码器对用于编码的采样率有限制。如果源采样率不受编码器支持，则使用源采样率，否则会选择默认采样率。
例如，
"opus"编码器仅支持 48k Hz，因此在编码具有"opus"编码器的波形时，它始终以 48k Hz 进行编码。而"mp3"("libmp3lame") 支持 44.1k、48k、32k、22.05k、24k、16k、11.025k、12k 和 8k Hz。如果原始采样率是其中之一，则使用原始采样率，否则将重采样为默认值（44.1k）。编码为 WAV 格式时，采样率没有限制，因此将使用原始采样率。提供
encoder_sample_rate将覆盖此行为，并使编码器尝试使用提供的采样率。提供的该值必须是编码器支持的值之一。encoder_num_channels (int 或 None, optional) –
覆盖用于编码的通道数。
与采样率类似，某些编码器（如
"opus"、"vorbis"和"g722"）对可用于编码的通道数有限制。如果编码器支持原始通道数，则将使用它，否则，编码器将尝试将通道重新混音为支持的通道之一。
提供
encoder_num_channels将覆盖此行为，并使编码器尝试使用提供的通道数。提供的该值必须是编码器支持的值之一。encoder_format (str 或 None, optional) –
用于编码媒体的格式。当编码器支持多种格式时，传递此参数将覆盖用于编码的格式。
要列出编码器支持的格式，您可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。注意
当未提供
encoder_format选项时，编码器将使用其默认格式。例如，编码音频为 wav 格式时，使用 16 位带符号整数；编码视频为 mp4 格式（h264 编码器）时，使用 YUV 格式之一。
这是因为音频模型通常使用 32 位或 16 位浮点数，但它们在音频格式中不常用。类似地，RGB24 在视觉模型中常用，但视频格式通常（且更好地）支持 YUV 格式。
codec_config (CodecConfig 或 None, optional) –
编解码器配置。有关配置选项，请参阅
CodecConfig。默认值：
None。filter_desc (str 或 None, optional) – 在编码输入媒体之前应用的附加处理。
add_video_stream¶
- StreamingMediaEncoder.add_video_stream(frame_rate: float, width: int, height: int, format: str = 'rgb24', *, encoder: Optional[str] = None, encoder_option: Optional[Dict[str, str]] = None, encoder_frame_rate: Optional[float] = None, encoder_width: Optional[int] = None, encoder_height: Optional[int] = None, encoder_format: Optional[str] = None, codec_config: Optional[CodecConfig] = None, filter_desc: Optional[str] = None, hw_accel: Optional[str] = None)[源代码]¶
添加一个输出视频流。
必须在调用 open 之前调用此方法。
- 参数
frame_rate (float) – 视频帧率。
width (int) – 视频帧的宽度。
height (int) – 视频帧的高度。
format (str, optional) –
输入像素格式，它决定了输入张量的颜色通道顺序。
"gray8": 一通道，灰度。"rgb24": 三通道，RGB 顺序。"bgr24": 三通道，BGR 顺序。"yuv444p": 三通道，YUV 顺序。
默认值：
"rgb24"。无论哪种情况，输入张量都必须是
torch.uint8类型，并且形状必须是 (帧数, 通道数, 高度, 宽度)。encoder (str 或 None, optional) –
要使用的编码器名称。如果提供了该名称，则使用指定的编码器而不是默认编码器。
要列出可用的编码器，请使用
get_audio_encoders()（用于音频），和get_video_encoders()（用于视频）。默认值：
None。encoder_option (dict 或 None, optional) –
传递给编码器的选项。从 str 映射到 str。
要列出编码器的编码器选项，您可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。除了编码器特定的选项外，还可以传递与多线程相关的选项。这些选项仅在编码器支持时有效。如果两者均未提供，StreamReader 将默认使用单线程。
"threads": 线程数（字符串类型）。提供值"0"将让 FFmpeg 根据其启发式方法进行选择。"thread_type": 要使用哪种多线程方法。有效值为"frame"或"slice"。请注意，每个编码器支持的方法集不同。如果未提供，则使用默认值。"frame": 一次编码多个帧。每个线程处理一个帧。这将增加一个帧/线程的解码延迟。"slice": 一次编码单个帧的多个部分。
encoder_frame_rate (float 或 None, optional) –
覆盖用于编码的帧率。
某些编码器（如
"mpeg1"和"mpeg2"）对可用于编码的帧率有限制。在这种情况下，如果源帧率（由frame_rate提供）不是受支持的帧率之一，则会选择默认帧率，并且帧率会被动态更改。否则，将使用源帧率。提供
encoder_frame_rate将覆盖此行为，并使编码器尝试使用提供的采样率。提供的该值必须是编码器支持的值之一。encoder_width (int 或 None, optional) – 用于编码的图像宽度。这允许在编码过程中更改图像大小。
encoder_height (int 或 None, optional) – 用于编码的图像高度。这允许在编码过程中更改图像大小。
encoder_format (str 或 None, optional) –
用于编码媒体的格式。当编码器支持多种格式时，传递此参数将覆盖用于编码的格式。
要列出编码器支持的格式，您可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。注意
当未提供
encoder_format选项时，编码器将使用其默认格式。例如，编码音频为 wav 格式时，使用 16 位带符号整数；编码视频为 mp4 格式（h264 编码器）时，使用 YUV 格式之一。
这是因为音频模型通常使用 32 位或 16 位浮点数，但它们在音频格式中不常用。类似地，RGB24 在视觉模型中常用，但视频格式通常（且更好地）支持 YUV 格式。
codec_config (CodecConfig 或 None, optional) –
编解码器配置。有关配置选项，请参阅
CodecConfig。默认值：
None。filter_desc (str 或 None, optional) – 在编码输入媒体之前应用的附加处理。
hw_accel (str 或 None, optional) –
启用硬件加速。
例如，当在 CUDA 硬件上编码视频时（encoder=”h264_nvenc”），将 CUDA 设备指示符传递给 hw_accel（即 hw_accel=”cuda:0”）将使 StreamingMediaEncoder 期望视频块是 CUDA 张量。传递 CPU 张量将导致错误。
如果为 None，则视频块张量必须是 CPU 张量。默认值：
None。
close¶
- StreamingMediaEncoder.close()[源代码]¶
关闭输出
StreamingMediaEncoder也是一个上下文管理器，因此支持with语句。建议使用上下文管理器，因为文件会在退出with子句时自动关闭。有关更多详细信息，请参阅
StreamingMediaEncoder.open()。
flush¶
open¶
- StreamingMediaEncoder.open(option: Optional[Dict[str, str]] = None) StreamingMediaEncoder[源代码]¶
打开输出文件/设备并写入头信息。
StreamingMediaEncoder也是一个上下文管理器，因此支持with语句。此方法返回调用它的实例（即 self），以便在 with 语句中使用。建议使用上下文管理器，因为在退出with子句时文件会自动关闭。- 参数
option (dict 或 None, 可选) – 协议、设备和复用器的私有选项。请参阅示例。
- 示例 - 协议选项
>>> s = StreamingMediaEncoder(dst="rtmp://:1234/live/app", format="flv") >>> s.add_video_stream(...) >>> # Passing protocol option `listen=1` makes StreamingMediaEncoder act as RTMP server. >>> with s.open(option={"listen": "1"}) as f: >>> f.write_video_chunk(...)
- 示例 - 设备选项
>>> s = StreamingMediaEncoder("-", format="sdl") >>> s.add_video_stream(..., encoder_format="rgb24") >>> # Open SDL video player with fullscreen >>> with s.open(option={"window_fullscreen": "1"}): >>> f.write_video_chunk(...)
- 示例 - 复用器选项
>>> s = StreamingMediaEncoder("foo.flac") >>> s.add_audio_stream(...) >>> s.set_metadata({"artist": "torio contributors"}) >>> # FLAC muxer has a private option to not write the header. >>> # The resulting file does not contain the above metadata. >>> with s.open(option={"write_header": "false"}) as f: >>> f.write_audio_chunk(...)
set_metadata¶
write_audio_chunk¶
write_video_chunk¶
- StreamingMediaEncoder.write_video_chunk(i: int, chunk: Tensor, pts: Optional[float] = None)[源代码]¶
写入视频/图像数据
- 参数
i (int) – 流索引。
chunk (Tensor) – 视频/图像张量。形状：(时间, 通道, 高, 宽)。
dtype必须为torch.uint8。形状（高、宽和通道数）必须与调用add_video_stream()时配置的相匹配。pts (float, 可选 或 None) –
如果提供，则覆盖显示时间戳。
注意
提供的值将转换为以帧率为基数的整数值。因此，它会被截断为最接近
n / frame_rate的值。
支持结构¶
CodecConfig¶
- class torio.io.CodecConfig(bit_rate: int = -1, compression_level: int = -1, qscale: Optional[int] = None, gop_size: int = -1, max_b_frames: int = -1)[源代码]¶
已弃用
警告
此类已从 2.8 版本开始弃用。它将在 2.9 版本中移除。此弃用是大型重构工作的一部分，目的是将 TorchAudio 转移到维护阶段。PyTorch 对音频和视频的解码和编码功能正在整合到 TorchCodec 中。有关更多信息，请参阅 https://github.com/pytorch/audio/issues/3902。
编解码器配置。
- qscale: Optional[int] = None¶
全局质量因子。启用可变比特率。有效值取决于编码器。
例如：MP3 接受
0-9（https://trac.ffmpeg.org/wiki/Encode/MP3），而 libvorbis 接受-1-10。
