ffprobe.texi 18.9 KB
Newer Older
Stefano Sabatini's avatar
Stefano Sabatini committed
1 2
\input texinfo @c -*- texinfo -*-

3
@settitle ffprobe Documentation
Stefano Sabatini's avatar
Stefano Sabatini committed
4
@titlepage
5
@center @titlefont{ffprobe Documentation}
Stefano Sabatini's avatar
Stefano Sabatini committed
6 7
@end titlepage

8 9 10 11
@top

@contents

12 13
@chapter Synopsis

14
ffprobe [@var{options}] [@file{input_file}]
15

16
@chapter Description
Stefano Sabatini's avatar
Stefano Sabatini committed
17 18
@c man begin DESCRIPTION

19
ffprobe gathers information from multimedia streams and prints it in
Stefano Sabatini's avatar
Stefano Sabatini committed
20 21 22 23 24 25 26 27 28 29
human- and machine-readable fashion.

For example it can be used to check the format of the container used
by a multimedia stream and the format and type of each media stream
contained in it.

If a filename is specified in input, ffprobe will try to open and
probe the file content. If the file cannot be opened or recognized as
a multimedia file, a positive exit code is returned.

30
ffprobe may be employed both as a standalone application or in
Stefano Sabatini's avatar
Stefano Sabatini committed
31 32 33 34 35 36 37
combination with a textual filter, which may perform more
sophisticated processing, e.g. statistical processing or plotting.

Options are used to list some of the formats supported by ffprobe or
for specifying which information to display, and for setting how
ffprobe will show it.

38
ffprobe output is designed to be easily parsable by a textual filter,
39 40
and consists of one or more sections of a form defined by the selected
writer, which is specified by the @option{print_format} option.
Stefano Sabatini's avatar
Stefano Sabatini committed
41

42 43 44 45
Sections may contain other nested sections, and are identified by a
name (which may be shared by other sections), and an unique
name. See the output of @option{sections}.

Stefano Sabatini's avatar
Stefano Sabatini committed
46
Metadata tags stored in the container or in the streams are recognized
47 48
and printed in the corresponding "FORMAT", "STREAM" or "PROGRAM_STREAM"
section.
Stefano Sabatini's avatar
Stefano Sabatini committed
49 50 51

@c man end

52
@chapter Options
Stefano Sabatini's avatar
Stefano Sabatini committed
53 54
@c man begin OPTIONS

55
@include fftools-common-opts.texi
Stefano Sabatini's avatar
Stefano Sabatini committed
56 57 58 59

@section Main options

@table @option
60 61 62 63

@item -f @var{format}
Force format to use.

Stefano Sabatini's avatar
Stefano Sabatini committed
64 65 66 67
@item -unit
Show the unit of the displayed values.

@item -prefix
68 69
Use SI prefixes for the displayed values.
Unless the "-byte_binary_prefix" option is used all the prefixes
Stefano Sabatini's avatar
Stefano Sabatini committed
70 71 72 73 74 75 76 77 78 79
are decimal.

@item -byte_binary_prefix
Force the use of binary prefixes for byte values.

@item -sexagesimal
Use sexagesimal format HH:MM:SS.MICROSECONDS for time values.

@item -pretty
Prettify the format of the displayed values, it corresponds to the
80
options "-unit -prefix -byte_binary_prefix -sexagesimal".
Stefano Sabatini's avatar
Stefano Sabatini committed
81

82
@item -of, -print_format @var{writer_name}[=@var{writer_options}]
83
Set the output printing format.
84

85 86 87
@var{writer_name} specifies the name of the writer, and
@var{writer_options} specifies the options to be passed to the writer.

88 89 90 91 92 93 94
For example for printing the output in JSON format, specify:
@example
-print_format json
@end example

For more details on the available output printing formats, see the
Writers section below.
95

96 97 98 99
@item -sections
Print sections structure and section information, and exit. The output
is not meant to be parsed by a machine.

100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
@item -select_streams @var{stream_specifier}
Select only the streams specified by @var{stream_specifier}. This
option affects only the options related to streams
(e.g. @code{show_streams}, @code{show_packets}, etc.).

For example to show only audio streams, you can use the command:
@example
ffprobe -show_streams -select_streams a INPUT
@end example

To show only video packets belonging to the video stream with index 1:
@example
ffprobe -show_packets -select_streams v:1 INPUT
@end example

115
@item -show_data
116
Show payload data, as a hexadecimal and ASCII dump. Coupled with
117 118 119 120 121
@option{-show_packets}, it will dump the packets' data. Coupled with
@option{-show_streams}, it will dump the codec extradata.

