ffprobe.1 (34397B)
- .Dd August 2, 2024
- .Dt FFPROBE 7
- .Os
- .Sh NAME
- .Nm ffprobe
- .Nd ffprobe Documentation
- .Sh
- .Sh Synopsis
- ffprobe [
- .Va options
- ]
- .Pa input_url
- .Pp
- .Sh Description
- ffprobe gathers information from multimedia streams and prints it in human-
- and machine-readable fashion.
- .Pp
- 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.
- .Pp
- If a url is specified in input, ffprobe will try to open and probe the url
- content. If the url cannot be opened or recognized as a multimedia file, a
- positive exit code is returned.
- .Pp
- If no output is specified as output with
- .Op o
- ffprobe will write to stdout.
- .Pp
- 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.
- .Pp
- 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.
- .Pp
- 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
- .Op output_format
- option.
- .Pp
- 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
- .Op sections .
- .Pp
- Metadata tags stored in the container or in the streams are recognized and
- printed in the corresponding "FORMAT", "STREAM", "STREAM_GROUP_STREAM" or
- "PROGRAM_STREAM" section.
- .Pp
- .Sh Options
- All the numerical options, if not specified otherwise, accept a string representing
- a number as input, which may be followed by one of the SI unit prefixes, for
- example: 'K', 'M', or 'G'.
- .Pp
- If 'i' is appended to the SI unit prefix, the complete prefix will be interpreted
- as a unit prefix for binary multiples, which are based on powers of 1024 instead
- of powers of 1000. Appending 'B' to the SI unit prefix multiplies the value
- by 8. This allows using, for example: 'KB', 'MiB', 'G' and 'B' as number suffixes.
- .Pp
- Options which do not take arguments are boolean options, and set the corresponding
- value to true. They can be set to false by prefixing the option name with
- "no". For example using "-nofoo" will set the boolean option with name "foo"
- to false.
- .Pp
- Options that take arguments support a special syntax where the argument given
- on the command line is interpreted as a path to the file from which the actual
- argument value is loaded. To use this feature, add a forward slash '/' immediately
- before the option name (after the leading dash). E.g.
- .Bd -literal -offset indent
- ffmpeg -i INPUT -/filter:v filter.script OUTPUT
- .Ed
- will load a filtergraph description from the file named
- .Pa filter.script .
- .Pp
- .Ss Stream specifiers
- Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers
- are used to precisely specify which stream(s) a given option belongs to.
- .Pp
- A stream specifier is a string generally appended to the option name and separated
- from it by a colon. E.g.
- .Li -codec:a:1 ac3
- contains the
- .Li a:1
- stream specifier, which matches the second audio stream. Therefore, it would
- select the ac3 codec for the second audio stream.
- .Pp
- A stream specifier can match several streams, so that the option is applied
- to all of them. E.g. the stream specifier in
- .Li -b:a 128k
- matches all audio streams.
- .Pp
- An empty stream specifier matches all streams. For example,
- .Li -codec copy
- or
- .Li -codec: copy
- would copy all the streams without reencoding.
- .Pp
- Possible forms of stream specifiers are:
- .Bl -tag -width Ds
- .It Va stream_index
- Matches the stream with this index. E.g.
- .Li -threads:1 4
- would set the thread count for the second stream to 4. If
- .Va stream_index
- is used as an additional stream specifier (see below), then it selects stream
- number
- .Va stream_index
- from the matching streams. Stream numbering is based on the order of the streams
- as detected by libavformat except when a stream group specifier or program
- ID is also specified. In this case it is based on the ordering of the streams
- in the group or program.
- .It Va stream_type[: Va additional_stream_specifier]
- .Va stream_type
- is one of following: 'v' or 'V' for video, 'a' for audio, 's' for subtitle,
- \&'d' for data, and 't' for attachments. 'v' matches all video streams, 'V'
- only matches video streams which are not attached pictures, video thumbnails
- or cover arts. If
- .Va additional_stream_specifier
- is used, then it matches streams which both have this type and match the
- .Va additional_stream_specifier .
- Otherwise, it matches all streams of the specified type.
- .It g: Va group_specifier[: Va additional_stream_specifier]
- Matches streams which are in the group with the specifier
- .Va group_specifier .
- if
- .Va additional_stream_specifier
- is used, then it matches streams which both are part of the group and match
- the
- .Va additional_stream_specifier .
- .Va group_specifier
- may be one of the following:
- .Bl -tag -width Ds
- .It Va group_index
- Match the stream with this group index.
- .It # Va group_id or i: Va group_id
- Match the stream with this group id.
- .El
- .It p: Va program_id[: Va additional_stream_specifier]
- Matches streams which are in the program with the id
- .Va program_id .
- If
- .Va additional_stream_specifier
- is used, then it matches streams which both are part of the program and match
- the
- .Va additional_stream_specifier .
- .Pp
- .It # Va stream_id or i: Va stream_id
- Match the stream by stream id (e.g. PID in MPEG-TS container).
- .It m: Va key[: Va value]
- Matches streams with the metadata tag
- .Va key
- having the specified value. If
- .Va value
- is not given, matches streams that contain the given tag with any value.
- .It u
- Matches streams with usable configuration, the codec must be defined and the
- essential information such as video dimension or audio sample rate must be
- present.
- .Pp
- Note that in
- .Xr ffmpeg ,
- matching by metadata will only work properly for input files.
- .El
- .Pp
- .Ss Generic options
- These options are shared amongst the ff* tools.
- .Pp
- .Bl -tag -width Ds
- .It -L
- Show license.
- .Pp
- .It -h, -?, -help, --help [ Va arg]
- Show help. An optional parameter may be specified to print help about a specific
- item. If no argument is specified, only basic (non advanced) tool options
- are shown.
- .Pp
- Possible values of
- .Va arg
- are:
- .Bl -tag -width Ds
- .It long
- Print advanced tool options in addition to the basic tool options.
- .Pp
- .It full
- Print complete list of options, including shared and private options for encoders,
- decoders, demuxers, muxers, filters, etc.
- .Pp
- .It decoder= Va decoder_name
- Print detailed information about the decoder named
- .Va decoder_name .
- Use the
- .Op -decoders
- option to get a list of all decoders.
- .Pp
- .It encoder= Va encoder_name
- Print detailed information about the encoder named
- .Va encoder_name .
- Use the
- .Op -encoders
- option to get a list of all encoders.
- .Pp
- .It demuxer= Va demuxer_name
- Print detailed information about the demuxer named
- .Va demuxer_name .
- Use the
- .Op -formats
- option to get a list of all demuxers and muxers.
- .Pp
- .It muxer= Va muxer_name
- Print detailed information about the muxer named
- .Va muxer_name .
- Use the
- .Op -formats
- option to get a list of all muxers and demuxers.
- .Pp
- .It filter= Va filter_name
- Print detailed information about the filter named
- .Va filter_name .
- Use the
- .Op -filters
- option to get a list of all filters.
- .Pp
- .It bsf= Va bitstream_filter_name
- Print detailed information about the bitstream filter named
- .Va bitstream_filter_name .
- Use the
- .Op -bsfs
- option to get a list of all bitstream filters.
- .Pp
- .It protocol= Va protocol_name
- Print detailed information about the protocol named
- .Va protocol_name .
- Use the
- .Op -protocols
- option to get a list of all protocols.
- .El
- .Pp
- .It -version
- Show version.
- .Pp
- .It -buildconf
- Show the build configuration, one option per line.
- .Pp
- .It -formats
- Show available formats (including devices).
- .Pp
- .It -demuxers
- Show available demuxers.
- .Pp
- .It -muxers
- Show available muxers.
- .Pp
- .It -devices
- Show available devices.
- .Pp
- .It -codecs
- Show all codecs known to libavcodec.
- .Pp
- Note that the term 'codec' is used throughout this documentation as a shortcut
- for what is more correctly called a media bitstream format.
- .Pp
- .It -decoders
- Show available decoders.
- .Pp
- .It -encoders
- Show all available encoders.
- .Pp
- .It -bsfs
- Show available bitstream filters.
- .Pp
- .It -protocols
- Show available protocols.
- .Pp
- .It -filters
- Show available libavfilter filters.
- .Pp
- .It -pix_fmts
- Show available pixel formats.
- .Pp
- .It -sample_fmts
- Show available sample formats.
- .Pp
- .It -layouts
- Show channel names and standard channel layouts.
- .Pp
- .It -dispositions
- Show stream dispositions.
- .Pp
- .It -colors
- Show recognized color names.
- .Pp
- .It -sources Va device[, Va opt1= Va val1[, Va opt2= Va val2]...]
- Show autodetected sources of the input device. Some devices may provide system-dependent
- source names that cannot be autodetected. The returned list cannot be assumed
- to be always complete.
- .Bd -literal -offset indent
- ffmpeg -sources pulse,server=192.168.0.4
- .Ed
- .Pp
- .It -sinks Va device[, Va opt1= Va val1[, Va opt2= Va val2]...]
- Show autodetected sinks of the output device. Some devices may provide system-dependent
- sink names that cannot be autodetected. The returned list cannot be assumed
- to be always complete.
- .Bd -literal -offset indent
- ffmpeg -sinks pulse,server=192.168.0.4
- .Ed
- .Pp
- .It -loglevel [ Va flags+] Va loglevel | -v [ Va flags+] Va loglevel
- Set logging level and flags used by the library.
- .Pp
- The optional
- .Va flags
- prefix can consist of the following values:
- .Bl -tag -width Ds
- .It repeat
- Indicates that repeated log output should not be compressed to the first line
- and the "Last message repeated n times" line will be omitted.
- .It level
- Indicates that log output should add a
- .Li [level]
- prefix to each message line. This can be used as an alternative to log coloring,
- e.g. when dumping the log to file.
- .El
- Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single
- flag without affecting other
- .Va flags
- or changing
- .Va loglevel .
- When setting both
- .Va flags
- and
- .Va loglevel ,
- a '+' separator is expected between the last
- .Va flags
- value and before
- .Va loglevel .
- .Pp
- .Va loglevel
- is a string or a number containing one of the following values:
- .Bl -tag -width Ds
- .It quiet, -8
- Show nothing at all; be silent.
- .It panic, 0
- Only show fatal errors which could lead the process to crash, such as an assertion
- failure. This is not currently used for anything.
- .It fatal, 8
- Only show fatal errors. These are errors after which the process absolutely
- cannot continue.
- .It error, 16
- Show all errors, including ones which can be recovered from.
- .It warning, 24
- Show all warnings and errors. Any message related to possibly incorrect or
- unexpected events will be shown.
- .It info, 32
- Show informative messages during processing. This is in addition to warnings
- and errors. This is the default value.
- .It verbose, 40
- Same as
- .Li info ,
- except more verbose.
- .It debug, 48
- Show everything, including debugging information.
- .It trace, 56
- .El
- .Pp
- For example to enable repeated log output, add the
- .Li level
- prefix, and set
- .Va loglevel
- to
- .Li verbose :
- .Bd -literal -offset indent
- ffmpeg -loglevel repeat+level+verbose -i input output
- .Ed
- Another example that enables repeated log output without affecting current
- state of
- .Li level
- prefix flag or
- .Va loglevel :
- .Bd -literal -offset indent
- ffmpeg [...] -loglevel +repeat
- .Ed
- .Pp
- By default the program logs to stderr. If coloring is supported by the terminal,
- colors are used to mark errors and warnings. Log coloring can be disabled
- setting the environment variable
- .Ev AV_LOG_FORCE_NOCOLOR ,
- or can be forced setting the environment variable
- .Ev AV_LOG_FORCE_COLOR .
- .Pp
- .It -report
- Dump full command line and log output to a file named
- .Li Va program- Va YYYYMMDD- Va HHMMSS.log
- in the current directory. This file can be useful for bug reports. It also
- implies
- .Li -loglevel debug .
- .Pp
- Setting the environment variable
- .Ev FFREPORT
- to any value has the same effect. If the value is a ':'-separated key=value
- sequence, these options will affect the report; option values must be escaped
- if they contain special characters or the options delimiter ':' (see the \(lqQuoting
- and escaping\(rq section in the ffmpeg-utils manual).
- .Pp
- The following options are recognized:
- .Bl -tag -width Ds
- .It file
- set the file name to use for the report;
- .Li %p
- is expanded to the name of the program,
- .Li %t
- is expanded to a timestamp,
- .Li %%
- is expanded to a plain
- .Li %
- .It level
- set the log verbosity level using a numerical value (see
- .Li -loglevel ) .
- .El
- .Pp
- For example, to output a report to a file named
- .Pa ffreport.log
- using a log level of
- .Li 32
- (alias for log level
- .Li info ) :
- .Pp
- .Bd -literal -offset indent
- FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
- .Ed
- .Pp
- Errors in parsing the environment variable are not fatal, and will not appear
- in the report.
- .Pp
- .It -hide_banner
- Suppress printing banner.
- .Pp
- All FFmpeg tools will normally show a copyright notice, build options and
- library versions. This option can be used to suppress printing this information.
- .Pp
- .It -cpuflags flags ( Em global)
- Allows setting and clearing cpu flags. This option is intended for testing.
- Do not use it unless you know what you're doing.
- .Bd -literal -offset indent
- ffmpeg -cpuflags -sse+mmx ...
- ffmpeg -cpuflags mmx ...
- ffmpeg -cpuflags 0 ...
- .Ed
- Possible flags for this option are:
- .Bl -tag -width Ds
- .It x86
- .Bl -tag -width Ds
- .It mmx
- .It mmxext
- .It sse
- .It sse2
- .It sse2slow
- .It sse3
- .It sse3slow
- .It ssse3
- .It atom
- .It sse4.1
- .It sse4.2
- .It avx
- .It avx2
- .It xop
- .It fma3
- .It fma4
- .It 3dnow
- .It 3dnowext
- .It bmi1
- .It bmi2
- .It cmov
- .El
- .It ARM
- .Bl -tag -width Ds
- .It armv5te
- .It armv6
- .It armv6t2
- .It vfp
- .It vfpv3
- .It neon
- .It setend
- .El
- .It AArch64
- .Bl -tag -width Ds
- .It armv8
- .It vfp
- .It neon
- .El
- .It PowerPC
- .Bl -tag -width Ds
- .It altivec
- .El
- .It Specific Processors
- .Bl -tag -width Ds
- .It pentium2
- .It pentium3
- .It pentium4
- .It k6
- .It k62
- .It athlon
- .It athlonxp
- .It k8
- .El
- .El
- .Pp
- .It -cpucount Va count ( Em global)
- Override detection of CPU count. This option is intended for testing. Do not
- use it unless you know what you're doing.
- .Bd -literal -offset indent
- ffmpeg -cpucount 2
- .Ed
- .Pp
- .It -max_alloc Va bytes
- Set the maximum size limit for allocating a block on the heap by ffmpeg's
- family of malloc functions. Exercise
- .Sy extreme caution
- when using this option. Don't use if you do not understand the full consequence
- of doing so. Default is INT_MAX.
- .El
- .Pp
- .Ss AVOptions
- These options are provided directly by the libavformat, libavdevice and libavcodec
- libraries. To see the list of available AVOptions, use the
- .Op -help
- option. They are separated into two categories:
- .Bl -tag -width Ds
- .It generic
- These options can be set for any container, codec or device. Generic options
- are listed under AVFormatContext options for containers/devices and under
- AVCodecContext options for codecs.
- .It private
- These options are specific to the given container, device or codec. Private
- options are listed under their corresponding containers/devices/codecs.
- .El
- .Pp
- For example to write an ID3v2.3 header instead of a default ID3v2.4 to an
- MP3 file, use the
- .Op id3v2_version
- private option of the MP3 muxer:
- .Bd -literal -offset indent
- ffmpeg -i input.flac -id3v2_version 3 out.mp3
- .Ed
- .Pp
- All codec AVOptions are per-stream, and thus a stream specifier should be
- attached to them:
- .Bd -literal -offset indent
- ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
- .Ed
- .Pp
- In the above example, a multichannel audio stream is mapped twice for output.
- The first instance is encoded with codec ac3 and bitrate 640k. The second
- instance is downmixed to 2 channels and encoded with codec aac. A bitrate
- of 128k is specified for it using absolute index of the output stream.
- .Pp
- Note: the
- .Op -nooption
- syntax cannot be used for boolean AVOptions, use
- .Op -option 0
- /
- .Op -option 1 .
- .Pp
- Note: the old undocumented way of specifying per-stream AVOptions by prepending
- v/a/s to the options name is now obsolete and will be removed soon.
- .Pp
- .Ss Main options
- .Bl -tag -width Ds
- .It -f Va format
- Force format to use.
- .Pp
- .It -unit
- Show the unit of the displayed values.
- .Pp
- .It -prefix
- Use SI prefixes for the displayed values. Unless the "-byte_binary_prefix"
- option is used all the prefixes are decimal.
- .Pp
- .It -byte_binary_prefix
- Force the use of binary prefixes for byte values.
- .Pp
- .It -sexagesimal
- Use sexagesimal format HH:MM:SS.MICROSECONDS for time values.
- .Pp
- .It -pretty
- Prettify the format of the displayed values, it corresponds to the options
- "-unit -prefix -byte_binary_prefix -sexagesimal".
- .Pp
- .It -output_format, -of, -print_format Va writer_name[= Va writer_options]
- Set the output printing format.
- .Pp
- .Va writer_name
- specifies the name of the writer, and
- .Va writer_options
- specifies the options to be passed to the writer.
- .Pp
- For example for printing the output in JSON format, specify:
- .Bd -literal -offset indent
- -output_format json
- .Ed
- .Pp
- For more details on the available output printing formats, see the Writers
- section below.
- .Pp
- .It -sections
- Print sections structure and section information, and exit. The output is
- not meant to be parsed by a machine.
- .Pp
- .It -select_streams Va stream_specifier
- Select only the streams specified by
- .Va stream_specifier .
- This option affects only the options related to streams (e.g.
- .Li show_streams ,
- .Li show_packets ,
- etc.).
- .Pp
- For example to show only audio streams, you can use the command:
- .Bd -literal -offset indent
- ffprobe -show_streams -select_streams a INPUT
- .Ed
- .Pp
- To show only video packets belonging to the video stream with index 1:
- .Bd -literal -offset indent
- ffprobe -show_packets -select_streams v:1 INPUT
- .Ed
- .Pp
- .It -show_data
- Show payload data, as a hexadecimal and ASCII dump. Coupled with
- .Op -show_packets ,
- it will dump the packets' data. Coupled with
- .Op -show_streams ,
- it will dump the codec extradata.
- .Pp
- The dump is printed as the "data" field. It may contain newlines.
- .Pp
- .It -show_data_hash Va algorithm
- Show a hash of payload data, for packets with
- .Op -show_packets
- and for codec extradata with
- .Op -show_streams .
- .Pp
- .It -show_error
- Show information about the error found when trying to probe the input.
- .Pp
- The error information is printed within a section with name "ERROR".
- .Pp
- .It -show_format
- Show information about the container format of the input multimedia stream.
- .Pp
- All the container format information is printed within a section with name
- "FORMAT".
- .Pp
- .It -show_format_entry Va name
- Like
- .Op -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.
- .Pp
- This option is deprecated, use
- .Li show_entries
- instead.
- .Pp
- .It -show_entries Va section_entries
- Set list of entries to show.
- .Pp
- Entries are specified according to the following syntax.
- .Va section_entries
- contains a list of section entries separated by
- .Li : .
- 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
- .Li , .
- .Pp
- If section name is specified but is followed by no
- .Li = ,
- 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
- .Li =
- is specified but the list of local entries is empty, then no entries will
- be shown for that section.
- .Pp
- 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.
- .Pp
- The formal syntax is given by:
- .Bd -literal -offset indent
- LOCAL_SECTION_ENTRIES ::= SECTION_ENTRY_NAME[,LOCAL_SECTION_ENTRIES]
- SECTION_ENTRY ::= SECTION_NAME[=[LOCAL_SECTION_ENTRIES]]
- SECTION_ENTRIES ::= SECTION_ENTRY[:SECTION_ENTRIES]
- .Ed
- .Pp
- 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:
- .Bd -literal -offset indent
- packet=pts_time,duration_time,stream_index : stream=index,codec_type
- .Ed
- .Pp
- To show all the entries in the section "format", but only the codec type in
- the section "stream", specify the argument:
- .Bd -literal -offset indent
- format : stream=codec_type
- .Ed
- .Pp
- To show all the tags in the stream and format sections:
- .Bd -literal -offset indent
- stream_tags : format_tags
- .Ed
- .Pp
- To show only the
- .Li title
- tag (if available) in the stream sections:
- .Bd -literal -offset indent
- stream_tags=title
- .Ed
- .Pp
- .It -show_packets
- Show information about each packet contained in the input multimedia stream.
- .Pp
- The information for each single packet is printed within a dedicated section
- with name "PACKET".
- .Pp
- .It -show_frames
- Show information about each frame and subtitle contained in the input multimedia
- stream.
- .Pp
- The information for each single frame is printed within a dedicated section
- with name "FRAME" or "SUBTITLE".
- .Pp
- .It -show_log Va loglevel
- Show logging information from the decoder about each frame according to the
- value set in
- .Va loglevel ,
- (see
- .Li -loglevel ) .
- This option requires
- .Li -show_frames .
- .Pp
- The information for each log message is printed within a dedicated section
- with name "LOG".
- .Pp
- .It -show_streams
- Show information about each media stream contained in the input multimedia
- stream.
- .Pp
- Each media stream information is printed within a dedicated section with name
- "STREAM".
- .Pp
- .It -show_programs
- Show information about programs and their streams contained in the input multimedia
- stream.
- .Pp
- Each media stream information is printed within a dedicated section with name
- "PROGRAM_STREAM".
- .Pp
- .It -show_stream_groups
- Show information about stream groups and their streams contained in the input
- multimedia stream.
- .Pp
- Each media stream information is printed within a dedicated section with name
- "STREAM_GROUP_STREAM".
- .Pp
- .It -show_chapters
- Show information about chapters stored in the format.
- .Pp
- Each chapter is printed within a dedicated section with name "CHAPTER".
- .Pp
- .It -count_frames
- Count the number of frames per stream and report it in the corresponding stream
- section.
- .Pp
- .It -count_packets
- Count the number of packets per stream and report it in the corresponding
- stream section.
- .Pp
- .It -read_intervals Va read_intervals
- .Pp
- Read only the specified intervals.
- .Va read_intervals
- must be a sequence of interval specifications separated by ",".
- .Xr ffprobe
- will seek to the interval starting point, and will continue reading from that.
- .Pp
- Each interval is specified by two optional parts, separated by "%".
- .Pp
- The first part specifies the interval start 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 this first part is not specified,
- no seeking will be performed when reading this interval.
- .Pp
- 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.
- .Pp
- 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.
- .Pp
- The formal syntax is given by:
- .Bd -literal -offset indent
- INTERVAL ::= [START|+START_OFFSET][%[END|+END_OFFSET]]
- INTERVALS ::= INTERVAL[,INTERVALS]
- .Ed
- .Pp
- A few examples follow.
- .Bl -bullet
- .It
- Seek to time 10, read packets until 20 seconds after the found seek point,
- then seek to position
- .Li 01:30
- (1 minute and thirty seconds) and read packets until position
- .Li 01:45 .
- .Bd -literal -offset indent
- 10%+20,01:30%01:45
- .Ed
- .Pp
- .It
- Read only 42 packets after seeking to position
- .Li 01:23 :
- .Bd -literal -offset indent
- 01:23%+#42
- .Ed
- .Pp
- .It
- Read only the first 20 seconds from the start:
- .Bd -literal -offset indent
- %+20
- .Ed
- .Pp
- .It
- Read from the start until position
- .Li 02:30 :
- .Bd -literal -offset indent
- %02:30
- .Ed
- .El
- .Pp
- .It -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.
- .Pp
- .It -show_program_version
- Show information related to program version.
- .Pp
- Version information is printed within a section with name "PROGRAM_VERSION".
- .Pp
- .It -show_library_versions
- Show information related to library versions.
- .Pp
- Version information for each library is printed within a section with name
- "LIBRARY_VERSION".
- .Pp
- .It -show_versions
- Show information related to program and library versions. This is the equivalent
- of setting both
- .Op -show_program_version
- and
- .Op -show_library_versions
- options.
- .Pp
- .It -show_pixel_formats
- Show information about all pixel formats supported by FFmpeg.
- .Pp
- Pixel format information for each format is printed within a section with
- name "PIXEL_FORMAT".
- .Pp
- .It -show_optional_fields Va value
- Some writers viz. JSON and XML, omit the printing of fields with invalid or
- non-applicable values, while other writers always print them. This option
- enables one to control this behaviour. Valid values are
- .Li always
- /
- .Li 1 ,
- .Li never
- /
- .Li 0
- and
- .Li auto
- /
- .Li -1 .
- Default is
- .Va auto .
- .Pp
- .It -bitexact
- Force bitexact output, useful to produce output which is not dependent on
- the specific build.
- .Pp
- .It -i Va input_url
- Read
- .Va input_url .
- .Pp
- .It -o Va output_url
- Write output to
- .Va output_url .
- If not specified, the output is sent to stdout.
- .Pp
- .El
- .Sh Writers
- A writer defines the output format adopted by
- .Xr ffprobe ,
- and will be used for printing all the parts of the output.
- .Pp
- A writer may accept one or more arguments, which specify the options to adopt.
- The options are specified as a list of
- .Va key
- =
- .Va value
- pairs, separated by ":".
- .Pp
- All writers support the following options:
- .Pp
- .Bl -tag -width Ds
- .It string_validation, sv
- Set string validation mode.
- .Pp
- The following values are accepted.
- .Bl -tag -width Ds
- .It 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.
- .Pp
- .It ignore
- Any validation error will be ignored. This will result in possibly broken
- output, especially with the json or xml writer.
- .Pp
- .It replace
- The writer will substitute invalid UTF-8 sequences or code points with the
- string specified with the
- .Op string_validation_replacement .
- .El
- .Pp
- Default value is
- .Li replace .
- .Pp
- .It string_validation_replacement, svr
- Set replacement string to use in case
- .Op string_validation
- is set to
- .Li replace .
- .Pp
- 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.
- .El
- .Pp
- A description of the currently available writers follows.
- .Pp
- .Ss default
- Default format.
- .Pp
- Print each section in the form:
- .Bd -literal -offset indent
- [SECTION]
- key1=val1
- \&...
- keyN=valN
- [/SECTION]
- .Ed
- .Pp
- Metadata tags are printed as a line in the corresponding FORMAT, STREAM, STREAM_GROUP_STREAM
- or PROGRAM_STREAM section, and are prefixed by the string "TAG:".
- .Pp
- A description of the accepted options follows.
- .Pp
- .Bl -tag -width Ds
- .It nokey, nk
- If set to 1 specify not to print the key of each field. Default value is 0.
- .Pp
- .It noprint_wrappers, nw
- If set to 1 specify not to print the section header and footer. Default value
- is 0.
- .El
- .Pp
- .Ss compact, csv
- Compact and CSV format.
- .Pp
- The
- .Li csv
- writer is equivalent to
- .Li compact ,
- but supports different defaults.
- .Pp
- Each section is printed on a single line. If no option is specified, the output
- has the form:
- .Bd -literal -offset indent
- section|key1=val1| ... |keyN=valN
- .Ed
- .Pp
- Metadata tags are printed in the corresponding "format" or "stream" section.
- A metadata tag key, if printed, is prefixed by the string "tag:".
- .Pp
- The description of the accepted options follows.
- .Pp
- .Bl -tag -width Ds
- .It 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
- .Li csv
- writer).
- .Pp
- .It nokey, nk
- If set to 1 specify not to print the key of each field. Its default value
- is 0 (1 for the
- .Li csv
- writer).
- .Pp
- .It escape, e
- Set the escape mode to use, default to "c" ("csv" for the
- .Li csv
- writer).
- .Pp
- It can assume one of the following values:
- .Bl -tag -width Ds
- .It c
- Perform C-like escaping. Strings containing a newline (
- .Li \en ) ,
- carriage return (
- .Li \er ) ,
- a tab (
- .Li \et ) ,
- a form feed (
- .Li \ef ) ,
- the escaping character (
- .Li \e )
- or the item separator character
- .Va SEP
- are escaped using C-like fashioned escaping, so that a newline is converted
- to the sequence
- .Li \en ,
- a carriage return to
- .Li \er ,
- .Li \e
- to
- .Li \e\e
- and the separator
- .Va SEP
- is converted to
- .Li \e Va SEP .
- .Pp
- .It csv
- Perform CSV-like escaping, as described in RFC4180. Strings containing a newline
- (
- .Li \en ) ,
- a carriage return (
- .Li \er ) ,
- a double quote (
- .Li " ) ,
- or
- .Va SEP
- are enclosed in double-quotes.
- .Pp
- .It none
- Perform no escaping.
- .El
- .Pp
- .It print_section, p
- Print the section name at the beginning of each line if the value is
- .Li 1 ,
- disable it with value set to
- .Li 0 .
- Default value is
- .Li 1 .
- .Pp
- .El
- .Ss flat
- Flat format.
- .Pp
- 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
- .Va sep_char
- option).
- .Pp
- The description of the accepted options follows.
- .Pp
- .Bl -tag -width Ds
- .It sep_char, s
- Separator character used to separate the chapter, the section name, IDs and
- potential tags in the printed field key.
- .Pp
- Default value is
- .Li . .
- .Pp
- .It 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.
- .Pp
- Default value is 1.
- .El
- .Pp
- .Ss ini
- INI format output.
- .Pp
- Print output in an INI based format.
- .Pp
- The following conventions are adopted:
- .Pp
- .Bl -bullet
- .It
- all key and values are UTF-8
- .It
- .Li .
- is the subgroup separator
- .It
- newline,
- .Li \et ,
- .Li \ef ,
- .Li \eb
- and the following characters are escaped
- .It
- .Li \e
- is the escape character
- .It
- .Li #
- is the comment indicator
- .It
- .Li =
- is the key/value separator
- .It
- .Li :
- is not used but usually parsed as key/value separator
- .El
- .Pp
- This writer accepts options as a list of
- .Va key
- =
- .Va value
- pairs, separated by
- .Li : .
- .Pp
- The description of the accepted options follows.
- .Pp
- .Bl -tag -width Ds
- .It 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.
- .Pp
- Default value is 1.
- .El
- .Pp
- .Ss json
- JSON based format.
- .Pp
- Each section is printed using JSON notation.
- .Pp
- The description of the accepted options follows.
- .Pp
- .Bl -tag -width Ds
- .It compact, c
- If set to 1 enable compact output, that is each section will be printed on
- a single line. Default value is 0.
- .El
- .Pp
- For more information about JSON, see
- .Lk http://www.json.org/ .
- .Pp
- .Ss xml
- XML based format.
- .Pp
- The XML output is described in the XML schema description file
- .Pa ffprobe.xsd
- installed in the FFmpeg datadir.
- .Pp
- An updated version of the schema can be retrieved at the url
- .Lk http://www.ffmpeg.org/schema/ffprobe.xsd ,
- which redirects to the latest schema committed into the FFmpeg development
- source code tree.
- .Pp
- Note that the output issued will be compliant to the
- .Pa ffprobe.xsd
- schema only when no special global output options (
- .Op unit ,
- .Op prefix ,
- .Op byte_binary_prefix ,
- .Op sexagesimal
- etc.) are specified.
- .Pp
- The description of the accepted options follows.
- .Pp
- .Bl -tag -width Ds
- .It 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.
- .Pp
- .It xsd_strict, x
- If set to 1 perform more checks for ensuring that the output is XSD compliant.
- Default value is 0. This option automatically sets
- .Op fully_qualified
- to 1.
- .El
- .Pp
- For more information about the XML format, see
- .Lk https://www.w3.org/XML/ .
- .Pp
- .Sh Timecode
- .Xr ffprobe
- supports Timecode extraction:
- .Pp
- .Bl -bullet
- .It
- MPEG1/2 timecode is extracted from the GOP, and is available in the video
- stream details (
- .Op -show_streams ,
- see
- .Va timecode ) .
- .Pp
- .It
- MOV timecode is extracted from tmcd track, so is available in the tmcd stream
- metadata (
- .Op -show_streams ,
- see
- .Va TAG:timecode ) .
- .Pp
- .It
- DV, GXF and AVI timecodes are available in format metadata (
- .Op -show_format ,
- see
- .Va TAG:timecode ) .
- .Pp
- .El
- .Sh See Also
- ffmpeg(1), ffplay(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)
- .Pp
- .Sh Authors
- The FFmpeg developers.
- .Pp
- For details about the authorship, see the Git history of the project (https://git.ffmpeg.org/ffmpeg),
- e.g. by typing the command
- .Xr git log
- in the FFmpeg source directory, or browsing the online repository at
- .Lk https://git.ffmpeg.org/ffmpeg .
- .Pp
- Maintainers for the specific components are listed in the file
- .Pa MAINTAINERS
- in the source code tree.
- .Pp