ffprobe.texi 20 KB

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