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