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