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

顶级命名空间已从 torchaudio 更改为 torio。StreamReader 已更名为 StreamingMediaDecoder。

torio::io::StreamingMediaDecoder

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

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

构造函数

StreamingMediaDecoder

classStreamingMediaDecoder

逐块获取并解码音频/视频流。

由 torio::io::StreamingMediaDecoderCustomIO 子类化

doxygenfunction: 无法解析函数“torio::io::StreamingMediaDecoder::StreamingMediaDecoder”，参数为(const std::string&, const std::optional

- StreamingMediaDecoder(const std::string &src, const std::optional<std::string> &format = c10::nullopt, const std::optional<OptionDict> &option = c10::nullopt)

StreamingMediaDecoderCustomIO

classStreamingMediaDecoderCustomIO:privatedetail::CustomInput,publictorio::io::StreamingMediaDecoder

StreamingMediaDecoder 的一个子类，支持自定义读取函数。可用于从内存或自定义对象中解码媒体。

torio::io::StreamingMediaDecoderCustomIO::StreamingMediaDecoderCustomIO(void*opaque, conststd::optional

使用自定义的读取和定位函数构造 StreamingMediaDecoder。

参数：

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

• format – 指定输入格式。

• buffer_size – 中间缓冲区的大小，FFmpeg 使用该缓冲区将数据传递给 read_packet 函数。

• read_packet – 自定义读取函数，FFmpeg 调用该函数从目标读取数据。

• seek – 可选的定位函数，用于在目标中进行定位。

• option – 初始化格式上下文时传递的自定义选项。

查询方法

find_best_audio_stream

int64_ttorio::io::StreamingMediaDecoder::find_best_audio_stream()const

使用 ffmpeg 的启发式方法查找合适的音频流。

如果成功，则返回最佳流的索引（>=0）。否则返回负值。

find_best_video_stream

int64_ttorio::io::StreamingMediaDecoder::find_best_video_stream()const

使用 ffmpeg 的启发式方法查找合适的视频流。

如果成功，则返回最佳流的索引（0 或更大）。否则返回负值。

get_metadata

OptionDicttorio::io::StreamingMediaDecoder::get_metadata()const

获取源媒体的元数据。

num_src_streams

int64_ttorio::io::StreamingMediaDecoder::num_src_streams()const

获取输入媒体中找到的源流数量。

源流不仅包括音频/视频流，还包括字幕和其他流。

get_src_stream_info

SrcStreamInfotorio::io::StreamingMediaDecoder::get_src_stream_info(inti)const

获取指定源流的信息。

有效值范围为 [0, numsrcstreams())。

num_out_streams

int64_ttorio::io::StreamingMediaDecoder::num_out_streams()const

获取由客户端代码定义的输出流数量。

get_out_stream_info

OutputStreamInfotorio::io::StreamingMediaDecoder::get_out_stream_info(inti)const

获取指定输出流的信息。

有效值范围为 [0, numoutstreams())。

is_buffer_ready

booltorio::io::StreamingMediaDecoder::is_buffer_ready()const

检查输出流的所有缓冲区是否有足够的解码帧。

配置方法

添加音频流

voidtorio::io::StreamingMediaDecoder::add_audio_stream(int64_ti, int64_tframes_per_chunk, int64_tnum_chunks, conststd::optional

定义一个输出音频流。

参数:

• 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

voidtorio::io::StreamingMediaDecoder::add_video_stream(int64_ti, int64_tframes_per_chunk, int64_tnum_chunks, conststd::optional

定义一个输出视频流。

参数:

• i, frames_per_chunk, num_chunks, filter_desc, decoder, decoder_option – 参见 addaudiostream()。

• hw_accel – 启用硬件加速。

  当视频在 CUDA 硬件上解码时（例如通过指定 "h264_cuvid" 解码器），将 CUDA 设备指示符传递给 hw_accel（即 hw_accel="cuda:0"）将使 StreamingMediaDecoder 将生成的帧直接放置在指定的 CUDA 设备上作为 CUDA 张量。

  如果为 None，则块将被移动到 CPU 内存中。

remove_stream

voidtorio::io::StreamingMediaDecoder::remove_stream(int64_ti)

移除一个输出流。

参数：

i – 要移除的输出流的索引。有效值范围为 [0, numoutstreams())。

流方法

定位

voidtorio::io::StreamingMediaDecoder::seek(doubletimestamp, int64_tmode)

定位到指定的时间戳。

参数:

• timestamp – 目标时间戳，单位为秒。

• mode – 搜索模式。

  • 0: 关键帧模式。在给定时间戳之前，定位到最近的关键帧。

  • 1: 任意模式。在给定时间戳之前，定位到任意帧（包括非关键帧）。

  • 2: 精确模式。首先在给定时间戳之前定位到最近的关键帧，然后解码帧直到达到最接近给定时间戳的帧。

process_packet

inttorio::io::StreamingMediaDecoder::process_packet()

解复用并处理一个数据包。

返回值：

• 0: 数据包已成功处理，且流中仍有剩余数据包，因此客户端代码可以再次调用此方法。

• 1: 数据包已成功处理，并且已到达文件末尾（EOF）。客户端代码不应再次调用此方法。

• <0: 发生了错误。

process_packet_block

inttorio::io::StreamingMediaDecoder::processpacketblock(const double timeout, const double backoff)

类似于 process_packet()，但在由于资源暂时不可用而导致失败时，它会自动重试。

这种行为在使用设备输入（例如麦克风）时非常有用，因为在采样获取过程中，缓冲区可能处于忙碌状态。

参数：

• timeout – 超时时间，单位为毫秒。

  • >=0: 持续重试，直到超过指定时间。

  • <0: 无限重试。

• backoff – 重试前的等待时间，单位为毫秒。

process_all_packets

voidtorio::io::StreamingMediaDecoder::process_all_packets()

处理数据包直到文件结束符（EOF）。

fill_buffer

inttorio::io::StreamingMediaDecoder::fill_buffer(conststd::optional\

处理数据包，直到所有块缓冲区至少有一个块

参数:

• timeout – 参见 processpacketblock()

• backoff – 参见 processpacketblock()

数据获取方法

pop_chunks

std::vector\

从每个输出流中弹出一个可用的数据块。

支持结构

数据块

源流信息

{
  "title": "foo",
  "artist": "bar",
  "date": "2017"
}

输出流信息