StreamingMediaEncoder¶
- class torio.io.StreamingMediaEncoder(dst: Union[str, Path, BinaryIO], format: Optional[str] = None, buffer_size: int = 4096)[source]¶
逐块编码和写入音频/视频流
- 参数:
dst (str, 类路径对象 或 类文件对象) –
编码数据写入的目标位置。如果为字符串类型，则必须是 FFmpeg 可以处理的资源指示符。支持的值取决于系统中找到的 FFmpeg。
如果为类文件对象，则必须支持带有签名 write(data: bytes) -> int 的 write 方法。
有关 write 方法的预期签名和行为，请参阅以下内容。
format (str 或 None, 可选) –
覆盖输出格式，或指定输出媒体设备。默认值：
None（不覆盖也不输出到设备）。此参数有两个不同的用例。
覆盖输出格式。当写入原始数据或格式与扩展名不同时，这很有用。
指定输出设备。这允许将媒体流输出到硬件设备，例如扬声器和视频屏幕。
注意
此选项大致对应于
ffmpeg命令的-f选项。有关可能的值，请参阅 ffmpeg 文档。https://ffmpeg.cpp.org.cn/ffmpeg-formats.html#Muxers
请使用
get_muxers()列出当前环境中可用的多路复用器。对于设备访问，可用值因硬件（AV 设备）和软件配置（ffmpeg 构建）而异。有关可能的值，请参阅 ffmpeg 文档。
https://ffmpeg.cpp.org.cn/ffmpeg-devices.html#Output-Devices
请使用
get_output_devices()列出当前环境中可用的输出设备。buffer_size (int) –
内部缓冲区大小，以字节为单位。仅当 dst 是类文件对象时使用。
默认值：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]] = 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)[source]¶
添加输出音频流。
- 参数:
sample_rate (int) – 采样率。
num_channels (int) – 声道数。
format (str, 可选) –
输入采样格式，它决定了输入张量的数据类型。
"u8": 输入张量必须是torch.uint8类型。"s16": 输入张量必须是torch.int16类型。"s32": 输入张量必须是torch.int32类型。"s64": 输入张量必须是torch.int64类型。"flt": 输入张量必须是torch.float32类型。"dbl": 输入张量必须是torch.float64类型。
默认值：
"flt"。encoder (str 或 None, 可选) –
要使用的编码器名称。如果提供，则使用指定的编码器而不是默认编码器。
要列出可用的编码器，音频请使用
get_audio_encoders()，视频请使用get_video_encoders()。默认值：
None。encoder_option (dict 或 None, 可选) –
传递给编码器的选项。从 str 到 str 的映射。
要列出编码器的选项，可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。除了特定于编码器的选项外，您还可以传递与多线程相关的选项。它们仅在编码器支持时才有效。如果两者均未提供，则 StreamReader 默认为单线程。
"threads"：线程数（以 str 形式）。提供值"0"将让 FFmpeg 根据其启发式方法决定。"thread_type"：要使用的多线程方法。有效值为"frame"或"slice"。请注意，每个编码器都支持不同的方法集。如果未提供，则使用默认值。"frame"：一次编码多个帧。每个线程处理一个帧。这将使解码延迟增加每个线程一帧"slice"：一次编码单个帧的多个部分。
encoder_sample_rate (int 或 None, 可选) –
覆盖用于编码时间的采样率。某些编码器对用于编码的采样率有限制。如果编码器不支持源采样率，则使用源采样率，否则选择默认采样率。
例如，
"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, 可选) –
覆盖用于编码的声道数。
与采样率类似，某些编码器（例如
"opus"、"vorbis"和"g722"）对可用于编码的声道数有限制。如果编码器支持原始声道数，则将使用它，否则，编码器会尝试将声道混合为支持的声道之一。
提供
encoder_num_channels将覆盖此行为，并使编码器尝试使用提供的声道数。提供的值必须是编码器支持的值之一。encoder_format (str 或 None, 可选) –
用于编码媒体的格式。当编码器支持多种格式时，传递此参数将覆盖用于编码的格式。
要列出编码器支持的格式，可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。注意
当未提供
encoder_format选项时，编码器使用其默认格式。例如，当将音频编码为 wav 格式时，使用 16 位有符号整数，当将视频编码为 mp4 格式（h264 编码器）时，使用 YUV 格式之一。
这是因为通常在音频模型中使用 32 位或 16 位浮点数，但它们在音频格式中并不常用。类似地，RGB24 常用于视觉模型，但视频格式通常（并且更好）支持 YUV 格式。
codec_config (CodecConfig 或 None, 可选) –
编解码器配置。有关配置选项，请参阅
CodecConfig。默认值：
None。filter_desc (str 或 None, 可选) – 在编码输入媒体之前应用的其他处理。
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]] = 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)[source]¶
添加输出视频流。
此方法必须在调用 open 之前调用。
- 参数:
frame_rate (float) – 视频的帧率。
width (int) – 视频帧的宽度。
height (int) – 视频帧的高度。
format (str, 可选) –
输入像素格式，它决定了输入张量的颜色通道顺序。
"gray8"：单通道，灰度。"rgb24"：三个通道，顺序为 RGB。"bgr24"：三个通道，顺序为 BGR。"yuv444p"：YUV 顺序的三个通道。
默认值：
"rgb24"。在任何情况下，输入张量都必须是
torch.uint8类型，且形状必须为 (帧, 通道, 高度, 宽度)。encoder (str 或 None, 可选) –
要使用的编码器名称。如果提供，则使用指定的编码器而不是默认编码器。
要列出可用的编码器，音频请使用
get_audio_encoders()，视频请使用get_video_encoders()。默认值：
None。encoder_option (dict 或 None, 可选) –
传递给编码器的选项。从 str 到 str 的映射。
要列出编码器的选项，可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。除了特定于编码器的选项外，您还可以传递与多线程相关的选项。它们仅在编码器支持时才有效。如果两者均未提供，则 StreamReader 默认为单线程。
"threads"：线程数（以 str 形式）。提供值"0"将让 FFmpeg 根据其启发式方法决定。"thread_type"：要使用的多线程方法。有效值为"frame"或"slice"。请注意，每个编码器都支持不同的方法集。如果未提供，则使用默认值。"frame"：一次编码多个帧。每个线程处理一个帧。这将使解码延迟增加每个线程一帧"slice"：一次编码单个帧的多个部分。
encoder_frame_rate (float 或 None，可选) –
覆盖用于编码的帧率。
一些编码器（例如
"mpeg1"和"mpeg2"）对可用于编码的帧率有限制。在这种情况下，如果源帧率（作为frame_rate提供）不是支持的帧率之一，则会选择默认帧率，并动态更改帧率。否则，将使用源帧率。提供
encoder_frame_rate将覆盖此行为，并使编码器尝试使用提供的采样率。提供的值必须是编码器支持的值之一。encoder_width (int 或 None，可选) – 用于编码的图像宽度。这允许在编码期间更改图像大小。
encoder_height (int 或 None，可选) – 用于编码的图像高度。这允许在编码期间更改图像大小。
encoder_format (str 或 None, 可选) –
用于编码媒体的格式。当编码器支持多种格式时，传递此参数将覆盖用于编码的格式。
要列出编码器支持的格式，可以使用
ffmpeg -h encoder=<ENCODER>命令。默认值：
None。注意
当未提供
encoder_format选项时，编码器使用其默认格式。例如，当将音频编码为 wav 格式时，使用 16 位有符号整数，当将视频编码为 mp4 格式（h264 编码器）时，使用 YUV 格式之一。
这是因为通常在音频模型中使用 32 位或 16 位浮点数，但它们在音频格式中并不常用。类似地，RGB24 常用于视觉模型，但视频格式通常（并且更好）支持 YUV 格式。
codec_config (CodecConfig 或 None, 可选) –
编解码器配置。有关配置选项，请参阅
CodecConfig。默认值：
None。filter_desc (str 或 None, 可选) – 在编码输入媒体之前应用的其他处理。
hw_accel (str 或 None，可选) –
启用硬件加速。
当在 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://127.0.0.1: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，optional 或 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)[源代码]¶
编解码器配置。
- qscale: Optional[int] = None¶
全局质量因子。启用可变比特率。有效值取决于编码器。
例如：MP3 采用
0-9(https://trac.ffmpeg.org/wiki/Encode/MP3)，而 libvorbis 采用-1-10。
