doc: More semantic markup using @samp and @var where appropriate
[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_file}]
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 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.
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_streams
212 Show information about each media stream contained in the input
213 multimedia stream.
214
215 Each media stream information is printed within a dedicated section
216 with name "STREAM".
217
218 @item -show_programs
219 Show information about programs and their streams contained in the input
220 multimedia stream.
221
222 Each media stream information is printed within a dedicated section
223 with name "PROGRAM_STREAM".
224
225 @item -show_chapters
226 Show information about chapters stored in the format.
227
228 Each chapter is printed within a dedicated section with name "CHAPTER".
229
230 @item -count_frames
231 Count the number of frames per stream and report it in the
232 corresponding stream section.
233
234 @item -count_packets
235 Count the number of packets per stream and report it in the
236 corresponding stream section.
237
238 @item -read_intervals @var{read_intervals}
239
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.
244
245 Each interval is specified by two optional parts, separated by "%".
246
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
251 interval.
252
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
259 end of the input.
260
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.
266
267 The formal syntax is given by:
268 @example
269 @var{INTERVAL}  ::= [@var{START}|+@var{START_OFFSET}][%[@var{END}|+@var{END_OFFSET}]]
270 @var{INTERVALS} ::= @var{INTERVAL}[,@var{INTERVALS}]
271 @end example
272
273 A few examples follow.
274 @itemize
275 @item
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}.
279 @example
280 10%+20,01:30%01:45
281 @end example
282
283 @item
284 Read only 42 packets after seeking to position @code{01:23}:
285 @example
286 01:23%+#42
287 @end example
288
289 @item
290 Read only the first 20 seconds from the start:
291 @example
292 %+20
293 @end example
294
295 @item
296 Read from the start until position @code{02:30}:
297 @example
298 %02:30
299 @end example
300 @end itemize
301
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.
307
308 @item -show_program_version
309 Show information related to program version.
310
311 Version information is printed within a section with name
312 "PROGRAM_VERSION".
313
314 @item -show_library_versions
315 Show information related to library versions.
316
317 Version information for each library is printed within a section with
318 name "LIBRARY_VERSION".
319
320 @item -show_versions
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.
324
325 @item -show_pixel_formats
326 Show information about all pixel formats supported by FFmpeg.
327
328 Pixel format information for each format is printed within a section
329 with name "PIXEL_FORMAT".
330
331 @item -bitexact
332 Force bitexact output, useful to produce output which is not dependent
333 on the specific build.
334
335 @item -i @var{input_file}
336 Read @var{input_file}.
337
338 @end table
339 @c man end
340
341 @chapter Writers
342 @c man begin WRITERS
343
344 A writer defines the output format adopted by @command{ffprobe}, and will be
345 used for printing all the parts of the output.
346
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 ":".
350
351 All writers support the following options:
352
353 @table @option
354 @item string_validation, sv
355 Set string validation mode.
356
357 The following values are accepted.
358 @table @samp
359 @item fail
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.
363
364 @item ignore
365 Any validation error will be ignored. This will result in possibly
366 broken output, especially with the json or xml writer.
367
368 @item replace
369 The writer will substitute invalid UTF-8 sequences or code points with
370 the string specified with the @option{string_validation_replacement}.
371 @end table
372
373 Default value is @samp{replace}.
374
375 @item string_validation_replacement, svr
376 Set replacement string to use in case @option{string_validation} is
377 set to @samp{replace}.
378
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
381 strings.
382 @end table
383
384 A description of the currently available writers follows.
385
386 @section default
387 Default format.
388
389 Print each section in the form:
390 @example
391 [SECTION]
392 key1=val1
393 ...
394 keyN=valN
395 [/SECTION]
396 @end example
397
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:".
400
401 A description of the accepted options follows.
402
403 @table @option
404
405 @item nokey, nk
406 If set to 1 specify not to print the key of each field. Default value
407 is 0.
408
409 @item noprint_wrappers, nw
410 If set to 1 specify not to print the section header and footer.
411 Default value is 0.
412 @end table
413
414 @section compact, csv
415 Compact and CSV format.
416
417 The @code{csv} writer is equivalent to @code{compact}, but supports
418 different defaults.
419
420 Each section is printed on a single line.
421 If no option is specifid, the output has the form:
422 @example
423 section|key1=val1| ... |keyN=valN
424 @end example
425
426 Metadata tags are printed in the corresponding "format" or "stream"
427 section. A metadata tag key, if printed, is prefixed by the string
428 "tag:".
429
430 The description of the accepted options follows.
431
432 @table @option
433
434 @item item_sep, s
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).
438
439 @item nokey, nk
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).
442
443 @item escape, e
444 Set the escape mode to use, default to "c" ("csv" for the @code{csv}
445 writer).
446
447 It can assume one of the following values:
448 @table @option
449 @item c
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}}.
456
457 @item csv
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.
461
462 @item none
463 Perform no escaping.
464 @end table
465
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
469 @code{1}.
470
471 @end table
472
473 @section flat
474 Flat format.
475
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).
480
481 The description of the accepted options follows.
482
483 @table @option
484 @item sep_char, s
485 Separator character used to separate the chapter, the section name, IDs and
486 potential tags in the printed field key.
487
488 Default value is @samp{.}.
489
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.
495
496 Default value is 1.
497 @end table
498
499 @section ini
500 INI format output.
501
502 Print output in an INI based format.
503
504 The following conventions are adopted:
505
506 @itemize
507 @item
508 all key and values are UTF-8
509 @item
510 @samp{.} is the subgroup separator
511 @item
512 newline, @samp{\t}, @samp{\f}, @samp{\b} and the following characters are
513 escaped
514 @item
515 @samp{\} is the escape character
516 @item
517 @samp{#} is the comment indicator
518 @item
519 @samp{=} is the key/value separator
520 @item
521 @samp{:} is not used but usually parsed as key/value separator
522 @end itemize
523
524 This writer accepts options as a list of @var{key}=@var{value} pairs,
525 separated by @samp{:}.
526
527 The description of the accepted options follows.
528
529 @table @option
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.
535
536 Default value is 1.
537 @end table
538
539 @section json
540 JSON based format.
541
542 Each section is printed using JSON notation.
543
544 The description of the accepted options follows.
545
546 @table @option
547
548 @item compact, c
549 If set to 1 enable compact output, that is each section will be
550 printed on a single line. Default value is 0.
551 @end table
552
553 For more information about JSON, see @url{http://www.json.org/}.
554
555 @section xml
556 XML based format.
557
558 The XML output is described in the XML schema description file
559 @file{ffprobe.xsd} installed in the FFmpeg datadir.
560
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.
564
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.
569
570 The description of the accepted options follows.
571
572 @table @option
573
574 @item fully_qualified, q
575 If set to 1 specify if the output should be fully qualified. Default
576 value is 0.
577 This is required for generating an XML file which can be validated
578 through an XSD file.
579
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.
584 @end table
585
586 For more information about the XML format, see
587 @url{http://www.w3.org/XML/}.
588 @c man end WRITERS
589
590 @chapter Timecode
591 @c man begin TIMECODE
592
593 @command{ffprobe} supports Timecode extraction:
594
595 @itemize
596
597 @item
598 MPEG1/2 timecode is extracted from the GOP, and is available in the video
599 stream details (@option{-show_streams}, see @var{timecode}).
600
601 @item
602 MOV timecode is extracted from tmcd track, so is available in the tmcd
603 stream metadata (@option{-show_streams}, see @var{TAG:timecode}).
604
605 @item
606 DV, GXF and AVI timecodes are available in format metadata
607 (@option{-show_format}, see @var{TAG:timecode}).
608
609 @end itemize
610 @c man end TIMECODE
611
612 @include config.texi
613 @ifset config-all
614 @set config-readonly
615 @ifset config-avutil
616 @include utils.texi
617 @end ifset
618 @ifset config-avcodec
619 @include codecs.texi
620 @include bitstream_filters.texi
621 @end ifset
622 @ifset config-avformat
623 @include formats.texi
624 @include protocols.texi
625 @end ifset
626 @ifset config-avdevice
627 @include devices.texi
628 @end ifset
629 @ifset config-swresample
630 @include resampler.texi
631 @end ifset
632 @ifset config-swscale
633 @include scaler.texi
634 @end ifset
635 @ifset config-avfilter
636 @include filters.texi
637 @end ifset
638 @end ifset
639
640 @chapter See Also
641
642 @ifhtml
643 @ifset config-all
644 @url{ffprobe.html,ffprobe},
645 @end ifset
646 @ifset config-not-all
647 @url{ffprobe-all.html,ffprobe-all},
648 @end ifset
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}
659 @end ifhtml
660
661 @ifnothtml
662 @ifset config-all
663 ffprobe(1),
664 @end ifset
665 @ifset config-not-all
666 ffprobe-all(1),
667 @end ifset
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)
672 @end ifnothtml
673
674 @include authors.texi
675
676 @ignore
677
678 @setfilename ffprobe
679 @settitle ffprobe media prober
680
681 @end ignore
682
683 @bye