The dump is printed as the "data" field. It may contain newlines.

122 123 124 125 126
@item -show_error
Show information about the error found when trying to probe the input.

The error information is printed within a section with name "ERROR".

Stefano Sabatini's avatar
Stefano Sabatini committed
127 128 129 130 131
@item -show_format
Show information about the container format of the input multimedia
stream.

All the container format information is printed within a section with
132
name "FORMAT".
Stefano Sabatini's avatar
Stefano Sabatini committed
133

134 135 136 137 138
@item -show_format_entry @var{name}
Like @option{-show_format}, but only prints the specified entry of the
container format information, rather than all. This option may be given more
than once, then all specified entries will be shown.

139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
This option is deprecated, use @code{show_entries} instead.

@item -show_entries @var{section_entries}
Set list of entries to show.

Entries are specified according to the following
syntax. @var{section_entries} contains a list of section entries
separated by @code{:}. Each section entry is composed by a section
name (or unique name), optionally followed by a list of entries local
to that section, separated by @code{,}.

If section name is specified but is followed by no @code{=}, all
entries are printed to output, together with all the contained
sections. Otherwise only the entries specified in the local section
entries list are printed. In particular, if @code{=} is specified but
the list of local entries is empty, then no entries will be shown for
that section.

Note that the order of specification of the local section entries is
not honored in the output, and the usual display order will be
retained.

The formal syntax is given by:
@example
@var{LOCAL_SECTION_ENTRIES} ::= @var{SECTION_ENTRY_NAME}[,@var{LOCAL_SECTION_ENTRIES}]
@var{SECTION_ENTRY}         ::= @var{SECTION_NAME}[=[@var{LOCAL_SECTION_ENTRIES}]]
@var{SECTION_ENTRIES}       ::= @var{SECTION_ENTRY}[:@var{SECTION_ENTRIES}]
@end example

For example, to show only the index and type of each stream, and the PTS
time, duration time, and stream index of the packets, you can specify
the argument:
@example
packet=pts_time,duration_time,stream_index : stream=index,codec_type
@end example

To show all the entries in the section "format", but only the codec
type in the section "stream", specify the argument:
@example
format : stream=codec_type
@end example

To show all the tags in the stream and format sections:
@example
format_tags : format_tags
@end example

To show only the @code{title} tag (if available) in the stream
sections:
@example
stream_tags=title
@end example

192 193 194 195 196
@item -show_packets
Show information about each packet contained in the input multimedia
stream.

The information for each single packet is printed within a dedicated
197
section with name "PACKET".
198

199
@item -show_frames
200 201
Show information about each frame and subtitle contained in the input
multimedia stream.
202 203

The information for each single frame is printed within a dedicated
204
section with name "FRAME" or "SUBTITLE".
205

Stefano Sabatini's avatar
Stefano Sabatini committed
206 207 208 209 210
@item -show_streams
Show information about each media stream contained in the input
multimedia stream.

Each media stream information is printed within a dedicated section
211
with name "STREAM".
Stefano Sabatini's avatar
Stefano Sabatini committed
212

213 214 215 216 217 218 219
@item -show_programs
Show information about programs and their streams contained in the input
multimedia stream.

Each media stream information is printed within a dedicated section
with name "PROGRAM_STREAM".

220 221 222 223 224
@item -show_chapters
Show information about chapters stored in the format.

Each chapter is printed within a dedicated section with name "CHAPTER".

225 226 227 228 229 230 231 232
@item -count_frames
Count the number of frames per stream and report it in the
corresponding stream section.

@item -count_packets
Count the number of packets per stream and report it in the
corresponding stream section.

233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
@item -read_intervals @var{read_intervals}

Read only the specified intervals. @var{read_intervals} must be a
sequence of interval specifications separated by ",".
@command{ffprobe} will seek to the interval starting point, and will
continue reading from that.

Each interval is specified by two optional parts, separated by "%".

The first part specifies the interval start position. It is
interpreted as an abolute position, or as a relative offset from the
current position if it is preceded by the "+" character. If this first
part is not specified, no seeking will be performed when reading this
interval.

The second part specifies the interval end position. It is interpreted
as an absolute position, or as a relative offset from the current
position if it is preceded by the "+" character. If the offset
specification starts with "#", it is interpreted as the number of
packets to read (not including the flushing packets) from the interval
start. If no second part is specified, the program will read until the
end of the input.

Note that seeking is not accurate, thus the actual interval start
point may be different from the specified position. Also, when an
interval duration is specified, the absolute end time will be computed
by adding the duration to the interval start point found by seeking
the file, rather than to the specified start value.

