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
。