1 \input texinfo @c -*- texinfo -*-
2 @documentencoding UTF-8
4 @settitle ffprobe Documentation
6 @center @titlefont{ffprobe Documentation}
15 ffprobe [@var{options}] [@file{input_file}]
18 @c man begin DESCRIPTION
20 ffprobe gathers information from multimedia streams and prints it in
21 human- and machine-readable fashion.
23 For example it can be used to check the format of the container used
24 by a multimedia stream and the format and type of each media stream
27 If a filename is specified in input, ffprobe will try to open and
28 probe the file content. If the file cannot be opened or recognized as
29 a multimedia file, a positive exit code is returned.
31 ffprobe may be employed both as a standalone application or in
32 combination with a textual filter, which may perform more
33 sophisticated processing, e.g. statistical processing or plotting.
35 Options are used to list some of the formats supported by ffprobe or
36 for specifying which information to display, and for setting how
39 ffprobe output is designed to be easily parsable by a textual filter,
40 and consists of one or more sections of a form defined by the selected
41 writer, which is specified by the @option{print_format} option.
43 Sections may contain other nested sections, and are identified by a
44 name (which may be shared by other sections), and an unique
45 name. See the output of @option{sections}.
47 Metadata tags stored in the container or in the streams are recognized
48 and printed in the corresponding "FORMAT", "STREAM" or "PROGRAM_STREAM"
56 @include fftools-common-opts.texi
66 Show the unit of the displayed values.
69 Use SI prefixes for the displayed values.
70 Unless the "-byte_binary_prefix" option is used all the prefixes
73 @item -byte_binary_prefix
74 Force the use of binary prefixes for byte values.
77 Use sexagesimal format HH:MM:SS.MICROSECONDS for time values.
80 Prettify the format of the displayed values, it corresponds to the
81 options "-unit -prefix -byte_binary_prefix -sexagesimal".
83 @item -of, -print_format @var{writer_name}[=@var{writer_options}]
84 Set the output printing format.
86 @var{writer_name} specifies the name of the writer, and
87 @var{writer_options} specifies the options to be passed to the writer.
89 For example for printing the output in JSON format, specify:
94 For more details on the available output printing formats, see the
95 Writers section below.
98 Print sections structure and section information, and exit. The output
99 is not meant to be parsed by a machine.
101 @item -select_streams @var{stream_specifier}
102 Select only the streams specified by @var{stream_specifier}. This
103 option affects only the options related to streams
104 (e.g. @code{show_streams}, @code{show_packets}, etc.).
106 For example to show only audio streams, you can use the command:
108 ffprobe -show_streams -select_streams a INPUT
111 To show only video packets belonging to the video stream with index 1:
113 ffprobe -show_packets -select_streams v:1 INPUT
117 Show payload data, as a hexadecimal and ASCII dump. Coupled with
118 @option{-show_packets}, it will dump the packets' data. Coupled with
119 @option{-show_streams}, it will dump the codec extradata.
121 The dump is printed as the "data" field. It may contain newlines.
123 @item -show_data_hash @var{algorithm}
124 Show a hash of payload data, for packets with @option{-show_packets} and for
125 codec extradata with @option{-show_streams}.
128 Show information about the error found when trying to probe the input.
130 The error information is printed within a section with name "ERROR".
133 Show information about the container format of the input multimedia
136 All the container format information is printed within a section with
139 @item -show_format_entry @var{name}
140 Like @option{-show_format}, but only prints the specified entry of the
141 container format information, rather than all. This option may be given more
142 than once, then all specified entries will be shown.
144 This option is deprecated, use @code{show_entries} instead.
146 @item -show_entries @var{section_entries}
147 Set list of entries to show.
149 Entries are specified according to the following
150 syntax. @var{section_entries} contains a list of section entries
151 separated by @code{:}. Each section entry is composed by a section
152 name (or unique name), optionally followed by a list of entries local
153 to that section, separated by @code{,}.
155 If section name is specified but is followed by no @code{=}, all
156 entries are printed to output, together with all the contained
157 sections. Otherwise only the entries specified in the local section
158 entries list are printed. In particular, if @code{=} is specified but
159 the list of local entries is empty, then no entries will be shown for
162 Note that the order of specification of the local section entries is
163 not honored in the output, and the usual display order will be
166 The formal syntax is given by:
168 @var{LOCAL_SECTION_ENTRIES} ::= @var{SECTION_ENTRY_NAME}[,@var{LOCAL_SECTION_ENTRIES}]
169 @var{SECTION_ENTRY} ::= @var{SECTION_NAME}[=[@var{LOCAL_SECTION_ENTRIES}]]
170 @var{SECTION_ENTRIES} ::= @var{SECTION_ENTRY}[:@var{SECTION_ENTRIES}]
173 For example, to show only the index and type of each stream, and the PTS
174 time, duration time, and stream index of the packets, you can specify
177 packet=pts_time,duration_time,stream_index : stream=index,codec_type
180 To show all the entries in the section "format", but only the codec
181 type in the section "stream", specify the argument:
183 format : stream=codec_type
186 To show all the tags in the stream and format sections:
188 stream_tags : format_tags
191 To show only the @code{title} tag (if available) in the stream
198 Show information about each packet contained in the input multimedia
201 The information for each single packet is printed within a dedicated
202 section with name "PACKET".
205 Show information about each frame and subtitle contained in the input
208 The information for each single frame is printed within a dedicated
209 section with name "FRAME" or "SUBTITLE".
212 Show information about each media stream contained in the input
215 Each media stream information is printed within a dedicated section
219 Show information about programs and their streams contained in the input
222 Each media stream information is printed within a dedicated section
223 with name "PROGRAM_STREAM".
226 Show information about chapters stored in the format.
228 Each chapter is printed within a dedicated section with name "CHAPTER".
231 Count the number of frames per stream and report it in the
232 corresponding stream section.
235 Count the number of packets per stream and report it in the
236 corresponding stream section.
238 @item -read_intervals @var{read_intervals}
240 Read only the specified intervals. @var{read_intervals} must be a
241 sequence of interval specifications separated by ",".
242 @command{ffprobe} will seek to the interval starting point, and will
243 continue reading from that.
245 Each interval is specified by two optional parts, separated by "%".
247 The first part specifies the interval start position. It is
248 interpreted as an abolute position, or as a relative offset from the
249 current position if it is preceded by the "+" character. If this first
250 part is not specified, no seeking will be performed when reading this
253 The second part specifies the interval end position. It is interpreted
254 as an absolute position, or as a relative offset from the current
255 position if it is preceded by the "+" character. If the offset
256 specification starts with "#", it is interpreted as the number of
257 packets to read (not including the flushing packets) from the interval
258 start. If no second part is specified, the program will read until the
261 Note that seeking is not accurate, thus the actual interval start
262 point may be different from the specified position. Also, when an
263 interval duration is specified, the absolute end time will be computed
264 by adding the duration to the interval start point found by seeking
265 the file, rather than to the specified start value.
267 The formal syntax is given by:
269 @var{INTERVAL} ::= [@var{START}|+@var{START_OFFSET}][%[@var{END}|+@var{END_OFFSET}]]
270 @var{INTERVALS} ::= @var{INTERVAL}[,@var{INTERVALS}]
273 A few examples follow.
276 Seek to time 10, read packets until 20 seconds after the found seek
277 point, then seek to position @code{01:30} (1 minute and thirty
278 seconds) and read packets until position @code{01:45}.
284 Read only 42 packets after seeking to position @code{01:23}:
290 Read only the first 20 seconds from the start:
296 Read from the start until position @code{02:30}:
302 @item -show_private_data, -private
303 Show private data, that is data depending on the format of the
304 particular shown element.
305 This option is enabled by default, but you may need to disable it
306 for specific uses, for example when creating XSD-compliant XML output.
308 @item -show_program_version
309 Show information related to program version.
311 Version information is printed within a section with name
314 @item -show_library_versions
315 Show information related to library versions.
317 Version information for each library is printed within a section with
318 name "LIBRARY_VERSION".
321 Show information related to program and library versions. This is the
322 equivalent of setting both @option{-show_program_version} and
323 @option{-show_library_versions} options.
325 @item -show_pixel_formats
326 Show information about all pixel formats supported by FFmpeg.
328 Pixel format information for each format is printed within a section
329 with name "PIXEL_FORMAT".
332 Force bitexact output, useful to produce output which is not dependent
333 on the specific build.
335 @item -i @var{input_file}
336 Read @var{input_file}.
344 A writer defines the output format adopted by @command{ffprobe}, and will be
345 used for printing all the parts of the output.
347 A writer may accept one or more arguments, which specify the options
348 to adopt. The options are specified as a list of @var{key}=@var{value}
349 pairs, separated by ":".
351 All writers support the following options:
354 @item string_validation, sv
355 Set string validation mode.
357 The following values are accepted.
360 The writer will fail immediately in case an invalid string (UTF-8)
361 sequence or code point is found in the input. This is especially
362 useful to validate input metadata.
365 Any validation error will be ignored. This will result in possibly
366 broken output, especially with the json or xml writer.
369 The writer will substitute invalid UTF-8 sequences or code points with
370 the string specified with the @option{string_validation_replacement}.
373 Default value is @samp{replace}.
375 @item string_validation_replacement, svr
376 Set replacement string to use in case @option{string_validation} is
377 set to @samp{replace}.
379 In case the option is not specified, the writer will assume the empty
380 string, that is it will remove the invalid sequences from the input
384 A description of the currently available writers follows.
389 Print each section in the form:
398 Metadata tags are printed as a line in the corresponding FORMAT, STREAM or
399 PROGRAM_STREAM section, and are prefixed by the string "TAG:".
401 A description of the accepted options follows.
406 If set to 1 specify not to print the key of each field. Default value
409 @item noprint_wrappers, nw
410 If set to 1 specify not to print the section header and footer.
414 @section compact, csv
415 Compact and CSV format.
417 The @code{csv} writer is equivalent to @code{compact}, but supports
420 Each section is printed on a single line.
421 If no option is specifid, the output has the form:
423 section|key1=val1| ... |keyN=valN
426 Metadata tags are printed in the corresponding "format" or "stream"
427 section. A metadata tag key, if printed, is prefixed by the string
430 The description of the accepted options follows.
435 Specify the character to use for separating fields in the output line.
436 It must be a single printable character, it is "|" by default ("," for
437 the @code{csv} writer).
440 If set to 1 specify not to print the key of each field. Its default
441 value is 0 (1 for the @code{csv} writer).
444 Set the escape mode to use, default to "c" ("csv" for the @code{csv}
447 It can assume one of the following values:
450 Perform C-like escaping. Strings containing a newline (@samp{\n}), carriage
451 return (@samp{\r}), a tab (@samp{\t}), a form feed (@samp{\f}), the escaping
452 character (@samp{\}) or the item separator character @var{SEP} are escaped
453 using C-like fashioned escaping, so that a newline is converted to the
454 sequence @samp{\n}, a carriage return to @samp{\r}, @samp{\} to @samp{\\} and
455 the separator @var{SEP} is converted to @samp{\@var{SEP}}.
458 Perform CSV-like escaping, as described in RFC4180. Strings
459 containing a newline (@samp{\n}), a carriage return (@samp{\r}), a double quote
460 (@samp{"}), or @var{SEP} are enclosed in double-quotes.
466 @item print_section, p
467 Print the section name at the begin of each line if the value is
468 @code{1}, disable it with value set to @code{0}. Default value is
476 A free-form output where each line contains an explicit key=value, such as
477 "streams.stream.3.tags.foo=bar". The output is shell escaped, so it can be
478 directly embedded in sh scripts as long as the separator character is an
479 alphanumeric character or an underscore (see @var{sep_char} option).
481 The description of the accepted options follows.
485 Separator character used to separate the chapter, the section name, IDs and
486 potential tags in the printed field key.
488 Default value is @samp{.}.
490 @item hierarchical, h
491 Specify if the section name specification should be hierarchical. If
492 set to 1, and if there is more than one section in the current
493 chapter, the section name will be prefixed by the name of the
494 chapter. A value of 0 will disable this behavior.
502 Print output in an INI based format.
504 The following conventions are adopted:
508 all key and values are UTF-8
510 @samp{.} is the subgroup separator
512 newline, @samp{\t}, @samp{\f}, @samp{\b} and the following characters are
515 @samp{\} is the escape character
517 @samp{#} is the comment indicator
519 @samp{=} is the key/value separator
521 @samp{:} is not used but usually parsed as key/value separator
524 This writer accepts options as a list of @var{key}=@var{value} pairs,
525 separated by @samp{:}.
527 The description of the accepted options follows.
530 @item hierarchical, h
531 Specify if the section name specification should be hierarchical. If
532 set to 1, and if there is more than one section in the current
533 chapter, the section name will be prefixed by the name of the
534 chapter. A value of 0 will disable this behavior.
542 Each section is printed using JSON notation.
544 The description of the accepted options follows.
549 If set to 1 enable compact output, that is each section will be
550 printed on a single line. Default value is 0.
553 For more information about JSON, see @url{http://www.json.org/}.
558 The XML output is described in the XML schema description file
559 @file{ffprobe.xsd} installed in the FFmpeg datadir.
561 An updated version of the schema can be retrieved at the url
562 @url{http://www.ffmpeg.org/schema/ffprobe.xsd}, which redirects to the
563 latest schema committed into the FFmpeg development source code tree.
565 Note that the output issued will be compliant to the
566 @file{ffprobe.xsd} schema only when no special global output options
567 (@option{unit}, @option{prefix}, @option{byte_binary_prefix},
568 @option{sexagesimal} etc.) are specified.
570 The description of the accepted options follows.
574 @item fully_qualified, q
575 If set to 1 specify if the output should be fully qualified. Default
577 This is required for generating an XML file which can be validated
580 @item xsd_compliant, x
581 If set to 1 perform more checks for ensuring that the output is XSD
582 compliant. Default value is 0.
583 This option automatically sets @option{fully_qualified} to 1.
586 For more information about the XML format, see
587 @url{http://www.w3.org/XML/}.
591 @c man begin TIMECODE
593 @command{ffprobe} supports Timecode extraction:
598 MPEG1/2 timecode is extracted from the GOP, and is available in the video
599 stream details (@option{-show_streams}, see @var{timecode}).
602 MOV timecode is extracted from tmcd track, so is available in the tmcd
603 stream metadata (@option{-show_streams}, see @var{TAG:timecode}).
606 DV, GXF and AVI timecodes are available in format metadata
607 (@option{-show_format}, see @var{TAG:timecode}).
618 @ifset config-avcodec
620 @include bitstream_filters.texi
622 @ifset config-avformat
623 @include formats.texi
624 @include protocols.texi
626 @ifset config-avdevice
627 @include devices.texi
629 @ifset config-swresample
630 @include resampler.texi
632 @ifset config-swscale
635 @ifset config-avfilter
636 @include filters.texi
644 @url{ffprobe.html,ffprobe},
646 @ifset config-not-all
647 @url{ffprobe-all.html,ffprobe-all},
649 @url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffserver.html,ffserver},
650 @url{ffmpeg-utils.html,ffmpeg-utils},
651 @url{ffmpeg-scaler.html,ffmpeg-scaler},
652 @url{ffmpeg-resampler.html,ffmpeg-resampler},
653 @url{ffmpeg-codecs.html,ffmpeg-codecs},
654 @url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters},
655 @url{ffmpeg-formats.html,ffmpeg-formats},
656 @url{ffmpeg-devices.html,ffmpeg-devices},
657 @url{ffmpeg-protocols.html,ffmpeg-protocols},
658 @url{ffmpeg-filters.html,ffmpeg-filters}
665 @ifset config-not-all
668 ffmpeg(1), ffplay(1), ffserver(1),
669 ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
670 ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),
671 ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1)
674 @include authors.texi
679 @settitle ffprobe media prober