StreamingMediaEncoder

class torio.io.StreamingMediaEncoder(dst: Union[str, Path, BinaryIO], format: Optional[str] = None, buffer_size: int = 4096)

逐块编码并写入音频/视频流

参数：

• dst (str, 路径类型 或 类文件对象) –

  编码数据写入的目标位置。如果为字符串类型，则必须是 FFmpeg 可以处理的资源指示符。支持的值取决于系统中找到的 FFmpeg。

  如果为类文件对象，则必须支持 write 方法，其签名为 write(data: bytes) -> int。

  请参阅以下内容以了解 write 方法的预期签名和行为。

  • https://docs.pythonlang.cn/3/library/io.html#io.BufferedIOBase.write

• format (str 或 None, 可选) –

  覆盖输出格式，或指定输出媒体设备。默认值：None（不覆盖也不输出设备）。

  此参数用于两种不同的用例。

  1. 覆盖输出格式。当写入原始数据或以不同于扩展名的格式写入时，这很有用。

  2. 指定输出设备。这允许将媒体流输出到硬件设备，例如扬声器和视频屏幕。

  注意

  此选项大致对应于 -f ffmpeg 命令选项。请参阅 ffmpeg 文档以了解可能的值。

  https://ffmpeg.org/ffmpeg-formats.html#Muxers

  请使用 get_muxers() 列出当前环境中可用的多路复用器。

  对于设备访问，可用值会根据硬件（AV 设备）和软件配置（ffmpeg 构建）而有所不同。请参阅 ffmpeg 文档以了解可能的值。

  https://ffmpeg.org/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, 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, 可选) –

  输入样本格式，决定输入张量的 dtype。

  • "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 将覆盖此行为，并使编码器尝试使用提供的采样率。提供的 value 必须是编码器支持的之一。

• encoder_num_channels (int 或 None, 可选) –

  覆盖用于编码的声道数。

  与采样率类似，某些编码器（例如 "opus"、"vorbis" 和 "g722"）对可用于编码的声道数有限制。

  如果编码器支持原始声道数，则将使用它，否则，编码器尝试将声道混音到支持的声道之一。

  提供 encoder_num_channels 将覆盖此行为，并使编码器尝试使用提供的声道数。提供的 value 必须是编码器支持的之一。

• 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, 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, 可选) –

  输入像素格式，决定输入张量的颜色通道顺序。

  • "gray8"：单通道，灰度。

  • "rgb24"：三个通道，顺序为RGB。

  • "bgr24"：三个通道，顺序为BGR。

  • "yuv444p"：三个通道，顺序为YUV。

  默认："rgb24"。

  在这两种情况下，输入张量必须为 torch.uint8 类型，形状必须为 (frame, channel, height, width)。

• 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

StreamingMediaEncoder.flush()

刷新编码器中的帧并将帧写入目标位置。

open

StreamingMediaEncoder.open(option: Optional[Dict[str, str]] = None) → StreamingMediaEncoder

打开输出文件/设备并写入头部。

StreamingMediaEncoder 也是一个上下文管理器，因此支持 with 语句。此方法返回调用该方法的实例（即 self），以便可以在 with 语句中使用。建议使用上下文管理器，因为在退出 with 子句时，文件会自动关闭。

参数：

option (字典 或 None, 可选) – 协议、设备和复用器的私有选项。请参阅示例。

示例 - 协议选项

>>> s = StreamingMediaEncoder(dst="rtmp://localhost: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

StreamingMediaEncoder.set_metadata(metadata: Dict[str, str])

设置文件级元数据

参数：

metadata (字典 或 None, 可选) – 文件级元数据。

write_audio_chunk

StreamingMediaEncoder.write_audio_chunk(i: int, chunk: Tensor, pts: Optional[float] = None)

写入音频数据

参数：

• i (整数) – 流索引。

• chunk (张量) – 波形张量。形状：(帧数, 通道数)。其 dtype 必须与传递给 add_audio_stream() 方法的类型匹配。

• pts (浮点数, 可选 或 None) –

  如果提供，则覆盖表示时间戳。

  注意

  提供的数值将转换为以采样率为基础的整数值。因此，它将截断为最接近 n / sample_rate 的值。

write_video_chunk

StreamingMediaEncoder.write_video_chunk(i: int, chunk: Tensor, pts: Optional[float] = None)

写入视频/图像数据

参数：

• i (整数) – 流索引。

• chunk (张量) – 视频/图像张量。形状：(时间, 通道数, 高度, 宽度)。其 dtype 必须为 torch.uint8。形状（高度、宽度和通道数）必须与调用 add_video_stream() 时配置的形状匹配。

• pts (浮点数, 可选 或 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)

编解码器配置。

bit_rate: int = -1

比特率

compression_level: int = -1

压缩级别

qscale: Optional[int] = None

全局质量因子。启用可变比特率。有效值取决于编码器。

例如：MP3 使用 0 - 9 (https://trac.ffmpeg.org/wiki/Encode/MP3)，而 libvorbis 使用 -1 - 10。

gop_size: int = -1

一组图像中的图像数量，或 0 表示仅使用帧内编码。

max_b_frames: int = -1

非 B 帧之间 B 帧的最大数量。