ffprobe文档 4-5

4 Writers 输出器

输出器定义了ffprobe所有输出的格式。

A writer defines the output format adopted by ffprobe, and will be used for printing all the parts of the output.

输出器可以接受一个或者多个参数，以启用某些选项。选项以一系列 键值对(“key=value”) 的形式描述，并用':'分割多个选项。

A writer may accept one or more arguments, which specify the options to adopt. The options are specified as a list of key=value pairs, separated by “:”.

下面是所有的输出器都支持的选项：

All writers support the following options:

• string_validation, sv

  字符串验证模式。

  Set string validation mode.

  该选项有如下值可选。

  The following values are accepted.

  • ‘fail’

    当在输入中发现任何错误（如非法字符串等）立即弹出。这种模式在验证输入元数据是非常有用。

    The writer will fail immediately in case an invalid string (UTF-8) sequence or code point is found in the input. This is especially useful to validate input metadata.

  • ‘ignore’

    忽视任何错误。但可能会使得输出的结果不可用，尤其是json与xml输出器时。

    Any validation error will be ignored. This will result in possibly broken output, especially with the json or xml writer.

  • ‘replace’

    输出器会使用string_validation_replacement替换所有非法字符串或其他错误。这也是 默认 的字符串验证模式。

    The writer will substitute invalid UTF-8 sequences or code points with the string specified with the string_validation_replacement.Default value is ‘replace’.

• string_validation_replacement, svr

  设置用于replace模式下替换错误值的字符串。若没有指定任何字符串，则输出器会从输入中删除所有非法的字符序列。

  Set replacement string to use in case string_validation is set to ‘replace’.In case the option is not specified, the writer will assume the empty string, that is it will remove the invalid sequences from the input strings.

目前可用的输出器如下：

A description of the currently available writers follows.

4.1 default

默认格式。

Default format.

每个分段以如下形式打印。

Print each section in the form:

[SECTION]
key1=val1
...
keyN=valN
[/SECTION]

FORMAT, STREAM, PROGRAM_STREAM所对应的 元数据标签(Metadata tag) 会在各自 分段(section) 下以TAG为前缀打印。

Metadata tags are printed as a line in the corresponding FORMAT, STREAM or PROGRAM_STREAM section, and are prefixed by the string “TAG:”.

一些可用的选项如下：

A description of the accepted options follows.

• nokey, nk

  该选项设为1则不打印key部分 （即只有val部分）。该选项默认为0。

  If set to 1 specify not to print the key of each field. Default value is 0.

• noprint_wrappers, nw

  该选项设为1则不打印段落的首部和尾部 （即[SECTION]与[/SECTION]部分）。该选项默认为0.

  If set to 1 specify not to print the section header and footer. Default value is 0.

4.2 compact, csv

CSV格式。

Compact and CSV format.

csv输出器与compact是等价的，但两者默认设置不同。

The csv writer is equivalent to compact, but supports different defaults.

每个分段在一行打印。如果没有设置任何选项，其输出形式如下：

Each section is printed on a single line. If no option is specified, the output has the form:

section|key1=val1| ... |keyN=valN

format, stream, 所对应的 元数据标签(Metadata tag) 会在各自 分段(section) 下以tag:为前缀打印。

Metadata tags are printed in the corresponding “format” or “stream” section. A metadata tag key, if printed, is prefixed by the string “tag:”.

一些可用的选项如下：

The description of the accepted options follows.

