警告
TorchAudio 的 C++ API 处于原型阶段。API/ABI 向后兼容性无法保证。
注意
顶级命名空间已从 torchaudio
更改为 torio
。 StreamWriter
已重命名为 StreamingMediaEncoder
。
torio::io::StreamingMediaEncoder¶
StreamingMediaEncoder
是 Python 等效实现使用的实现,并提供类似的接口。在处理自定义 I/O(例如内存中数据)时,可以使用 StreamingMediaEncoderCustomIO
类。
这两个类都定义了相同的方法,因此它们的用法相同。
构造函数¶
StreamingMediaEncoder¶
-
class StreamingMediaEncoder¶
逐块编码和写入音频/视频流
-
explicit torio::io::StreamingMediaEncoder::StreamingMediaEncoder(const std::string &dst, const std::optional<std::string> &format = c10::nullopt)¶
从目标 URI 构造 StreamingMediaEncoder
- 参数:
dst – 编码数据写入的目标位置。
format – 指定输出格式。如果未提供,则从
dst
推断。
StreamingMediaEncoderCustomIO¶
-
class StreamingMediaEncoderCustomIO : private detail::CustomOutput, public torio::io::StreamingMediaEncoder¶
StreamingMediaDecoder 的一个子类,它使用自定义读取函数。可用于将媒体编码到内存或自定义对象中。
-
torio::io::StreamingMediaEncoderCustomIO::StreamingMediaEncoderCustomIO(void *opaque, const std::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。
- 参数:
opaque –
write_packet
和seek
函数使用的自定义数据。format – 指定输出格式。
buffer_size – 中间缓冲区的大小,FFmpeg 使用它将数据传递给 write_packet 函数。
write_packet – 从 FFmpeg 调用以将数据实际写入自定义目标的自定义写入函数。
seek – 用于查找目标的可选查找函数。
配置方法¶
添加音频流¶
-
void torio::io::StreamingMediaEncoder::add_audio_stream(int sample_rate, int num_channels, const std::string &format, const std::optional<std::string> &encoder = c10::nullopt, const std::optional<OptionDict> &encoder_option = c10::nullopt, const std::optional<std::string> &encoder_format = c10::nullopt, const std::optional<int> &encoder_sample_rate = c10::nullopt, const std::optional<int> &encoder_num_channels = c10::nullopt, const std::optional<CodecConfig> &codec_config = c10::nullopt, const std::optional<std::string> &filter_desc = c10::nullopt)¶
添加一个输出音频流。
- 参数:
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 – 在编码输入数据之前应用的其他处理
添加视频流¶
-
void torio::io::StreamingMediaEncoder::add_video_stream(double frame_rate, int width, int height, const std::string &format, const std::optional<std::string> &encoder = c10::nullopt, const std::optional<OptionDict> &encoder_option = c10::nullopt, const std::optional<std::string> &encoder_format = c10::nullopt, const std::optional<double> &encoder_frame_rate = c10::nullopt, const std::optional<int> &encoder_width = c10::nullopt, const std::optional<int> &encoder_height = c10::nullopt, const std::optional<std::string> &hw_accel = c10::nullopt, const std::optional<CodecConfig> &codec_config = c10::nullopt, const std::optional<std::string> &filter_desc = c10::nullopt)¶
添加输出视频流。
- 参数:
frame_rate – 帧率
width – 宽度
height – 高度
format – 输入像素格式,确定输入张量的颜色通道顺序。
"gray8"
: 单通道,灰度。"rgb24"
: 三通道,RGB顺序。"bgr24"
: 三通道,BGR顺序。"yuv444p"
: 三通道,YUV顺序。
在任何一种情况下,输入张量都必须是
torch.uint8
类型,并且形状必须为(帧,通道,高度,宽度)。encoder – 参见
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 张量。传递 CPU 张量会导致错误。如果为
None
,则视频块张量必须是 CPU 张量。filter_desc – 在编码输入数据之前应用的其他处理
set_metadata¶
-
void torio::io::StreamingMediaEncoder::set_metadata(const OptionDict &metadata)¶
设置文件级元数据
- 参数:
metadata – 元数据。
写入方法¶
open¶
-
void torio::io::StreamingMediaEncoder::open(const std::optional<OptionDict> &opt = c10::nullopt)¶
打开输出文件/设备并写入头信息。
- 参数:
opt – 协议、设备和复用器的私有选项。
close¶
-
void torio::io::StreamingMediaEncoder::close()¶
关闭输出文件/设备并完成元数据。
write_audio_chunk¶
-
void torio::io::StreamingMediaEncoder::write_audio_chunk(int i, const torch::Tensor &frames, const std::optional<double> &pts = c10::nullopt)¶
写入音频数据
- 参数:
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 std::optional<double> &pts = c10::nullopt)¶
写入视频数据
- 参数:
i – 流索引。
frames – 视频/图像张量。形状:
(time, channel, height, width)
。dtype
必须为torch.uint8
。形状(height, width 和 通道数)
必须与调用add_video_stream()
时配置的匹配。pts –
显示时间戳。如果提供,它将用提供的值覆盖第一个帧的 PTS。否则,PTS 将根据帧率的倒数递增。仅值超过内部处理的 PTS 值。
注意:提供的值将转换为以帧率为基础的整数值。因此,它将截断到最接近的
n / frame_rate
值。
flush¶
-
void torio::io::StreamingMediaEncoder::flush()¶
刷新编码器中的帧并将帧写入目标。