ffprobe文档

英文原文链接：https://ffmpeg.org/ffprobe.html
结合机翻，不保证准确性

1 用法

ffprobe [options] input_url

2 说明

ffprobe从多媒体流从收集信息，然后以人类可读或机器可读的格式输出。

例如ffprobe可以用于检查多媒体流使用的容器的格式以及其中每个媒体流的格式与类型。

如果指定了输入文件路径，ffprobe会尝试打开指定文件，并解析其内容。如果路径不能被打开或识别为多媒体文件，ffprobe会返回一个正值的退出码。

如果没有用指定输出，ffprobe会写到标准输出。

ffprobe既可以用作独立的应用程序，也可以与文本过滤器结合使用，后者可以执行更复杂的处理，例如统计处理或绘图。

[options]用于列出ffprobe支持的一些格式，或指定要显示的信息，以及设置ffprobe显示信息的方式。

ffprobe输出被设计可以通过文本过滤器轻松解析，并且由output_format选项指定的输出格式定义的表单的一个或多个部分组成。

部分可以包含其他嵌套的部分，并且由名称（可以由其他部分共享）和唯一名称标识。请参见各部分的输出。

存储在容器或流中的元数据标签被识别并打印在相应的“FORMAT”、“STREAM”、“STREAM_GROUP_STREAM”或“DATA_STREAM”部分中。

3 选项

所有数值选项，如果没有另外指定，则接受表示数字的字符串作为输入，该字符串可以后跟SI单位前缀之一，例如：‘K’，‘M’或’G’。

如果“i”被附加到SI单位前缀，则完整的前缀将被解释为基于1024的幂而不是1000的幂的二进制倍数的单位前缀。将“B”插入SI单位前缀将值乘以8。这允许使用例如：‘KB’，‘MiB’，'G’和’B’作为数字后缀。

不带参数的选项是布尔选项，并将相应的值设置为true。可以通过在选项名称前加上“no”来将它们设置为false。例如，使用“-nofoo”会将名为“foo”的布尔选项设置为false。

接受参数的选项支持一种特殊的语法，在这种语法中，命令行给出的参数被解释为加载实际参数值的文件的路径。要使用此功能，请在选项名称前（前导破折号后）添加正斜杠“/”。例如

ffmpeg -i INPUT -/filter:v filter.script OUTPUT

将从名为filter.script的文件中加载过滤器图描述。

3.1 流说明符

某些选项是按每个流使用的，例如比特率或编解码器。流说明符用于精确指定给定选项属于哪个流。

流说明符是一个字符串，通常附加在选项名之后，并用冒号与选项名分隔。例如，-codec:a:1 ac3包含a:1流说明符，它与第二个音频流匹配。因此，它将为第二音频流采用ac3编解码器。

一个流说明符可以匹配多个流，以便选项可以批量应用。例如，流说明符-b:a 128k匹配所有音频流。

空流说明符匹配所有流。例如，-codec copy或-codec: copy将复制所有流而不重新编码。

流说明符的可能形式有：

• stream_index
  将流与此索引匹配。例如，-threads:1 4会将第二个流的线程数设置为4。如果stream_index被用作一个额外的流指定符（见下文），那么它会从匹配的流中选择流编号为stream_index的流。流编号基于libavformat检测到的流顺序，除非还指定了流组说明符或程序ID。在这种情况下，它基于组或程序中的流的排序。
• stream_type[:additional_stream_specifier]
stream_type是以下类型之一：'v’或’V’表示视频，'a’表示音频，'s’表示字幕，'d’表示数据，'t’表示附件。'v’匹配所有视频流，'V’只匹配不是附加图片、视频缩略图或封面艺术的视频流。如果使用了additional_stream_specifier，则它匹配具有此类型并匹配additional_stream_specifier的流。否则，它将匹配指定类型的所有流。
• g:group_specifier[:additional_stream_specifier]
  匹配group_specifier组中的流。如果使用了additional_stream_specifier，则它匹配都是该组的一部分并且与additional_stream_specifier匹配的流。group_specifier可以是以下之一：
  • group_index
    将流与此组索引匹配。
  • #group_id or i:group_id
    将流与此组ID匹配。
• p:program_id[:additional_stream_specifier]
  匹配程序中具有id program_id的流。如果使用了additional_stream_specifier，则它匹配既是程序的一部分又匹配additional_stream_specifier的流。
• #stream_id or i:stream_id
  通过流id匹配流（例如，MPEG-TS容器中的PID）。
• m:key[:value]
  匹配具有指定值的元数据标记key的流。如果未指定value，则匹配包含给定标记的流的任何值。key或value中的冒号字符“:”需要进行反斜杠转义。