• item_sep, s

  指定用于分割输出 字段(field) 的字符。其只能为单个可见字符 （换行等格式控制字符为不可见字符），默认是'|'（csv默认为’,’`）。

  Specify the character to use for separating fields in the output line. It must be a single printable character, it is “|” by default ("," for the csv writer).

• nokey, nk

  该选项设为1则不打印key部分。该选项默认为0（csv默认为1）。

  If set to 1 specify not to print the key of each field. Its default value is 0 (1 for the csv writer).

• escape, e

  该选项设置转义字符模式。该选项默认为模式c（csv默认为csv模式）。

  Set the escape mode to use, default to “c” (“csv” for the csv writer).

  它有如下值可以设置：

  It can assume one of the following values:

  • c

    使用类C语言的转义字符。如换行'\n'，回车'\r'，tab缩进'\t'，换页’\f'，自定义的分隔符也会使用'\'转义。

    Perform C-like escaping. Strings containing a newline (‘\n’), carriage return (‘\r’), a tab (‘\t’), a form feed (‘\f’), the escaping character (‘\’) or the item separator character SEP are escaped using C-like fashioned escaping, so that a newline is converted to the sequence ‘\n’, a carriage return to ‘\r’, ‘\’ to ‘\’ and the separator SEP is converted to ‘\SEP’.

  • csv

    使用类CSV的转义字符，遵循RFC4180规范。换行符'\n'，回车'\r'，双引号""，自定义的分隔符会被双引号包裹。

    Perform CSV-like escaping, as described in RFC4180. Strings containing a newline (‘\n’), a carriage return (‘\r’), a double quote (‘"’), or SEP are enclosed in double-quotes.

  • none

    不使用任何转义字符。

    Perform no escaping.

• print_section, p

  该选项设为1则在每行的开始前打印该分段名。默认值为1。

  Print the section name at the beginning of each line if the value is 1, disable it with value set to 0. Default value is 1.

4.3 flat

单层模式。

Flat format.

这种模式不保留层级结构，每一行由一个精确特定的键值对描述（如"streams.stream.3.tags.foo=bar"）。该输出遵循shell的转义方式，只要分隔字符是字母或数字或下划线就非常适合直接嵌入sh脚本中使用。

A free-form output where each line contains an explicit key=value, such as “streams.stream.3.tags.foo=bar”. The output is shell escaped, so it can be directly embedded in sh scripts as long as the separator character is an alphanumeric character or an underscore (see sep_char option).

它有如下选项可以设置：

The description of the accepted options follows.

• sep_char, s

  设置用于分隔分段或标签的符号。其默认值为'.'。

  Separator character used to separate the chapter, the section name, IDs and potential tags in the printed field key.Default value is ‘.’.

• hierarchical, h

  该选项设为1时会使分段描述遵循其层级结构*（即如上述的示例的键值对）*，其层级结构会以前缀的方式打印。其默认值为1。

  Specify if the section name specification should be hierarchical. If set to 1, and if there is more than one section in the current chapter, the section name will be prefixed by the name of the chapter. A value of 0 will disable this behavior.Default value is 1.

4.4 ini

INI格式

INI format output.

使用INI的基本格式，并采用下列特性：

Print output in an INI based format.

The following conventions are adopted:

• 所有的键值都以UTF-8描述

  all key and values are UTF-8

• '.'用于子分组分隔符

  ‘.’ is the subgroup separator

• 换行符，'\t', '\f', '\b'与如下字符已转义。

  newline, ‘\t’, ‘\f’, ‘\b’ and the following characters are escaped

  • '\'用于转义其他字符

    ‘\’ is the escape character

  • '#'表示注释

    ‘#’ is the comment indicator

  • '='用于分隔键/值

    ‘=’ is the key/value separator

  • ':'不使用，但也常见于分隔键/值用

    ‘:’ is not used but usually parsed as key/value separator

该输出器只接受以key=value方式描述的选项，选项之间以':'分隔。

This writer accepts options as a list of key=value pairs, separated by ‘:’.

它有如下选项可以设置：

The description of the accepted options follows.

• hierarchical, h

  选项设置为1时，如多个分段是均位于同 章节**(chapter)** 下，则这些分段都会以章节名作为前缀。设为0时则会关闭该项功能。默认为1。

  Specify if the section name specification should be hierarchical. If set to 1, and if there is more than one section in the current chapter, the section name will be prefixed by the name of the chapter. A value of 0 will disable this behavior.Default value is 1.

4.5 json

JSON 格式，分段均以JSON格式打印。

JSON based format.

Each section is printed using JSON notation.

它有如下选项可以设置：

The description of the accepted options follows.

• compact, c

  设为1时使用压缩输出模式，即每个分段均在一行输出。其默认值为0。

  If set to 1 enable compact output, that is each section will be printed on a single line. Default value is 0.

For more information about JSON, see http://www.json.org/.

4.6 xml

XML格式，该输出是通过一个XML描述文件ffprobe.xsd描述的，该文件位于FFmpeg的datadir目录下。

XML based format.

The XML output is described in the XML schema description file ffprobe.xsd installed in the FFmpeg datadir.

你可以从这个链接里获取最新版本的描述文件。

An updated version of the schema can be retrieved at the url http://www.ffmpeg.org/schema/ffprobe.xsd, which redirects to the latest schema committed into the FFmpeg development source code tree.

但是描述文件仅在没有打开特殊全局输出选项时起效，如（unit, prefix, byte_binary_prefix, sexagesimal等）。

Note that the output issued will be compliant to the ffprobe.xsd schema only when no special global output options (unit, prefix, byte_binary_prefix, sexagesimal etc.) are specified.

它有如下选项可以设置：

The description of the accepted options follows.

• fully_qualified, q

  该选项设置为1时会确保输出会严格符合要求，需要在输出XML文件时打开，它可以保证产生的文件通过XSD文件的验证。默认值为0。

  If set to 1 specify if the output should be fully qualified. Default value is 0. This is required for generating an XML file which can be validated through an XSD file.

• xsd_strict, x

  该选项设置为1时保证输出符合XSD文件的描述。默认值为0，该选项会同时将fully_qualified设置为1。

  If set to 1 perform more checks for ensuring that the output is XSD compliant. Default value is 0. This option automatically sets fully_qualified to 1.

更多关于XML格式的信息参照 https://www.w3.org/XML。

For more information about the XML format, see https://www.w3.org/XML/.

5 Timecode

ffmpeg支持提取 时间码(Timecode)。

ffprobe supports Timecode extraction:

• MPEG1/2的时间码会从GOP中提取，它也会出现在stream分段中。

  MPEG1/2 timecode is extracted from the GOP, and is available in the video stream details (-show_streams, see timecode).

• MOV的时间码通过tmcd轨道提取，因此它也出现在tmcd流的元数据中。

  MOV timecode is extracted from tmcd track, so is available in the tmcd stream metadata (-show_streams, see TAG:timecode).

• DV, GXF, AVI的时间码则可在format分段的元数据中提取。

EG1/2 timecode is extracted from the GOP, and is available in the video stream details (-show_streams, see timecode).

• MOV的时间码通过tmcd轨道提取，因此它也出现在tmcd流的元数据中。

  MOV timecode is extracted from tmcd track, so is available in the tmcd stream metadata (-show_streams, see TAG:timecode).

• DV, GXF, AVI的时间码则可在format分段的元数据中提取。

  DV, GXF and AVI timecodes are available in format metadata (-show_format, see TAG:timecode).