警告
TorchAudio 的 C++ API 是一项原型功能。 不保证 API/ABI 向后兼容性。
注意
顶级命名空间已从 torchaudio 更改为 torio。
StreamReader 已重命名为 StreamingMediaDecoder。
torio::io::StreamingMediaDecoder¶
StreamingMediaDecoder 是 Python 等效实现所使用的实现，并提供类似的接口。
在处理自定义 I/O（例如内存数据）时，可以使用 StreamingMediaDecoderCustomIO 类。
这两个类都定义了相同的方法，因此它们的用法也相同。
构造函数¶
StreamingMediaDecoder¶
-
class StreamingMediaDecoder¶
逐块获取并解码音频/视频流。
Subclassed by torio::io::StreamingMediaDecoderCustomIO
-
explicit torio::io::StreamingMediaDecoder::StreamingMediaDecoder(const std::string &src, const c10::optional<std::string> &format = c10::nullopt, const c10::optional<OptionDict> &option = c10::nullopt)¶
从源 URI 构建媒体处理器。
- Parameters:
src – 源媒体的 URL，采用 FFmpeg 可理解的格式。
format – 指定格式（如 mp4）或设备（如 lavfi 和 avfoundation）
option – 初始化格式上下文（打开源）时传递的自定义选项。
StreamingMediaDecoderCustomIO¶
-
class StreamingMediaDecoderCustomIO : private detail::CustomInput, public torio::io::StreamingMediaDecoder¶
StreamingMediaDecoder 的子类，可与自定义读取函数配合使用。可用于从内存或自定义对象解码媒体。
-
torio::io::StreamingMediaDecoderCustomIO::StreamingMediaDecoderCustomIO(void *opaque, const c10::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 c10::optional<OptionDict> &option = c10::nullopt)¶
使用自定义的读取和寻道函数构建 StreamingMediaDecoder。
- Parameters:
opaque – 由
read_packet和seek函数使用的自定义数据。format – 指定输入格式。
buffer_size – 中间缓冲区的大小，FFmpeg 使用它向 read_packet 函数传递数据。
read_packet – 自定义读取函数，由 FFmpeg 调用以从目标位置读取数据。
seek – 可选的 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 c10::optional<std::string> &filter_desc = c10::nullopt, const c10::optional<std::string> &decoder = c10::nullopt, const c10::optional<OptionDict> &decoder_option = c10::nullopt)¶
定义一个输出音频流。
- Parameters:
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 c10::optional<std::string> &filter_desc = c10::nullopt, const c10::optional<std::string> &decoder = c10::nullopt, const c10::optional<OptionDict> &decoder_option = c10::nullopt, const c10::optional<std::string> &hw_accel = c10::nullopt)¶
定义输出视频流。
- Parameters:
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)¶
移除一个输出流。
- Parameters:
i – 要移除的输出流的索引。有效值范围是
[0, num_out_streams())。
流方法¶
搜索¶
-
void torio::io::StreamingMediaDecoder::seek(double timestamp, int64_t mode)¶
跳转到指定的时间戳。
- Parameters:
timestamp – 目标时间戳（秒）。
mode – 搜索模式。
0: 关键帧模式。在给定时间戳之前跳转到最近的关键帧。1: 任意模式。在给定时间戳之前，搜索到任意帧（包括非关键帧）。2: 精确模式。首先跳转到给定时间戳之前的最近关键帧，然后解码帧直到到达最接近给定时间戳的帧。
process_packet¶
-
int torio::io::StreamingMediaDecoder::process_packet()¶
解复用并处理一个数据包。
- Returns:
0: 数据包已成功处理，且流中仍有剩余数据包，因此客户端代码可以再次调用此方法。1: 数据包已成功处理并到达文件末尾（EOF）。客户端代码不应再次调用此方法。<0: 发生了一个错误。
process_packet_block¶
-
int torio::io::StreamingMediaDecoder::process_packet_block(const double timeout, const double backoff)¶
类似于
process_packet()，但如果因资源暂时不可用而失败，它会自动重试。在使用设备输入（例如麦克风）时，此行为非常有用，因为在采样采集过程中缓冲区可能处于繁忙状态。
- Parameters:
timeout – 超时时间，单位为毫秒。
>=0: 持续重试直到给定时间过去。<0: 永远重试。
backoff – 重试前等待的时间，单位为毫秒。
process_all_packets¶
-
void torio::io::StreamingMediaDecoder::process_all_packets()¶
处理数据包直到文件结束。
fill_buffer¶
-
int torio::io::StreamingMediaDecoder::fill_buffer(const c10::optional<double> &timeout = c10::nullopt, const double backoff = 10.)¶
处理数据包，直到所有块缓冲区至少包含一个块。
- Parameters:
timeout – 参见
process_packet_block()backoff – 参见
process_packet_block()
检索方法¶
pop_chunks¶
-
std::vector<c10::optional<Chunk>> torio::io::StreamingMediaDecoder::pop_chunks()¶
如果可用，则从每个输出流中弹出一个块。
支持结构¶
块¶
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 标签。
Example:
{ "title": "foo", "artist": "bar", "date": "2017" }
-
const char *codec_name = "N/A"¶
OutputStreaminfo¶
-
struct OutputStreamInfo¶
有关用户代码配置的输出流的信息。