警告
TorchAudio 的 C++ API 是原型功能。不保证 API/ABI 向后兼容性。
注意
顶层命名空间已从 torchaudio 更改为 torio。StreamReader 已重命名为 StreamingMediaDecoder。
torio::io::StreamingMediaDecoder¶
StreamingMediaDecoder 是 Python 等效项使用的实现，并提供类似的接口。当使用自定义 I/O（例如内存数据）时，可以使用 StreamingMediaDecoderCustomIO 类。
这两个类都定义了相同的方法，因此它们的用法是相同的。
构造函数¶
StreamingMediaDecoder¶
-
class StreamingMediaDecoder¶
逐块获取和解码音频/视频流。
警告
doxygenfunction: 无法解析函数 “torio::io::StreamingMediaDecoder::StreamingMediaDecoder”，参数为 (const std::string&, const std::optional<std::string>&, const c10::optional<OptionDict>&)，来自目录 cpp/xml 的项目 “libtorio” 的 doxygen xml 输出。可能的匹配项
- StreamingMediaDecoder(const std::string &src, const std::optional<std::string> &format = c10::nullopt, const std::optional<OptionDict> &option = c10::nullopt)
StreamingMediaDecoderCustomIO¶
-
class StreamingMediaDecoderCustomIO : private detail::CustomInput, public torio::io::StreamingMediaDecoder¶
StreamingMediaDecoder 的子类，用于处理自定义读取函数。可用于解码来自内存或自定义对象的媒体。
-
torio::io::StreamingMediaDecoderCustomIO::StreamingMediaDecoderCustomIO(void *opaque, const std::optional<std::string> &format, int buffer_size, int (*read_packet)(void *opaque, uint8_t *buf, int buf_size), int64_t (*seek)(void *opaque, int64_t offset, int whence) = nullptr, const std::optional<OptionDict> &option = c10::nullopt)¶
使用自定义读取和查找函数构造 StreamingMediaDecoder。
- 参数:
opaque –
read_packet和seek函数使用的自定义数据。format – 指定输入格式。
buffer_size – 中间缓冲区的大小，FFmpeg 使用该缓冲区将数据传递给函数 read_packet。
read_packet – 从 FFmpeg 调用的自定义读取函数，用于从目标位置读取数据。
seek – 可选的查找函数，用于查找目标位置。
option – 初始化格式上下文时传递的自定义选项。
查询方法¶
find_best_audio_stream¶
-
int64_t torio::io::StreamingMediaDecoder::find_best_audio_stream() const¶
使用 ffmpeg 的启发式方法查找合适的音频流。
如果成功，则返回最佳流的索引（>=0）。否则返回负值。
find_best_video_stream¶
-
int64_t torio::io::StreamingMediaDecoder::find_best_video_stream() const¶
使用 ffmpeg 的启发式方法查找合适的视频流。
如果成功，则返回最佳流的索引（0>=）。否则返回负值。
get_metadata¶
-
OptionDict torio::io::StreamingMediaDecoder::get_metadata() const¶
获取源媒体的元数据。
num_src_streams¶
-
int64_t torio::io::StreamingMediaDecoder::num_src_streams() const¶
获取输入媒体中找到的源流的数量。
源流不仅包括音频/视频流，还包括字幕和其他流。
get_src_stream_info¶
-
SrcStreamInfo torio::io::StreamingMediaDecoder::get_src_stream_info(int i) const¶
获取有关指定源流的信息。
有效值范围为
[0, num_src_streams())。
num_out_streams¶
-
int64_t torio::io::StreamingMediaDecoder::num_out_streams() const¶
获取客户端代码定义的输出流的数量。
get_out_stream_info¶
-
OutputStreamInfo torio::io::StreamingMediaDecoder::get_out_stream_info(int i) const¶
获取有关指定输出流的信息。
有效值范围为
[0, num_out_streams())。
is_buffer_ready¶
-
bool torio::io::StreamingMediaDecoder::is_buffer_ready() const¶
检查所有输出流的缓冲区是否都有足够的解码帧。
配置方法¶
add_audio_stream¶
-
void torio::io::StreamingMediaDecoder::add_audio_stream(int64_t i, int64_t frames_per_chunk, int64_t num_chunks, const std::optional<std::string> &filter_desc = c10::nullopt, const std::optional<std::string> &decoder = c10::nullopt, const std::optional<OptionDict> &decoder_option = c10::nullopt)¶
定义输出音频流。
- 参数:
i – 源流的索引。
frames_per_chunk – 作为一块返回的帧数。
如果在
frames_per_chunk帧被缓冲之前源流已耗尽，则按原样返回块。因此，块中的帧数可能小于frames_per_chunk。提供
-1将禁用分块，在这种情况下，方法pop_chunks()将返回所有缓冲的帧作为一个块。num_chunks – 内部缓冲区大小。
当缓冲块的数量超过此数量时，将丢弃旧块。例如，如果
frames_per_chunk为 5，而buffer_chunk_size为 3，则将丢弃早于 15 的帧。提供
-1将禁用此行为，强制保留所有块。filter_desc – 应用于源流的滤波器图的描述。
decoder – 要使用的解码器的名称。如果提供，则使用指定的解码器而不是默认解码器。
decoder_option – 传递给解码器的选项。
要列出解码器的解码器选项，可以使用
ffmpeg -h decoder=<DECODER>命令。除了特定于解码器的选项外，您还可以传递与多线程相关的选项。它们仅在解码器支持它们时才有效。如果两者都未提供，则 StreamingMediaDecoder 默认为单线程。
"threads"：线程数或值"0"，以让 FFmpeg 根据其启发式方法决定。"thread_type"：要使用的多线程方法。有效值为"frame"或"slice"。请注意，每个解码器都支持不同的方法集。如果未提供，则使用默认值。"frame"：一次解码多个帧。每个线程处理一个帧。这将使每个线程的解码延迟增加一帧"slice"：一次解码单个帧的多个部分。
add_video_stream¶
-
void torio::io::StreamingMediaDecoder::add_video_stream(int64_t i, int64_t frames_per_chunk, int64_t num_chunks, const std::optional<std::string> &filter_desc = c10::nullopt, const std::optional<std::string> &decoder = c10::nullopt, const std::optional<OptionDict> &decoder_option = c10::nullopt, const std::optional<std::string> &hw_accel = c10::nullopt)¶
定义输出视频流。
- 参数:
i, frames_per_chunk, num_chunks, filter_desc, decoder, decoder_option – 请参阅
add_audio_stream()。hw_accel – 启用硬件加速。
当视频在 CUDA 硬件上解码时（例如，通过指定
"h264_cuvid"解码器），将 CUDA 设备指示符传递给hw_accel（即hw_accel="cuda:0"）将使 StreamingMediaDecoder 将生成的帧直接放置在指定的 CUDA 设备上作为 CUDA 张量。如果为
None，则块将移动到 CPU 内存。
remove_stream¶
-
void torio::io::StreamingMediaDecoder::remove_stream(int64_t i)¶
删除输出流。
- 参数:
i – 要删除的输出流的索引。有效值范围为
[0, num_out_streams())。
流方法¶
seek¶
-
void torio::io::StreamingMediaDecoder::seek(double timestamp, int64_t mode)¶
查找给定的时间戳。
- 参数:
timestamp – 目标时间戳，以秒为单位。
mode – 查找模式。
0：关键帧模式。查找给定时间戳之前的最近关键帧。1：任意模式。查找给定时间戳之前的任何帧（包括非关键帧）。2：精确模式。首先查找给定时间戳之前的最近关键帧，然后解码帧，直到到达最接近给定时间戳的帧。
process_packet¶
-
int torio::io::StreamingMediaDecoder::process_packet()¶
解复用并处理一个数据包。
- 返回值:
0：数据包已成功处理，并且流中仍有数据包，因此客户端代码可以再次调用此方法。1：数据包已成功处理，并且已到达 EOF。客户端代码不应再次调用此方法。<0：发生错误。
process_packet_block¶
-
int torio::io::StreamingMediaDecoder::process_packet_block(const double timeout, const double backoff)¶
类似于
process_packet()，但如果由于资源暂时不可用而失败，它会自动重试。当使用设备输入（如麦克风）时，此行为很有帮助，在此期间，缓冲区在样本采集期间可能会很忙。
- 参数:
timeout – 超时时间，单位为毫秒。
>=0: 持续重试直到超过给定的时间。<0: 永久持续重试。
backoff – 重试前等待的时间，单位为毫秒。
process_all_packets¶
-
void torio::io::StreamingMediaDecoder::process_all_packets()¶
处理数据包直到文件结束 (EOF)。
fill_buffer¶
-
int torio::io::StreamingMediaDecoder::fill_buffer(const std::optional<double> &timeout = c10::nullopt, const double backoff = 10.)¶
处理数据包直到所有块缓冲区至少有一个块。
- 参数:
timeout – 参见
process_packet_block()backoff – 参见
process_packet_block()
检索方法¶
pop_chunks¶
-
std::vector<std::optional<Chunk>> torio::io::StreamingMediaDecoder::pop_chunks()¶
如果每个输出流都有可用的块，则从每个输出流弹出一个块。
支持结构¶
Chunk¶
SrcStreaminfo¶
-
struct SrcStreamInfo¶
关于在输入媒体中找到的源流的信息。
通用成员
-
const char *codec_name = "N/A"¶
编解码器的名称。
-
const char *codec_long_name = "N/A"¶
编解码器的完整名称，更易于理解的形式。
-
const char *fmt_name = "N/A"¶
对于音频，它是采样格式。
常见的取值包括：
"u8","u8p": 8 位无符号整数。"s16","s16p": 16 位有符号整数。"s32","s32p": 32 位有符号整数。"s64","s64p": 64 位有符号整数。"flt","fltp": 32 位浮点数。"dbl","dblp": 64 位浮点数。
对于视频，它是颜色通道格式。
常见的取值包括：
"gray8": 灰度"rgb24": RGB"bgr24": BGR"yuv420p": YUV420p
-
int64_t bit_rate = 0¶
比特率。
-
int64_t num_frames = 0¶
帧数。
注意
在某些格式中，该值不可靠或不可用。
-
int bits_per_sample = 0¶
每个采样的位数。
-
OptionDict metadata = {}¶
元数据
此方法可以从 MP3 中获取 ID3 标签。
示例
{ "title": "foo", "artist": "bar", "date": "2017" }
-
const char *codec_name = "N/A"¶
OutputStreaminfo¶
-
struct OutputStreamInfo¶
关于用户代码配置的输出流的信息。
