警告
Torchaudio 的 C++ API 是原型特性。不保证 API/ABI 向后兼容性。
注意
顶层命名空间已从 torchaudio 更改为 torio。StreamReader 已重命名为 StreamingMediaDecoder。
torio::io::StreamingMediaDecoder¶
StreamingMediaDecoder 是 Python 等效实现使用的类，并提供类似的接口。在使用自定义 I/O（例如内存中的数据）时，可以使用 StreamingMediaDecoderCustomIO 类。
这两个类定义了相同的方法，因此用法相同。
构造函数¶
StreamingMediaDecoder¶
-
class StreamingMediaDecoder¶
逐块获取和解码音频/视频流。
警告
doxygenfunction: 无法在目录 cpp/xml 中项目“libtorio”的 doxygen xml 输出中解析带有参数 (const std::string&, const std::optional<std::string>&, const c10::optional<OptionDict>&) 的函数“torio::io::StreamingMediaDecoder::StreamingMediaDecoder”。潜在匹配项
- 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 – 作为一块（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 tensor。如果为
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¶
用户代码配置的输出流信息。