• disp:dispositions[:additional_stream_specifier]
  匹配具有给定处理的流。dispositions是一个或多个处置的列表（由-dispositions选项输出）并用’+'连接。
• u
  匹配与可用配置匹配的流，编解码器必须被定义以及基本信息，如视频尺寸或音频采样率必须存在。
  注意，在ffmpeg中，通过元数据进行匹配只对输入文件有效。

3.2 通用选项

这些选项在ff* 工具中共享。

• -L
  显示许可证。
• -h, -?, -help, --help [arg]
  显示帮助信息。可以指定一个可选参数来打印特定项的帮助。如果未指定参数，则仅显示基本（非高级）工具选项。
  arg的可能取值如下：
  • long
    除了基本工具选项之外，还打印高级工具选项。
  • full
    打印完整的选项列表，包括编码器、解码器、解复用器、复用器、滤波器等的共享和私有选项。
  • decoder=decoder_name
    打印名为decoder_name的解码器的详细信息。使用-decoders选项获取所有解码器的列表。
  • encoder=encoder_name
    打印名为encoder_name的编码器的详细信息。使用-encoders选项获取所有编码器的列表。
  • demuxer=demuxer_name
    打印名为demuxer_name的解复用器的详细信息。使用-formats选项获取所有解复用器和复用器的列表。
  • muxer=muxer_name
    打印名为muxer_name的复用器的详细信息。使用-formats选项获取所有复用器和解复用器的列表。
  • filter=filter_name
    打印名为filter_name的过滤器的详细信息。使用-filters选项获取所有过滤器的列表。
  • bsf=bitstream_filter_name
    打印名为bitstream_filter_name的比特流过滤器的详细信息。使用-bsfs选项获取所有比特流过滤器的列表。
  • protocol=protocol_name
    打印名为protocol_name的协议的详细信息。使用-protocols选项获取所有协议的列表。
• -version
  显示版本。
• -buildconf
  显示构建配置，每行一个选项。
• -formats
  显示可用格式（包括设备）。
• -demuxers
  显示可用解复用器。
• -muxers
  显示可用复用器。
• -devices
  显示可用设备。
• -codecs
  显示libavcodec已知的所有编解码器。
  注意：在本文档中，“编解码器格式”一词是更准确的媒体比特流格式的简称。
• -decoders
  显示可用解码器。
• -encoders
  显示所有可用编码器。
• -bsfs
  显示可用比特流过滤器。
• -protocols
  显示可用协议。
• -filters
  显示可用的libavfilter过滤器。
• -pix_fmts
  显示可用像素格式。
• -sample_fmts
  显示可用采样格式。
• -layouts
  显示通道名称和标准通道布局。
• -dispositions
  显示流处置。
• -colors
  显示识别的颜色名称。
• -sources device [,opt1 =val1 [,opt2 =val2]...]
  显示输入设备的自动检测源。一些设备可能提供无法自动检测的系统相关源名称。返回的列表不能假定总是完整的。

  ffmpeg -sources pulse,server = 192.168.0.4
  

• -sinks device [,opt1 =val1 [,opt2 =val2]...]
  显示输出设备的自动检测接收器。一些设备可能提供无法自动检测的系统相关接收器名称。返回的列表不能假定总是完整的。

  ffmpeg -sinks pulse,server = 192.168.0.4
  

• -loglevel [flags +]loglevel | -v [flags +]loglevel
  设置库使用的日志级别和标志。
  可选的flags可以由以下值组成：
  • ‘repeat’：表示重复的日志输出不应压缩到第一行，并且将省略“最后一条消息重复n次”行。
  • ‘level’：表示日志输出应在每条消息行添加一个[level]前缀。这可以用作日志着色的替代方法，例如当将日志转储到文件时。
    标志也可以单独使用，通过添加’+'/’-'前缀来设置/重置单个标志，而不影响其他flags或更改loglevel。当同时设置flags和loglevel时，在最后一个flags值和loglevel之间需要一个’+'分隔符。
    loglevel是一个字符串或数字，包含以下值之一：
  • ‘quiet, -8’：什么都不显示；保持沉默。
  • ‘panic, 0’：仅显示可能导致进程崩溃的致命错误，例如断言失败。目前此选项未用于任何实际用途。
  • ‘fatal, 8’：仅显示致命错误。这些错误发生后进程绝对无法继续。
  • ‘error, 16’：显示所有错误，包括可以恢复的错误。
  • ‘warning, 24’：显示所有警告和错误。任何与可能不正确或意外事件相关的消息都将显示。
  • ‘info, 32’：在处理过程中显示信息性消息。这是在警告和错误之外的额外信息。这是默认值。
  • ‘verbose, 40’：与“info”相同，但更详细。
  • ‘debug, 48’：显示所有内容，包括调试信息。
  • ‘trace, 56’

