警告

TorchAudio 的 C++ API 是原型功能。 不保证 API/ABI 向后兼容性。

注意

顶级命名空间已从 torchaudio 更改为 torio。 StreamWriter 已重命名为 StreamingMediaEncoder。

torio::io::StreamingMediaEncoder

StreamingMediaEncoder 是 Python 等效实现所使用的实现，并提供类似的接口。 在处理自定义 I/O（例如内存数据）时，可以使用 StreamingMediaEncoderCustomIO 类。

这两个类都定义了相同的方法，因此它们的用法也相同。

构造函数

StreamingMediaEncoder

class StreamingMediaEncoder

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

被 torio::io::StreamingMediaEncoderCustomIO 子类化

explicit torio::io::StreamingMediaEncoder::StreamingMediaEncoder(const std::string &dst, const c10::optional<std::string> &format = c10::nullopt)

从目标 URI 构建 StreamingMediaEncoder

Parameters:

• dst – 写入编码数据的目的地。

• format – 指定输出格式。如果未提供，则从 dst 中推断。

StreamingMediaEncoderCustomIO

class StreamingMediaEncoderCustomIO : private detail::CustomOutput, public torio::io::StreamingMediaEncoder

StreamingMediaDecoder 的子类，可与自定义读取函数配合使用。可用于将媒体编码到内存或自定义对象中。

torio::io::StreamingMediaEncoderCustomIO::StreamingMediaEncoderCustomIO(void *opaque, const c10::optional<std::string> &format, int buffer_size, int (*write_packet)(void *opaque, uint8_t *buf, int buf_size), int64_t (*seek)(void *opaque, int64_t offset, int whence) = nullptr)

使用自定义写入和寻址函数构造 StreamingMediaEncoderCustomIO。

Parameters:

• opaque – 由 write_packet 和 seek 函数使用的自定义数据。

• format – 指定输出格式。

• buffer_size – 中间缓冲区的大小，FFmpeg 使用它向 write_packet 函数传递数据。

• write_packet – 自定义写入函数，由 FFmpeg 调用以将数据实际写入自定义目标。

• seek – 可选的 seek 函数，用于定位目标位置。

配置方法

add_audio_stream

void torio::io::StreamingMediaEncoder::add_audio_stream(int sample_rate, int num_channels, const std::string &format, const c10::optional<std::string> &encoder = c10::nullopt, const c10::optional<OptionDict> &encoder_option = c10::nullopt, const c10::optional<std::string> &encoder_format = c10::nullopt, const c10::optional<int> &encoder_sample_rate = c10::nullopt, const c10::optional<int> &encoder_num_channels = c10::nullopt, const c10::optional<CodecConfig> &codec_config = c10::nullopt, const c10::optional<std::string> &filter_desc = c10::nullopt)

添加输出音频流。

Parameters:

• sample_rate – 采样率。

• num_channels – 通道数量。

• format – 输入样本格式，用于确定输入张量的 dtype。

  • "u8": 输入张量必须是 torch.uint8 类型。

  • "s16": 输入张量必须是 torch.int16 类型。

  • "s32": 输入张量必须是 torch.int32 类型。

  • "s64": 输入张量必须是 torch.int64 类型。

  • "flt": 输入张量必须是 torch.float32 类型。

  • "dbl": 输入张量必须是 torch.float64 类型。

  默认值："flt".

• encoder – 要使用的编码器名称。

  如果提供，则使用指定的编码器而不是默认编码器。

  要列出可用的编码器，您可以使用 ffmpeg -encoders 命令。

• encoder_option – 传递给编码器的选项。要列出某个编码器的编码器选项，您可以使用 ffmpeg -h encoder=<ENCODER>。

• encoder_format – 用于编码媒体的格式。当编码器支持多种格式时，传递此参数将覆盖用于编码的格式。要列出编码器支持的格式，您可以使用 ffmpeg -h encoder=<ENCODER> 命令。

• encoder_sample_rate – 如果提供，则在编码前执行重采样。

• encoder_num_channels – 如果提供，则在编码前更改通道配置。