The formal syntax is given by:
@example
@var{INTERVAL}  ::= [@var{START}|+@var{START_OFFSET}][%[@var{END}|+@var{END_OFFSET}]]
@var{INTERVALS} ::= @var{INTERVAL}[,@var{INTERVALS}]
@end example

A few examples follow.
@itemize
@item
Seek to time 10, read packets until 20 seconds after the found seek
point, then seek to position @code{01:30} (1 minute and thirty
seconds) and read packets until position @code{01:45}.
@example
10%+20,01:30%01:45
@end example

@item
Read only 42 packets after seeking to position @code{01:23}:
@example
01:23%+#42
@end example

@item
Read only the first 20 seconds from the start:
@example
%+20
@end example

@item
Read from the start until position @code{02:30}:
@example
%02:30
@end example
@end itemize

297 298 299 300 301 302
@item -show_private_data, -private
Show private data, that is data depending on the format of the
particular shown element.
This option is enabled by default, but you may need to disable it
for specific uses, for example when creating XSD-compliant XML output.

303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
@item -show_program_version
Show information related to program version.

Version information is printed within a section with name
"PROGRAM_VERSION".

@item -show_library_versions
Show information related to library versions.

Version information for each library is printed within a section with
name "LIBRARY_VERSION".

@item -show_versions
Show information related to program and library versions. This is the
equivalent of setting both @option{-show_program_version} and
@option{-show_library_versions} options.

320 321 322 323
@item -bitexact
Force bitexact output, useful to produce output which is not dependent
on the specific build.

324 325 326
@item -i @var{input_file}
Read @var{input_file}.

Stefano Sabatini's avatar
Stefano Sabatini committed
327 328 329
@end table
@c man end

330 331 332
@chapter Writers
@c man begin WRITERS

333
A writer defines the output format adopted by @command{ffprobe}, and will be
334 335
used for printing all the parts of the output.

336 337 338
A writer may accept one or more arguments, which specify the options
to adopt. The options are specified as a list of @var{key}=@var{value}
pairs, separated by ":".
339

340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372
All writers support the following options:

@table @option
@item string_validation, sv
Set string validation mode.

The following values are accepted.
@table @samp
@item 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.

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

@item replace
The writer will substitute invalid UTF-8 sequences or code points with
the string specified with the @option{string_validation_replacement}.
@end table

Default value is @samp{replace}.

@item string_validation_replacement, svr
Set replacement string to use in case @option{string_validation} is
set to @samp{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.
@end table

373 374 375 376 377 378 379 380 381 382 383 384 385 386
A description of the currently available writers follows.

@section default
Default format.

Print each section in the form:
@example
[SECTION]
key1=val1
...
keyN=valN
[/SECTION]
@end example

387 388
Metadata tags are printed as a line in the corresponding FORMAT, STREAM or
PROGRAM_STREAM section, and are prefixed by the string "TAG:".
389

390 391 392 393
A description of the accepted options follows.

@table @option

394 395 396 397
@item nokey, nk
If set to 1 specify not to print the key of each field. Default value
is 0.

398 399 400 401 402
@item noprint_wrappers, nw
If set to 1 specify not to print the section header and footer.
Default value is 0.
@end table

403 404 405 406 407
@section compact, csv
Compact and CSV format.

The @code{csv} writer is equivalent to @code{compact}, but supports
different defaults.
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424

Each section is printed on a single line.
If no option is specifid, the output has the form:
@example
section|key1=val1| ... |keyN=valN
@end example

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.

@table @option

@item item_sep, s
Specify the character to use for separating fields in the output line.
425 426
It must be a single printable character, it is "|" by default ("," for
the @code{csv} writer).
427 428 429

@item nokey, nk
If set to 1 specify not to print the key of each field. Its default
430
value is 0 (1 for the @code{csv} writer).
431 432

@item escape, e
433 434
Set the escape mode to use, default to "c" ("csv" for the @code{csv}
writer).
435 436 437 438

It can assume one of the following values:
@table @option
@item c
439 440 441
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 @var{SEP} are escaped using C-like fashioned
442 443 444 445 446 447 448 449 450 451 452 453 454
escaping, so that a newline is converted to the sequence "\n", a
carriage return to "\r", '\' to "\\" and the separator @var{SEP} is
converted to "\@var{SEP}".

@item csv
Perform CSV-like escaping, as described in RFC4180.  Strings
containing a newline ('\n'), a carriage return ('\r'), a double quote
('"'), or @var{SEP} are enclosed in double-quotes.

@item none
Perform no escaping.
@end table

455 456 457 458 459
@item print_section, p
Print the section name at the begin of each line if the value is
@code{1}, disable it with value set to @code{0}. Default value is
@code{1}.

460 461
@end table

462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487
@section flat
Flat format.

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 @var{sep_char} option).