例如，要启用重复日志输出、添加level前缀并将loglevel设置为“verbose”：

ffmpeg -loglevel repeat + level + verbose -i input output

另一个示例，启用重复日志输出而不影响当前“level”前缀标志或日志级别的状态：

ffmpeg [...] -loglevel + repeat

默认情况下，程序将日志记录到标准错误输出。如果终端支持着色，则使用颜色标记错误和警告。可以通过设置环境变量AV_LOG_FORCE_NOCOLOR禁用日志着色，或者通过设置环境变量AV_LOG_FORCE_COLOR强制启用日志着色。

• -report
  将完整的命令行和日志输出转储到当前目录中名为“program - YYYYMMDD - HHMMSS.log”的文件中。此文件对于错误报告可能很有用。它还暗示“-loglevel debug”。
  将环境变量FFREPORT设置为任何值都具有相同的效果。如果该值是一个以’:‘分隔的键=值序列，这些选项将影响报告；如果选项值包含特殊字符或选项分隔符’:’，则必须对其进行转义（请参阅ffmpeg - utils手册中的“引用和转义”部分）。
  以下选项被识别：
  • file：设置用于报告的文件名；“%p”扩展为程序名称，“%t”扩展为时间戳，“%%”扩展为普通的“%”。
  • level：使用数字值设置日志详细程度级别（请参阅“-loglevel”）。
    例如，要将报告输出到名为ffreport.log的文件中，使用日志级别为32（日志级别“info”的别名）：
    FFREPORT = file = ffreport.log:level = 32 ffmpeg -i input output
    解析环境变量时的错误不是致命的，并且不会出现在报告中。
• -hide_banner
  抑制打印横幅。
  所有FFmpeg工具通常会显示版权声明、构建选项和库版本。此选项可用于抑制打印此信息。
• -cpuflags flags（全局）
  允许设置和清除CPU标志。此选项用于测试。除非你知道自己在做什么，否则请勿使用。
  例如：ffmpeg -cpuflags -sse + mmx…
  ffmpeg -cpuflags mmx…
  ffmpeg -cpuflags 0…
  此选项的可能标志如下：
  • ‘x86’
  • ‘mmx’
  • ‘mmxext’
  • ‘sse’
  • ‘sse2’
  • ‘sse2slow’
  • ‘sse3’
  • ‘sse3slow’
  • ‘ssse3’
  • ‘atom’
  • ‘sse4.1’
  • ‘sse4.2’
  • ‘avx’
  • ‘avx2’
  • ‘xop’
  • ‘fma3’
  • ‘fma4’
  • ‘3dnow’
  • ‘3dnowext’
  • ‘bmi1’
  • ‘bmi2’
  • ‘cmov’
  • ‘ARM’
  • ‘armv5te’
  • ‘armv6’
  • ‘armv6t2’
  • ‘vfp’
  • ‘vfpv3’
  • ‘neon’
  • ‘setend’
  • ‘AArch64’
  • ‘armv8’
  • ‘vfp’
  • ‘neon’
  • ‘PowerPC’
  • ‘altivec’
  • ‘Specific Processors’
  • ‘pentium2’
  • ‘pentium3’
  • ‘pentium4’
  • ‘k6’
  • ‘k62’
  • ‘athlon’
  • ‘athlonxp’
  • ‘k8’
• -cpucount count（全局）
  覆盖CPU数量的检测。此选项用于测试。除非你知道自己在做什么，否则请勿使用。
  例如：ffmpeg -cpucount 2
• -max_alloc bytes
  设置ffmpeg的malloc函数家族在堆上分配块的最大大小限制。使用此选项时要格外小心。如果你不了解这样做的全部后果，请不要使用。默认值为INT_MAX。

3.3 AV选项

这些选项由libavformat、libavdevice和libavcodec库直接提供。要查看可用的AV选项列表，请使用 - help选项。它们分为两类：

• 通用：这些选项可以为任何容器、编解码器或设备设置。通用选项列在AVFormatContext选项下用于容器/设备，列在AVCodecContext选项下用于编解码器。
• 私有：这些选项特定于给定的容器、设备或编解码器。私有选项列在其相应的容器/设备/编解码器下。
  例如，要将默认的ID3v2.4头写入MP3文件改为ID3v2.3头，使用MP3复用器的id3v2_version私有选项：

  ffmpeg -i input.flac -id3v2_version 3 out.mp3
  

  所有编解码器AV选项都是按流的，因此应附加流指定符：

  ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
  

