ffprobe.texi 20 KB

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