1\input texinfo @c -*- texinfo -*- 2 3@settitle ffprobe Documentation 4@titlepage 5@center @titlefont{ffprobe Documentation} 6@end titlepage 7 8@top 9 10@contents 11 12@chapter Synopsis 13 14ffprobe [@var{options}] [@file{input_file}] 15 16@chapter Description 17@c man begin DESCRIPTION 18 19ffprobe gathers information from multimedia streams and prints it in 20human- and machine-readable fashion. 21 22For example it can be used to check the format of the container used 23by a multimedia stream and the format and type of each media stream 24contained in it. 25 26If a filename is specified in input, ffprobe will try to open and 27probe the file content. If the file cannot be opened or recognized as 28a multimedia file, a positive exit code is returned. 29 30ffprobe may be employed both as a standalone application or in 31combination with a textual filter, which may perform more 32sophisticated processing, e.g. statistical processing or plotting. 33 34Options are used to list some of the formats supported by ffprobe or 35for specifying which information to display, and for setting how 36ffprobe will show it. 37 38ffprobe output is designed to be easily parsable by a textual filter, 39and consists of one or more sections of a form defined by the selected 40writer, which is specified by the @option{print_format} option. 41 42Sections may contain other nested sections, and are identified by a 43name (which may be shared by other sections), and an unique 44name. See the output of @option{sections}. 45 46Metadata tags stored in the container or in the streams are recognized 47and printed in the corresponding "FORMAT", "STREAM" or "PROGRAM_STREAM" 48section. 49 50@c man end 51 52@chapter Options 53@c man begin OPTIONS 54 55@include fftools-common-opts.texi 56 57@section Main options 58 59@table @option 60 61@item -f @var{format} 62Force format to use. 63 64@item -unit 65Show the unit of the displayed values. 66 67@item -prefix 68Use SI prefixes for the displayed values. 69Unless the "-byte_binary_prefix" option is used all the prefixes 70are decimal. 71 72@item -byte_binary_prefix 73Force the use of binary prefixes for byte values. 74 75@item -sexagesimal 76Use sexagesimal format HH:MM:SS.MICROSECONDS for time values. 77 78@item -pretty 79Prettify the format of the displayed values, it corresponds to the 80options "-unit -prefix -byte_binary_prefix -sexagesimal". 81 82@item -of, -print_format @var{writer_name}[=@var{writer_options}] 83Set the output printing format. 84 85@var{writer_name} specifies the name of the writer, and 86@var{writer_options} specifies the options to be passed to the writer. 87 88For example for printing the output in JSON format, specify: 89@example 90-print_format json 91@end example 92 93For more details on the available output printing formats, see the 94Writers section below. 95 96@item -sections 97Print sections structure and section information, and exit. The output 98is not meant to be parsed by a machine. 99 100@item -select_streams @var{stream_specifier} 101Select only the streams specified by @var{stream_specifier}. This 102option affects only the options related to streams 103(e.g. @code{show_streams}, @code{show_packets}, etc.). 104 105For example to show only audio streams, you can use the command: 106@example 107ffprobe -show_streams -select_streams a INPUT 108@end example 109 110To show only video packets belonging to the video stream with index 1: 111@example 112ffprobe -show_packets -select_streams v:1 INPUT 113@end example 114 115@item -show_data 116Show payload data, as a hexadecimal and ASCII dump. Coupled with 117@option{-show_packets}, it will dump the packets' data. Coupled with 118@option{-show_streams}, it will dump the codec extradata. 119 120The dump is printed as the "data" field. It may contain newlines. 121 122@item -show_error 123Show information about the error found when trying to probe the input. 124 125The error information is printed within a section with name "ERROR". 126 127@item -show_format 128Show information about the container format of the input multimedia 129stream. 130 131All the container format information is printed within a section with 132name "FORMAT". 133 134@item -show_format_entry @var{name} 135Like @option{-show_format}, but only prints the specified entry of the 136container format information, rather than all. This option may be given more 137than once, then all specified entries will be shown. 138 139This option is deprecated, use @code{show_entries} instead. 140 141@item -show_entries @var{section_entries} 142Set list of entries to show. 143 144Entries are specified according to the following 145syntax. @var{section_entries} contains a list of section entries 146separated by @code{:}. Each section entry is composed by a section 147name (or unique name), optionally followed by a list of entries local 148to that section, separated by @code{,}. 149 150If section name is specified but is followed by no @code{=}, all 151entries are printed to output, together with all the contained 152sections. Otherwise only the entries specified in the local section 153entries list are printed. In particular, if @code{=} is specified but 154the list of local entries is empty, then no entries will be shown for 155that section. 156 157Note that the order of specification of the local section entries is 158not honored in the output, and the usual display order will be 159retained. 160 161The formal syntax is given by: 162@example 163@var{LOCAL_SECTION_ENTRIES} ::= @var{SECTION_ENTRY_NAME}[,@var{LOCAL_SECTION_ENTRIES}] 164@var{SECTION_ENTRY} ::= @var{SECTION_NAME}[=[@var{LOCAL_SECTION_ENTRIES}]] 165@var{SECTION_ENTRIES} ::= @var{SECTION_ENTRY}[:@var{SECTION_ENTRIES}] 166@end example 167 168For example, to show only the index and type of each stream, and the PTS 169time, duration time, and stream index of the packets, you can specify 170the argument: 171@example 172packet=pts_time,duration_time,stream_index : stream=index,codec_type 173@end example 174 175To show all the entries in the section "format", but only the codec 176type in the section "stream", specify the argument: 177@example 178format : stream=codec_type 179@end example 180 181To show all the tags in the stream and format sections: 182@example 183format_tags : format_tags 184@end example 185 186To show only the @code{title} tag (if available) in the stream 187sections: 188@example 189stream_tags=title 190@end example 191 192@item -show_packets 193Show information about each packet contained in the input multimedia 194stream. 195 196The information for each single packet is printed within a dedicated 197section with name "PACKET". 198 199@item -show_frames 200Show information about each frame and subtitle contained in the input 201multimedia stream. 202 203The information for each single frame is printed within a dedicated 204section with name "FRAME" or "SUBTITLE". 205 206@item -show_streams 207Show information about each media stream contained in the input 208multimedia stream. 209 210Each media stream information is printed within a dedicated section 211with name "STREAM". 212 213@item -show_programs 214Show information about programs and their streams contained in the input 215multimedia stream. 216 217Each media stream information is printed within a dedicated section 218with name "PROGRAM_STREAM". 219 220@item -show_chapters 221Show information about chapters stored in the format. 222 223Each chapter is printed within a dedicated section with name "CHAPTER". 224 225@item -count_frames 226Count the number of frames per stream and report it in the 227corresponding stream section. 228 229@item -count_packets 230Count the number of packets per stream and report it in the 231corresponding stream section. 232 233@item -read_intervals @var{read_intervals} 234 235Read only the specified intervals. @var{read_intervals} must be a 236sequence of interval specifications separated by ",". 237@command{ffprobe} will seek to the interval starting point, and will 238continue reading from that. 239 240Each interval is specified by two optional parts, separated by "%". 241 242The first part specifies the interval start position. It is 243interpreted as an abolute position, or as a relative offset from the 244current position if it is preceded by the "+" character. If this first 245part is not specified, no seeking will be performed when reading this 246interval. 247 248The second part specifies the interval end position. It is interpreted 249as an absolute position, or as a relative offset from the current 250position if it is preceded by the "+" character. If the offset 251specification starts with "#", it is interpreted as the number of 252packets to read (not including the flushing packets) from the interval 253start. If no second part is specified, the program will read until the 254end of the input. 255 256Note that seeking is not accurate, thus the actual interval start 257point may be different from the specified position. Also, when an 258interval duration is specified, the absolute end time will be computed 259by adding the duration to the interval start point found by seeking 260the file, rather than to the specified start value. 261 262The formal syntax is given by: 263@example 264@var{INTERVAL} ::= [@var{START}|+@var{START_OFFSET}][%[@var{END}|+@var{END_OFFSET}]] 265@var{INTERVALS} ::= @var{INTERVAL}[,@var{INTERVALS}] 266@end example 267 268A few examples follow. 269@itemize 270@item 271Seek to time 10, read packets until 20 seconds after the found seek 272point, then seek to position @code{01:30} (1 minute and thirty 273seconds) and read packets until position @code{01:45}. 274@example 27510%+20,01:30%01:45 276@end example 277 278@item 279Read only 42 packets after seeking to position @code{01:23}: 280@example 28101:23%+#42 282@end example 283 284@item 285Read only the first 20 seconds from the start: 286@example 287%+20 288@end example 289 290@item 291Read from the start until position @code{02:30}: 292@example 293%02:30 294@end example 295@end itemize 296 297@item -show_private_data, -private 298Show private data, that is data depending on the format of the 299particular shown element. 300This option is enabled by default, but you may need to disable it 301for specific uses, for example when creating XSD-compliant XML output. 302 303@item -show_program_version 304Show information related to program version. 305 306Version information is printed within a section with name 307"PROGRAM_VERSION". 308 309@item -show_library_versions 310Show information related to library versions. 311 312Version information for each library is printed within a section with 313name "LIBRARY_VERSION". 314 315@item -show_versions 316Show information related to program and library versions. This is the 317equivalent of setting both @option{-show_program_version} and 318@option{-show_library_versions} options. 319 320@item -bitexact 321Force bitexact output, useful to produce output which is not dependent 322on the specific build. 323 324@item -i @var{input_file} 325Read @var{input_file}. 326 327@end table 328@c man end 329 330@chapter Writers 331@c man begin WRITERS 332 333A writer defines the output format adopted by @command{ffprobe}, and will be 334used for printing all the parts of the output. 335 336A writer may accept one or more arguments, which specify the options 337to adopt. The options are specified as a list of @var{key}=@var{value} 338pairs, separated by ":". 339 340All writers support the following options: 341 342@table @option 343@item string_validation, sv 344Set string validation mode. 345 346The following values are accepted. 347@table @samp 348@item fail 349The writer will fail immediately in case an invalid string (UTF-8) 350sequence or code point is found in the input. This is especially 351useful to validate input metadata. 352 353@item ignore 354Any validation error will be ignored. This will result in possibly 355broken output, especially with the json or xml writer. 356 357@item replace 358The writer will substitute invalid UTF-8 sequences or code points with 359the string specified with the @option{string_validation_replacement}. 360@end table 361 362Default value is @samp{replace}. 363 364@item string_validation_replacement, svr 365Set replacement string to use in case @option{string_validation} is 366set to @samp{replace}. 367 368In case the option is not specified, the writer will assume the empty 369string, that is it will remove the invalid sequences from the input 370strings. 371@end table 372 373A description of the currently available writers follows. 374 375@section default 376Default format. 377 378Print each section in the form: 379@example 380[SECTION] 381key1=val1 382... 383keyN=valN 384[/SECTION] 385@end example 386 387Metadata tags are printed as a line in the corresponding FORMAT, STREAM or 388PROGRAM_STREAM section, and are prefixed by the string "TAG:". 389 390A description of the accepted options follows. 391 392@table @option 393 394@item nokey, nk 395If set to 1 specify not to print the key of each field. Default value 396is 0. 397 398@item noprint_wrappers, nw 399If set to 1 specify not to print the section header and footer. 400Default value is 0. 401@end table 402 403@section compact, csv 404Compact and CSV format. 405 406The @code{csv} writer is equivalent to @code{compact}, but supports 407different defaults. 408 409Each section is printed on a single line. 410If no option is specifid, the output has the form: 411@example 412section|key1=val1| ... |keyN=valN 413@end example 414 415Metadata tags are printed in the corresponding "format" or "stream" 416section. A metadata tag key, if printed, is prefixed by the string 417"tag:". 418 419The description of the accepted options follows. 420 421@table @option 422 423@item item_sep, s 424Specify the character to use for separating fields in the output line. 425It must be a single printable character, it is "|" by default ("," for 426the @code{csv} writer). 427 428@item nokey, nk 429If set to 1 specify not to print the key of each field. Its default 430value is 0 (1 for the @code{csv} writer). 431 432@item escape, e 433Set the escape mode to use, default to "c" ("csv" for the @code{csv} 434writer). 435 436It can assume one of the following values: 437@table @option 438@item c 439Perform C-like escaping. Strings containing a newline ('\n'), carriage 440return ('\r'), a tab ('\t'), a form feed ('\f'), the escaping 441character ('\') or the item separator character @var{SEP} are escaped using C-like fashioned 442escaping, so that a newline is converted to the sequence "\n", a 443carriage return to "\r", '\' to "\\" and the separator @var{SEP} is 444converted to "\@var{SEP}". 445 446@item csv 447Perform CSV-like escaping, as described in RFC4180. Strings 448containing a newline ('\n'), a carriage return ('\r'), a double quote 449('"'), or @var{SEP} are enclosed in double-quotes. 450 451@item none 452Perform no escaping. 453@end table 454 455@item print_section, p 456Print the section name at the begin of each line if the value is 457@code{1}, disable it with value set to @code{0}. Default value is 458@code{1}. 459 460@end table 461 462@section flat 463Flat format. 464 465A free-form output where each line contains an explicit key=value, such as 466"streams.stream.3.tags.foo=bar". The output is shell escaped, so it can be 467directly embedded in sh scripts as long as the separator character is an 468alphanumeric character or an underscore (see @var{sep_char} option). 469 470The description of the accepted options follows. 471 472@table @option 473@item sep_char, s 474Separator character used to separate the chapter, the section name, IDs and 475potential tags in the printed field key. 476 477Default value is '.'. 478 479@item hierarchical, h 480Specify if the section name specification should be hierarchical. If 481set to 1, and if there is more than one section in the current 482chapter, the section name will be prefixed by the name of the 483chapter. A value of 0 will disable this behavior. 484 485Default value is 1. 486@end table 487 488@section ini 489INI format output. 490 491Print output in an INI based format. 492 493The following conventions are adopted: 494 495@itemize 496@item 497all key and values are UTF-8 498@item 499'.' is the subgroup separator 500@item 501newline, '\t', '\f', '\b' and the following characters are escaped 502@item 503'\' is the escape character 504@item 505'#' is the comment indicator 506@item 507'=' is the key/value separator 508@item 509':' is not used but usually parsed as key/value separator 510@end itemize 511 512This writer accepts options as a list of @var{key}=@var{value} pairs, 513separated by ":". 514 515The description of the accepted options follows. 516 517@table @option 518@item hierarchical, h 519Specify if the section name specification should be hierarchical. If 520set to 1, and if there is more than one section in the current 521chapter, the section name will be prefixed by the name of the 522chapter. A value of 0 will disable this behavior. 523 524Default value is 1. 525@end table 526 527@section json 528JSON based format. 529 530Each section is printed using JSON notation. 531 532The description of the accepted options follows. 533 534@table @option 535 536@item compact, c 537If set to 1 enable compact output, that is each section will be 538printed on a single line. Default value is 0. 539@end table 540 541For more information about JSON, see @url{http://www.json.org/}. 542 543@section xml 544XML based format. 545 546The XML output is described in the XML schema description file 547@file{ffprobe.xsd} installed in the FFmpeg datadir. 548 549An updated version of the schema can be retrieved at the url 550@url{http://www.ffmpeg.org/schema/ffprobe.xsd}, which redirects to the 551latest schema committed into the FFmpeg development source code tree. 552 553Note that the output issued will be compliant to the 554@file{ffprobe.xsd} schema only when no special global output options 555(@option{unit}, @option{prefix}, @option{byte_binary_prefix}, 556@option{sexagesimal} etc.) are specified. 557 558The description of the accepted options follows. 559 560@table @option 561 562@item fully_qualified, q 563If set to 1 specify if the output should be fully qualified. Default 564value is 0. 565This is required for generating an XML file which can be validated 566through an XSD file. 567 568@item xsd_compliant, x 569If set to 1 perform more checks for ensuring that the output is XSD 570compliant. Default value is 0. 571This option automatically sets @option{fully_qualified} to 1. 572@end table 573 574For more information about the XML format, see 575@url{http://www.w3.org/XML/}. 576@c man end WRITERS 577 578@chapter Timecode 579@c man begin TIMECODE 580 581@command{ffprobe} supports Timecode extraction: 582 583@itemize 584 585@item 586MPEG1/2 timecode is extracted from the GOP, and is available in the video 587stream details (@option{-show_streams}, see @var{timecode}). 588 589@item 590MOV timecode is extracted from tmcd track, so is available in the tmcd 591stream metadata (@option{-show_streams}, see @var{TAG:timecode}). 592 593@item 594DV, GXF and AVI timecodes are available in format metadata 595(@option{-show_format}, see @var{TAG:timecode}). 596 597@end itemize 598@c man end TIMECODE 599 600@include config.texi 601@ifset config-all 602@set config-readonly 603@ifset config-avutil 604@include utils.texi 605@end ifset 606@ifset config-avcodec 607@include codecs.texi 608@include bitstream_filters.texi 609@end ifset 610@ifset config-avformat 611@include formats.texi 612@include protocols.texi 613@end ifset 614@ifset config-avdevice 615@include devices.texi 616@end ifset 617@ifset config-swresample 618@include resampler.texi 619@end ifset 620@ifset config-swscale 621@include scaler.texi 622@end ifset 623@ifset config-avfilter 624@include filters.texi 625@end ifset 626@end ifset 627 628@chapter See Also 629 630@ifhtml 631@ifset config-all 632@url{ffprobe.html,ffprobe}, 633@end ifset 634@ifset config-not-all 635@url{ffprobe-all.html,ffprobe-all}, 636@end ifset 637@url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffserver.html,ffserver}, 638@url{ffmpeg-utils.html,ffmpeg-utils}, 639@url{ffmpeg-scaler.html,ffmpeg-scaler}, 640@url{ffmpeg-resampler.html,ffmpeg-resampler}, 641@url{ffmpeg-codecs.html,ffmpeg-codecs}, 642@url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters}, 643@url{ffmpeg-formats.html,ffmpeg-formats}, 644@url{ffmpeg-devices.html,ffmpeg-devices}, 645@url{ffmpeg-protocols.html,ffmpeg-protocols}, 646@url{ffmpeg-filters.html,ffmpeg-filters} 647@end ifhtml 648 649@ifnothtml 650@ifset config-all 651ffprobe(1), 652@end ifset 653@ifset config-not-all 654ffprobe-all(1), 655@end ifset 656ffmpeg(1), ffplay(1), ffserver(1), 657ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1), 658ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1), 659ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1) 660@end ifnothtml 661 662@include authors.texi 663 664@ignore 665 666@setfilename ffprobe 667@settitle ffprobe media prober 668 669@end ignore 670 671@bye 672