在上面的示例中，一个多声道音频流被映射两次用于输出。第一个实例使用编解码器ac3和比特率640k进行编码。第二个实例下混到2个声道并使用编解码器aac进行编码。使用输出流的绝对索引为其指定比特率为128k。
注意：布尔型AV选项不能使用 - nooption语法，应使用 - option 0 / - option 1。
注意：以前通过在选项名称前添加v/a/s来指定按流的AV选项的未记录方式现在已过时，将很快被删除。

3.4 主要选项

• -f format
  强制使用格式。
• -unit
  显示显示值的单位。
• -prefix
  对显示值使用SI前缀。除非使用“-byte_binary_prefix”选项，否则所有前缀都是十进制的。
• -byte_binary_prefix
  强制对字节值使用二进制前缀。
• -sexagesimal
  对时间值使用六十进制格式HH:MM:SS.MICROSECONDS。
• -pretty
  美化显示值的格式，它对应于选项“-unit -prefix -byte_binary_prefix -sexagesimal”。
• -output_format、-of、-print_format writer_name[=writer_options]
  设置输出打印格式。
  writer_name指定写入器的名称，writer_options指定要使用的写入器的特定选项。例如，要以JSON格式输出并使用缩进使输出更易读，可以使用以下命令：
  ffprobe -print_format json=indent=4 input_file
  不同的写入器及其对应的选项会在后续内容中详细介绍，用于满足各种不同的输出展示需求以及与其他工具或流程配合使用等情况。

4 写入器

4.1 默认格式

默认情况下，如果没有通过-output_format等相关选项指定输出格式，ffprobe会采用一种内部的默认格式来输出信息。这种默认格式会尽可能清晰且有条理地展示多媒体流相关的关键信息，例如流的类型（视频、音频、字幕等）、基本参数（如视频的分辨率、音频的采样率等）以及部分元数据标签等内容。不过，其格式相对固定，可能在一些需要特定格式输出以方便后续处理或者展示美观性要求较高的场景下不太适用，所以才有了多种可指定的写入器格式供选择。

4.2 紧凑格式、CSV格式

紧凑格式旨在用最精简的方式来呈现信息，去除了很多不必要的描述性文字等，只保留核心的数据内容，适合于对数据量有严格要求且后续处理程序能轻易解析这种简单格式的情况。

CSV（逗号分隔值）格式则是将各项信息按照逗号进行分隔排列，每行代表一条记录，通常可以方便地导入到电子表格软件等工具中进行进一步分析和处理，比如可以方便地进行数据筛选、统计等操作，常用于需要对多媒体流的多组数据进行批量对比分析之类的场景。

4.3 扁平格式

扁平格式会将所有相关信息都放置在同一层级，不会有复杂的嵌套结构，这样使得信息的查找和整体浏览更加直观便捷，在不需要深入到多层级结构去获取信息，只是简单查看各项主要数据的场景下比较实用，例如快速查看一个多媒体文件大致的参数情况，而不需要去关心其内部更细致的分组等情况时可以选用。

4.4 INI格式

INI格式遵循一种常见的配置文件格式规范，采用类似“键=值”的形式来组织信息，有明显的节（section）划分，不同节可以存放不同类别的数据，比如可以将视频流相关信息放在一个节，音频流相关放在另一个节等。这种格式在需要将ffprobe获取的信息与一些按照INI格式读取配置的其他程序或系统进行对接整合时会比较方便，便于实现数据的共享和交互使用。

4.5 JSON格式

JSON格式是一种非常流行的用于数据交换的轻量级格式，它具有良好的可读性以及易于被众多编程语言解析的特点。在ffprobe输出中使用JSON格式，可以将多媒体流的各种复杂信息以一种层次分明、结构清晰的方式呈现出来，比如流的嵌套关系、详细的元数据等都能很好地展示，适合在需要与各种网络服务、后端系统等进行数据交互或者需要长期保存、随时能方便重新解析多媒体文件相关信息的场景下使用。

4.6 XML格式

XML格式同样是一种常用于数据表示和交换的格式，它有着严格的语法规范，通过标签来定义元素以及元素之间的层次关系，可以对多媒体流的信息进行详尽且规范的描述。在一些对数据格式的准确性、完整性以及遵循标准要求较高的企业级应用或者与其他基于XML规范进行数据交互的系统对接时，选用XML格式输出ffprobe的结果会是比较合适的选择。

5 时间码

时间码相关部分主要涉及ffprobe如何处理、显示以及解析多媒体流中的时间相关信息。在多媒体内容中，时间码对于定位特定时刻、计算时长、同步不同流之间的播放等方面起着关键作用。ffprobe能够准确识别并按照不同的要求展示时间码，例如按照常规的时分秒格式，或者更精确的包含微秒等的格式，同时也能在不同的输出写入器格式下保持时间码信息的正确呈现，以满足诸如视频编辑、流媒体播放系统等对时间相关数据精确获取和处理的需求。