diff options
Diffstat (limited to 'doc/ffprobe.texi')
| -rw-r--r-- | doc/ffprobe.texi | 671 |
1 files changed, 671 insertions, 0 deletions
diff --git a/doc/ffprobe.texi b/doc/ffprobe.texi new file mode 100644 index 0000000..8de8956 --- /dev/null +++ b/doc/ffprobe.texi @@ -0,0 +1,671 @@ +\input texinfo @c -*- texinfo -*- + +@settitle ffprobe Documentation +@titlepage +@center @titlefont{ffprobe Documentation} +@end titlepage + +@top + +@contents + +@chapter Synopsis + +ffprobe [@var{options}] [@file{input_file}] + +@chapter Description +@c man begin DESCRIPTION + +ffprobe gathers information from multimedia streams and prints it in +human- and machine-readable fashion. + +For example it can be used to check the format of the container used +by a multimedia stream and the format and type of each media stream +contained in it. + +If a filename is specified in input, ffprobe will try to open and +probe the file content. If the file cannot be opened or recognized as +a multimedia file, a positive exit code is returned. + +ffprobe may be employed both as a standalone application or in +combination with a textual filter, which may perform more +sophisticated processing, e.g. statistical processing or plotting. + +Options are used to list some of the formats supported by ffprobe or +for specifying which information to display, and for setting how +ffprobe will show it. + +ffprobe output is designed to be easily parsable by a textual filter, +and consists of one or more sections of a form defined by the selected +writer, which is specified by the @option{print_format} option. + +Sections may contain other nested sections, and are identified by a +name (which may be shared by other sections), and an unique +name. See the output of @option{sections}. + +Metadata tags stored in the container or in the streams are recognized +and printed in the corresponding "FORMAT", "STREAM" or "PROGRAM_STREAM" +section. + +@c man end + +@chapter Options +@c man begin OPTIONS + +@include fftools-common-opts.texi + +@section Main options + +@table @option + +@item -f @var{format} +Force format to use. + +@item -unit +Show the unit of the displayed values. + +@item -prefix +Use SI prefixes for the displayed values. +Unless the "-byte_binary_prefix" option is used all the prefixes +are decimal. + +@item -byte_binary_prefix +Force the use of binary prefixes for byte values. + +@item -sexagesimal +Use sexagesimal format HH:MM:SS.MICROSECONDS for time values. + +@item -pretty +Prettify the format of the displayed values, it corresponds to the +options "-unit -prefix -byte_binary_prefix -sexagesimal". + +@item -of, -print_format @var{writer_name}[=@var{writer_options}] +Set the output printing format. + +@var{writer_name} specifies the name of the writer, and +@var{writer_options} specifies the options to be passed to the writer. + +For example for printing the output in JSON format, specify: +@example +-print_format json +@end example + +For more details on the available output printing formats, see the +Writers section below. + +@item -sections +Print sections structure and section information, and exit. The output +is not meant to be parsed by a machine. + +@item -select_streams @var{stream_specifier} +Select only the streams specified by @var{stream_specifier}. This +option affects only the options related to streams +(e.g. @code{show_streams}, @code{show_packets}, etc.). + +For example to show only audio streams, you can use the command: +@example +ffprobe -show_streams -select_streams a INPUT +@end example + +To show only video packets belonging to the video stream with index 1: +@example +ffprobe -show_packets -select_streams v:1 INPUT +@end example + +@item -show_data +Show payload data, as a hexadecimal and ASCII dump. Coupled with +@option{-show_packets}, it will dump the packets' data. Coupled with +@option{-show_streams}, it will dump the codec extradata. + +The dump is printed as the "data" field. It may contain newlines. + +@item -show_error +Show information about the error found when trying to probe the input. + +The error information is printed within a section with name "ERROR". + +@item -show_format +Show information about the container format of the input multimedia +stream. + +All the container format information is printed within a section with +name "FORMAT". + +@item -show_format_entry @var{name} +Like @option{-show_format}, but only prints the specified entry of the +container format information, rather than all. This option may be given more +than once, then all specified entries will be shown. + +This option is deprecated, use @code{show_entries} instead. + +@item -show_entries @var{section_entries} +Set list of entries to show. + +Entries are specified according to the following +syntax. @var{section_entries} contains a list of section entries +separated by @code{:}. Each section entry is composed by a section +name (or unique name), optionally followed by a list of entries local +to that section, separated by @code{,}. + +If section name is specified but is followed by no @code{=}, all +entries are printed to output, together with all the contained +sections. Otherwise only the entries specified in the local section +entries list are printed. In particular, if @code{=} is specified but +the list of local entries is empty, then no entries will be shown for +that section. + +Note that the order of specification of the local section entries is +not honored in the output, and the usual display order will be +retained. + +The formal syntax is given by: +@example +@var{LOCAL_SECTION_ENTRIES} ::= @var{SECTION_ENTRY_NAME}[,@var{LOCAL_SECTION_ENTRIES}] +@var{SECTION_ENTRY} ::= @var{SECTION_NAME}[=[@var{LOCAL_SECTION_ENTRIES}]] +@var{SECTION_ENTRIES} ::= @var{SECTION_ENTRY}[:@var{SECTION_ENTRIES}] +@end example + +For example, to show only the index and type of each stream, and the PTS +time, duration time, and stream index of the packets, you can specify +the argument: +@example +packet=pts_time,duration_time,stream_index : stream=index,codec_type +@end example + +To show all the entries in the section "format", but only the codec +type in the section "stream", specify the argument: +@example +format : stream=codec_type +@end example + +To show all the tags in the stream and format sections: +@example +format_tags : format_tags +@end example + +To show only the @code{title} tag (if available) in the stream +sections: +@example +stream_tags=title +@end example + +@item -show_packets +Show information about each packet contained in the input multimedia +stream. + +The information for each single packet is printed within a dedicated +section with name "PACKET". + +@item -show_frames +Show information about each frame and subtitle contained in the input +multimedia stream. + +The information for each single frame is printed within a dedicated +section with name "FRAME" or "SUBTITLE". + +@item -show_streams +Show information about each media stream contained in the input +multimedia stream. + +Each media stream information is printed within a dedicated section +with name "STREAM". + +@item -show_programs +Show information about programs and their streams contained in the input +multimedia stream. + +Each media stream information is printed within a dedicated section +with name "PROGRAM_STREAM". + +@item -show_chapters +Show information about chapters stored in the format. + +Each chapter is printed within a dedicated section with name "CHAPTER". + +@item -count_frames +Count the number of frames per stream and report it in the +corresponding stream section. + +@item -count_packets +Count the number of packets per stream and report it in the +corresponding stream section. + +@item -read_intervals @var{read_intervals} + +Read only the specified intervals. @var{read_intervals} must be a +sequence of interval specifications separated by ",". +@command{ffprobe} will seek to the interval starting point, and will +continue reading from that. + +Each interval is specified by two optional parts, separated by "%". + +The first part specifies the interval start position. It is +interpreted as an abolute position, or as a relative offset from the +current position if it is preceded by the "+" character. If this first +part is not specified, no seeking will be performed when reading this +interval. + +The second part specifies the interval end position. It is interpreted +as an absolute position, or as a relative offset from the current +position if it is preceded by the "+" character. If the offset +specification starts with "#", it is interpreted as the number of +packets to read (not including the flushing packets) from the interval +start. If no second part is specified, the program will read until the +end of the input. + +Note that seeking is not accurate, thus the actual interval start +point may be different from the specified position. Also, when an +interval duration is specified, the absolute end time will be computed +by adding the duration to the interval start point found by seeking +the file, rather than to the specified start value. + +The formal syntax is given by: +@example +@var{INTERVAL} ::= [@var{START}|+@var{START_OFFSET}][%[@var{END}|+@var{END_OFFSET}]] +@var{INTERVALS} ::= @var{INTERVAL}[,@var{INTERVALS}] +@end example + +A few examples follow. +@itemize +@item +Seek to time 10, read packets until 20 seconds after the found seek +point, then seek to position @code{01:30} (1 minute and thirty +seconds) and read packets until position @code{01:45}. +@example +10%+20,01:30%01:45 +@end example + +@item +Read only 42 packets after seeking to position @code{01:23}: +@example +01:23%+#42 +@end example + +@item +Read only the first 20 seconds from the start: +@example +%+20 +@end example + +@item +Read from the start until position @code{02:30}: +@example +%02:30 +@end example +@end itemize + +@item -show_private_data, -private +Show private data, that is data depending on the format of the +particular shown element. +This option is enabled by default, but you may need to disable it +for specific uses, for example when creating XSD-compliant XML output. + +@item -show_program_version +Show information related to program version. + +Version information is printed within a section with name +"PROGRAM_VERSION". + +@item -show_library_versions +Show information related to library versions. + +Version information for each library is printed within a section with +name "LIBRARY_VERSION". + +@item -show_versions +Show information related to program and library versions. This is the +equivalent of setting both @option{-show_program_version} and +@option{-show_library_versions} options. + +@item -bitexact +Force bitexact output, useful to produce output which is not dependent +on the specific build. + +@item -i @var{input_file} +Read @var{input_file}. + +@end table +@c man end + +@chapter Writers +@c man begin WRITERS + +A writer defines the output format adopted by @command{ffprobe}, and will be +used for printing all the parts of the output. + +A writer may accept one or more arguments, which specify the options +to adopt. The options are specified as a list of @var{key}=@var{value} +pairs, separated by ":". + +All writers support the following options: + +@table @option +@item string_validation, sv +Set string validation mode. + +The following values are accepted. +@table @samp +@item fail +The writer will fail immediately in case an invalid string (UTF-8) +sequence or code point is found in the input. This is especially +useful to validate input metadata. + +@item ignore +Any validation error will be ignored. This will result in possibly +broken output, especially with the json or xml writer. + +@item replace +The writer will substitute invalid UTF-8 sequences or code points with +the string specified with the @option{string_validation_replacement}. +@end table + +Default value is @samp{replace}. + +@item string_validation_replacement, svr +Set replacement string to use in case @option{string_validation} is +set to @samp{replace}. + +In case the option is not specified, the writer will assume the empty +string, that is it will remove the invalid sequences from the input +strings. +@end table + +A description of the currently available writers follows. + +@section default +Default format. + +Print each section in the form: +@example +[SECTION] +key1=val1 +... +keyN=valN +[/SECTION] +@end example + +Metadata tags are printed as a line in the corresponding FORMAT, STREAM or +PROGRAM_STREAM section, and are prefixed by the string "TAG:". + +A description of the accepted options follows. + +@table @option + +@item nokey, nk +If set to 1 specify not to print the key of each field. Default value +is 0. + +@item noprint_wrappers, nw +If set to 1 specify not to print the section header and footer. +Default value is 0. +@end table + +@section compact, csv +Compact and CSV format. + +The @code{csv} writer is equivalent to @code{compact}, but supports +different defaults. + +Each section is printed on a single line. +If no option is specifid, the output has the form: +@example +section|key1=val1| ... |keyN=valN +@end example + +Metadata tags are printed in the corresponding "format" or "stream" +section. A metadata tag key, if printed, is prefixed by the string +"tag:". + +The description of the accepted options follows. + +@table @option + +@item item_sep, s +Specify the character to use for separating fields in the output line. +It must be a single printable character, it is "|" by default ("," for +the @code{csv} writer). + +@item nokey, nk +If set to 1 specify not to print the key of each field. Its default +value is 0 (1 for the @code{csv} writer). + +@item escape, e +Set the escape mode to use, default to "c" ("csv" for the @code{csv} +writer). + +It can assume one of the following values: +@table @option +@item c +Perform C-like escaping. Strings containing a newline ('\n'), carriage +return ('\r'), a tab ('\t'), a form feed ('\f'), the escaping +character ('\') or the item separator character @var{SEP} are escaped using C-like fashioned +escaping, so that a newline is converted to the sequence "\n", a +carriage return to "\r", '\' to "\\" and the separator @var{SEP} is +converted to "\@var{SEP}". + +@item csv +Perform CSV-like escaping, as described in RFC4180. Strings +containing a newline ('\n'), a carriage return ('\r'), a double quote +('"'), or @var{SEP} are enclosed in double-quotes. + +@item none +Perform no escaping. +@end table + +@item print_section, p +Print the section name at the begin of each line if the value is +@code{1}, disable it with value set to @code{0}. Default value is +@code{1}. + +@end table + +@section flat +Flat format. + +A free-form output where each line contains an explicit key=value, such as +"streams.stream.3.tags.foo=bar". The output is shell escaped, so it can be +directly embedded in sh scripts as long as the separator character is an +alphanumeric character or an underscore (see @var{sep_char} option). + +The description of the accepted options follows. + +@table @option +@item sep_char, s +Separator character used to separate the chapter, the section name, IDs and +potential tags in the printed field key. + +Default value is '.'. + +@item hierarchical, h +Specify if the section name specification should be hierarchical. If +set to 1, and if there is more than one section in the current +chapter, the section name will be prefixed by the name of the +chapter. A value of 0 will disable this behavior. + +Default value is 1. +@end table + +@section ini +INI format output. + +Print output in an INI based format. + +The following conventions are adopted: + +@itemize +@item +all key and values are UTF-8 +@item +'.' is the subgroup separator +@item +newline, '\t', '\f', '\b' and the following characters are escaped +@item +'\' is the escape character +@item +'#' is the comment indicator +@item +'=' is the key/value separator +@item +':' is not used but usually parsed as key/value separator +@end itemize + +This writer accepts options as a list of @var{key}=@var{value} pairs, +separated by ":". + +The description of the accepted options follows. + +@table @option +@item hierarchical, h +Specify if the section name specification should be hierarchical. If +set to 1, and if there is more than one section in the current +chapter, the section name will be prefixed by the name of the +chapter. A value of 0 will disable this behavior. + +Default value is 1. +@end table + +@section json +JSON based format. + +Each section is printed using JSON notation. + +The description of the accepted options follows. + +@table @option + +@item compact, c +If set to 1 enable compact output, that is each section will be +printed on a single line. Default value is 0. +@end table + +For more information about JSON, see @url{http://www.json.org/}. + +@section xml +XML based format. + +The XML output is described in the XML schema description file +@file{ffprobe.xsd} installed in the FFmpeg datadir. + +An updated version of the schema can be retrieved at the url +@url{http://www.ffmpeg.org/schema/ffprobe.xsd}, which redirects to the +latest schema committed into the FFmpeg development source code tree. + +Note that the output issued will be compliant to the +@file{ffprobe.xsd} schema only when no special global output options +(@option{unit}, @option{prefix}, @option{byte_binary_prefix}, +@option{sexagesimal} etc.) are specified. + +The description of the accepted options follows. + +@table @option + +@item fully_qualified, q +If set to 1 specify if the output should be fully qualified. Default +value is 0. +This is required for generating an XML file which can be validated +through an XSD file. + +@item xsd_compliant, x +If set to 1 perform more checks for ensuring that the output is XSD +compliant. Default value is 0. +This option automatically sets @option{fully_qualified} to 1. +@end table + +For more information about the XML format, see +@url{http://www.w3.org/XML/}. +@c man end WRITERS + +@chapter Timecode +@c man begin TIMECODE + +@command{ffprobe} supports Timecode extraction: + +@itemize + +@item +MPEG1/2 timecode is extracted from the GOP, and is available in the video +stream details (@option{-show_streams}, see @var{timecode}). + +@item +MOV timecode is extracted from tmcd track, so is available in the tmcd +stream metadata (@option{-show_streams}, see @var{TAG:timecode}). + +@item +DV, GXF and AVI timecodes are available in format metadata +(@option{-show_format}, see @var{TAG:timecode}). + +@end itemize +@c man end TIMECODE + +@include config.texi +@ifset config-all +@set config-readonly +@ifset config-avutil +@include utils.texi +@end ifset +@ifset config-avcodec +@include codecs.texi +@include bitstream_filters.texi +@end ifset +@ifset config-avformat +@include formats.texi +@include protocols.texi +@end ifset +@ifset config-avdevice +@include devices.texi +@end ifset +@ifset config-swresample +@include resampler.texi +@end ifset +@ifset config-swscale +@include scaler.texi +@end ifset +@ifset config-avfilter +@include filters.texi +@end ifset +@end ifset + +@chapter See Also + +@ifhtml +@ifset config-all +@url{ffprobe.html,ffprobe}, +@end ifset +@ifset config-not-all +@url{ffprobe-all.html,ffprobe-all}, +@end ifset +@url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffserver.html,ffserver}, +@url{ffmpeg-utils.html,ffmpeg-utils}, +@url{ffmpeg-scaler.html,ffmpeg-scaler}, +@url{ffmpeg-resampler.html,ffmpeg-resampler}, +@url{ffmpeg-codecs.html,ffmpeg-codecs}, +@url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters}, +@url{ffmpeg-formats.html,ffmpeg-formats}, +@url{ffmpeg-devices.html,ffmpeg-devices}, +@url{ffmpeg-protocols.html,ffmpeg-protocols}, +@url{ffmpeg-filters.html,ffmpeg-filters} +@end ifhtml + +@ifnothtml +@ifset config-all +ffprobe(1), +@end ifset +@ifset config-not-all +ffprobe-all(1), +@end ifset +ffmpeg(1), ffplay(1), ffserver(1), +ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1), +ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1), +ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1) +@end ifnothtml + +@include authors.texi + +@ignore + +@setfilename ffprobe +@settitle ffprobe media prober + +@end ignore + +@bye |
