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