The description of the accepted options follows.

@table @option
@item 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 '.'.

@item hierarchical, h
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.
@end table

488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526
@section ini
INI format output.

Print output in an INI based format.

The following conventions are adopted:

@itemize
@item
all key and values are UTF-8
@item
'.' is the subgroup separator
@item
newline, '\t', '\f', '\b' and the following characters are escaped
@item
'\' is the escape character
@item
'#' is the comment indicator
@item
'=' is the key/value separator
@item
':' is not used but usually parsed as key/value separator
@end itemize

This writer accepts options as a list of @var{key}=@var{value} pairs,
separated by ":".

The description of the accepted options follows.

@table @option
@item hierarchical, h
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.
@end table

527 528 529 530 531
@section json
JSON based format.

Each section is printed using JSON notation.

532 533 534 535 536 537 538 539 540
The description of the accepted options follows.

@table @option

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

541 542
For more information about JSON, see @url{http://www.json.org/}.

543 544 545 546 547 548
@section xml
XML based format.

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

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

553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575
Note that the output issued will be compliant to the
@file{ffprobe.xsd} schema only when no special global output options
(@option{unit}, @option{prefix}, @option{byte_binary_prefix},
@option{sexagesimal} etc.) are specified.

The description of the accepted options follows.

@table @option

@item fully_qualified, q
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.

@item xsd_compliant, x
If set to 1 perform more checks for ensuring that the output is XSD
compliant. Default value is 0.
This option automatically sets @option{fully_qualified} to 1.
@end table

For more information about the XML format, see
@url{http://www.w3.org/XML/}.
576
@c man end WRITERS
577

578
@chapter Timecode
579
@c man begin TIMECODE
580 581 582 583 584

@command{ffprobe} supports Timecode extraction:

@itemize

585 586
@item
MPEG1/2 timecode is extracted from the GOP, and is available in the video
587 588
stream details (@option{-show_streams}, see @var{timecode}).

589 590
@item
MOV timecode is extracted from tmcd track, so is available in the tmcd
591
stream metadata (@option{-show_streams}, see @var{TAG:timecode}).
592

593
@item
594
DV, GXF and AVI timecodes are available in format metadata
595 596 597
(@option{-show_format}, see @var{TAG:timecode}).

@end itemize
598
@c man end TIMECODE
599

600
@include config.texi
601
@ifset config-all
602
@set config-readonly
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625
@ifset config-avutil
@include utils.texi
@end ifset
@ifset config-avcodec
@include codecs.texi
@include bitstream_filters.texi
@end ifset
@ifset config-avformat
@include formats.texi
@include protocols.texi
@end ifset
@ifset config-avdevice
@include devices.texi
@end ifset
@ifset config-swresample
@include resampler.texi
@end ifset
@ifset config-swscale
@include scaler.texi
@end ifset
@ifset config-avfilter
@include filters.texi
@end ifset
626 627
@end ifset

628 629 630
@chapter See Also

@ifhtml
631 632 633 634 635 636
@ifset config-all
@url{ffprobe.html,ffprobe},
@end ifset
@ifset config-not-all
@url{ffprobe-all.html,ffprobe-all},
@end ifset
637
@url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffserver.html,ffserver},
638 639 640 641
@url{ffmpeg-utils.html,ffmpeg-utils},
@url{ffmpeg-scaler.html,ffmpeg-scaler},
@url{ffmpeg-resampler.html,ffmpeg-resampler},
@url{ffmpeg-codecs.html,ffmpeg-codecs},
642
@url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters},
643 644 645 646 647 648 649
@url{ffmpeg-formats.html,ffmpeg-formats},
@url{ffmpeg-devices.html,ffmpeg-devices},
@url{ffmpeg-protocols.html,ffmpeg-protocols},
@url{ffmpeg-filters.html,ffmpeg-filters}
@end ifhtml

@ifnothtml
650 651 652 653 654 655
@ifset config-all
ffprobe(1),
@end ifset
@ifset config-not-all
ffprobe-all(1),
@end ifset
656 657 658 659 660 661
ffmpeg(1), ffplay(1), ffserver(1),
ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),
ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1)
@end ifnothtml

662 663
@include authors.texi

Stefano Sabatini's avatar
Stefano Sabatini committed
664 665 666
@ignore

@setfilename ffprobe
667
@settitle ffprobe media prober
Stefano Sabatini's avatar
Stefano Sabatini committed
668 669 670 671

@end ignore

@bye