快捷方式

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) -> intwrite 方法。

    有关 write 方法的预期签名和行为,请参阅以下内容。

  • format (strNone, 可选) –

    覆盖输出格式,或指定输出媒体设备。默认值:None(不覆盖也不输出到设备)。

    此参数有两个不同的用例。

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

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

    注意

    此选项大致对应于 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 (strNone, 可选) –

    要使用的编码器名称。如果提供,则使用指定的编码器而不是默认编码器。

    要列出可用的编码器,音频请使用 get_audio_encoders(),视频请使用 get_video_encoders()

    默认值:None

  • encoder_option (dictNone, 可选) –

    传递给编码器的选项。从 str 到 str 的映射。

    要列出编码器的选项,可以使用 ffmpeg -h encoder=<ENCODER> 命令。

    默认值:None


    除了特定于编码器的选项外,您还可以传递与多线程相关的选项。它们仅在编码器支持时才有效。如果两者均未提供,则 StreamReader 默认为单线程。

    "threads":线程数(以 str 形式)。提供值 "0" 将让 FFmpeg 根据其启发式方法决定。

    "thread_type":要使用的多线程方法。有效值为 "frame""slice"。请注意,每个编码器都支持不同的方法集。如果未提供,则使用默认值。

    • "frame":一次编码多个帧。每个线程处理一个帧。这将使解码延迟增加每个线程一帧

    • "slice":一次编码单个帧的多个部分。


  • encoder_sample_rate (intNone, 可选) –

    覆盖用于编码时间的采样率。某些编码器对用于编码的采样率有限制。如果编码器不支持源采样率,则使用源采样率,否则选择默认采样率。

    例如,"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 (intNone, 可选) –

    覆盖用于编码的声道数。

    与采样率类似,某些编码器(例如 "opus""vorbis""g722")对可用于编码的声道数有限制。

    如果编码器支持原始声道数,则将使用它,否则,编码器会尝试将声道混合为支持的声道之一。

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

  • encoder_format (strNone, 可选) –

    用于编码媒体的格式。当编码器支持多种格式时,传递此参数将覆盖用于编码的格式。

    要列出编码器支持的格式,可以使用 ffmpeg -h encoder=<ENCODER> 命令。

    默认值:None

    注意

    当未提供 encoder_format 选项时,编码器使用其默认格式。

    例如,当将音频编码为 wav 格式时,使用 16 位有符号整数,当将视频编码为 mp4 格式(h264 编码器)时,使用 YUV 格式之一。

    这是因为通常在音频模型中使用 32 位或 16 位浮点数,但它们在音频格式中并不常用。类似地,RGB24 常用于视觉模型,但视频格式通常(并且更好)支持 YUV 格式。

  • codec_config (CodecConfigNone, 可选) –

    编解码器配置。有关配置选项,请参阅 CodecConfig

    默认值:None

  • filter_desc (strNone, 可选) – 在编码输入媒体之前应用的其他处理。

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

    要使用的编码器名称。如果提供,则使用指定的编码器而不是默认编码器。

    要列出可用的编码器,音频请使用 get_audio_encoders(),视频请使用 get_video_encoders()

    默认值:None

  • encoder_option (dictNone, 可选) –

    传递给编码器的选项。从 str 到 str 的映射。

    要列出编码器的选项,可以使用 ffmpeg -h encoder=<ENCODER> 命令。

    默认值:None


    除了特定于编码器的选项外,您还可以传递与多线程相关的选项。它们仅在编码器支持时才有效。如果两者均未提供,则 StreamReader 默认为单线程。

    "threads":线程数(以 str 形式)。提供值 "0" 将让 FFmpeg 根据其启发式方法决定。

    "thread_type":要使用的多线程方法。有效值为 "frame""slice"。请注意,每个编码器都支持不同的方法集。如果未提供,则使用默认值。

    • "frame":一次编码多个帧。每个线程处理一个帧。这将使解码延迟增加每个线程一帧

    • "slice":一次编码单个帧的多个部分。


  • encoder_frame_rate (floatNone,可选) –

    覆盖用于编码的帧率。

    一些编码器(例如 "mpeg1""mpeg2")对可用于编码的帧率有限制。在这种情况下,如果源帧率(作为 frame_rate 提供)不是支持的帧率之一,则会选择默认帧率,并动态更改帧率。否则,将使用源帧率。

    提供 encoder_frame_rate 将覆盖此行为,并使编码器尝试使用提供的采样率。提供的值必须是编码器支持的值之一。

  • encoder_width (intNone,可选) – 用于编码的图像宽度。这允许在编码期间更改图像大小。

  • encoder_height (intNone,可选) – 用于编码的图像高度。这允许在编码期间更改图像大小。

  • encoder_format (strNone, 可选) –

    用于编码媒体的格式。当编码器支持多种格式时,传递此参数将覆盖用于编码的格式。

    要列出编码器支持的格式,可以使用 ffmpeg -h encoder=<ENCODER> 命令。

    默认值:None

    注意

    当未提供 encoder_format 选项时,编码器使用其默认格式。

    例如,当将音频编码为 wav 格式时,使用 16 位有符号整数,当将视频编码为 mp4 格式(h264 编码器)时,使用 YUV 格式之一。

    这是因为通常在音频模型中使用 32 位或 16 位浮点数,但它们在音频格式中并不常用。类似地,RGB24 常用于视觉模型,但视频格式通常(并且更好)支持 YUV 格式。

  • codec_config (CodecConfigNone, 可选) –

    编解码器配置。有关配置选项,请参阅 CodecConfig

    默认值:None

  • filter_desc (strNone, 可选) – 在编码输入媒体之前应用的其他处理。

  • hw_accel (strNone,可选) –

    启用硬件加速。

    当在 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 (dictNone,可选) – 协议、设备和复用器的私有选项。请参见示例。

示例 - 协议选项
>>> 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

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

设置文件级元数据

参数:

metadata (dictNone,可选) – 文件级元数据。

write_audio_chunk

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

写入音频数据

参数:
  • i (int) – 流索引。

  • chunk (Tensor) – 波形张量。形状:(帧, 通道)dtype 必须与传递给 add_audio_stream() 方法的内容匹配。

  • pts (floatoptional,或 None) –

    如果提供,则覆盖演示时间戳。

    注意

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

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 (floatoptionalNone) –

    如果提供,则覆盖演示时间戳。

    注意

    提供的值将转换为以帧率为基准的整数值。因此,它将被截断为最接近 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 表示 intra_only

max_b_frames: int = -1

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

文档

访问 PyTorch 的全面开发者文档

查看文档

教程

获取面向初学者和高级开发者的深入教程

查看教程

资源

查找开发资源并获得您的问题解答

查看资源