• codec_config – 编解码器配置。

• filter_desc – 在编码输入数据之前要应用的额外处理

add_video_stream

void torio::io::StreamingMediaEncoder::add_video_stream(double frame_rate, int width, int height, const std::string &format, const c10::optional<std::string> &encoder = c10::nullopt, const c10::optional<OptionDict> &encoder_option = c10::nullopt, const c10::optional<std::string> &encoder_format = c10::nullopt, const c10::optional<double> &encoder_frame_rate = c10::nullopt, const c10::optional<int> &encoder_width = c10::nullopt, const c10::optional<int> &encoder_height = c10::nullopt, const c10::optional<std::string> &hw_accel = c10::nullopt, const c10::optional<CodecConfig> &codec_config = c10::nullopt, const c10::optional<std::string> &filter_desc = c10::nullopt)

添加输出视频流。

Parameters:

• frame_rate – 帧率

• width – 宽度

• height – 高度

• format – 输入像素格式，用于确定输入张量的颜色通道顺序。

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

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

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

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

  无论哪种情况，输入张量都必须是 torch.uint8 类型，且形状必须为 (frame, channel, height, width)。

• 编码器 – 参见 add_audio_stream().

• encoder_option – 参见 add_audio_stream()。

• encoder_format – 参见 add_audio_stream()。

• encoder_frame_rate – 如果提供，则在编码前更改帧率。

• encoder_width – 如果提供，则在编码前调整图像大小。

• encoder_height – 如果提供，则在编码前调整图像大小。

• hw_accel – 启用硬件加速。

• codec_config – 编解码器配置。

  当视频在 CUDA 硬件上编码时，例如 encoder="h264_nvenc"，将 CUDA 设备指示符传递给 hw_accel（即 hw_accel="cuda:0"）将使 StreamingMediaEncoder 期望视频块为 CUDA Tensor。传递 CPU Tensor 将导致错误。

  如果 None，视频块张量必须是 CPU 张量。

• filter_desc – 在编码输入数据之前要应用的额外处理

set_metadata

void torio::io::StreamingMediaEncoder::set_metadata(const OptionDict &metadata)

设置文件级元数据

Parameters:

元数据 – 元数据。

编写方法

打开

void torio::io::StreamingMediaEncoder::open(const c10::optional<OptionDict> &opt = c10::nullopt)

打开输出文件/设备并写入标题。

Parameters:

opt – 协议、设备和复用器的私有选项。

关闭

void torio::io::StreamingMediaEncoder::close()

关闭输出文件/设备并终结元数据。

write_audio_chunk

void torio::io::StreamingMediaEncoder::write_audio_chunk(int i, const torch::Tensor &frames, const c10::optional<double> &pts = c10::nullopt)

写入音频数据

Parameters:

• i – 流索引。

• frames – 波形张量。形状：(frame, channel)。dtype必须与传递给add_audio_stream()方法的值匹配。

• pts –

  演示时间戳。如果提供，它将用提供的值覆盖第一帧的 PTS；否则，PTS 将按采样率的倒数递增。仅处理内部已处理的 PTS 值之外的数值。

  注意：提供的值将被转换为基于采样率的整数值。因此，它会被截断为最接近的 n / sample_rate 值。

write_video_chunk

void torio::io::StreamingMediaEncoder::write_video_chunk(int i, const torch::Tensor &frames, const c10::optional<double> &pts = c10::nullopt)

写入视频数据

Parameters:

• i – 流索引。

• frames – 视频/图像张量。形状：(time, channel, height, width)。dtype 必须是 torch.uint8。形状 (height, width and the number of channels) 必须与调用 add_video_stream() 时配置的内容匹配。

• pts –

  演示时间戳。如果提供，它将用提供的值覆盖第一帧的 PTS；否则，PTS 将根据帧率的倒数进行递增。仅处理内部已处理的 PTS 值之外的数值。

  注意：提供的值会转换为以帧率为基准的整数值。因此，它将被截断为最接近的 n / frame_rate 的值。

flush

void torio::io::StreamingMediaEncoder::flush()

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