ffprobe Documentation

Table of Contents

1 Synopsis

ffprobe [options] input_url

2 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 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.

If no output is specified as output with o ffprobe will write to stdout.

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 output_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 sections.

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.

3 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’.

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.

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.

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.

ffmpeg -i INPUT -/filter:v filter.script OUTPUT

will load a filtergraph description from the file named filter.script.

3.1 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.

A stream specifier is a string generally appended to the option name and separated from it by a colon. E.g. -codec:a:1 ac3 contains the a:1 stream specifier, which matches the second audio stream. Therefore, it would select the ac3 codec for the second audio stream.

A stream specifier can match several streams, so that the option is applied to all of them. E.g. the stream specifier in -b:a 128k matches all audio streams.

An empty stream specifier matches all streams. For example, -codec copy or -codec: copy would copy all the streams without reencoding.

Possible forms of stream specifiers are:

stream_index

Matches the stream with this index. E.g. -threads:1 4 would set the thread count for the second stream to 4. If stream_index is used as an additional stream specifier (see below), then it selects stream number 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.

stream_type[:additional_stream_specifier]

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 additional_stream_specifier is used, then it matches streams which both have this type and match the additional_stream_specifier. Otherwise, it matches all streams of the specified type.

g:group_specifier[:additional_stream_specifier]

Matches streams which are in the group with the specifier group_specifier. if additional_stream_specifier is used, then it matches streams which both are part of the group and match the additional_stream_specifier. group_specifier may be one of the following:

group_index

Match the stream with this group index.

#group_id or i:group_id

Match the stream with this group id.

p:program_id[:additional_stream_specifier]

Matches streams which are in the program with the id program_id. If additional_stream_specifier is used, then it matches streams which both are part of the program and match the additional_stream_specifier.

#stream_id or i:stream_id

Match the stream by stream id (e.g. PID in MPEG-TS container).

m:key[:value]

Matches streams with the metadata tag key having the specified value. If value is not given, matches streams that contain the given tag with any value. The colon character ’:’ in key or value needs to be backslash-escaped.

disp:dispositions[:additional_stream_specifier]

Matches streams with the given disposition(s). dispositions is a list of one or more dispositions (as printed by the -dispositions option) joined with ’+’.

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.

Note that in ffmpeg, matching by metadata will only work properly for input files.

3.2 Generic options

These options are shared amongst the ff* tools.

-L, -license

Show license.

-h, -?, -help, --help [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.

Possible values of arg are:

long

Print advanced tool options in addition to the basic tool options.

full

Print complete list of options, including shared and private options for encoders, decoders, demuxers, muxers, filters, etc.

decoder=decoder_name

Print detailed information about the decoder named decoder_name. Use the -decoders option to get a list of all decoders.

encoder=encoder_name

Print detailed information about the encoder named encoder_name. Use the -encoders option to get a list of all encoders.

demuxer=demuxer_name

Print detailed information about the demuxer named demuxer_name. Use the -formats option to get a list of all demuxers and muxers.

muxer=muxer_name

Print detailed information about the muxer named muxer_name. Use the -formats option to get a list of all muxers and demuxers.

filter=filter_name

Print detailed information about the filter named filter_name. Use the -filters option to get a list of all filters.

bsf=bitstream_filter_name

Print detailed information about the bitstream filter named bitstream_filter_name. Use the -bsfs option to get a list of all bitstream filters.

protocol=protocol_name

Print detailed information about the protocol named protocol_name. Use the -protocols option to get a list of all protocols.

-version

Show version.

-buildconf

Show the build configuration, one option per line.

-formats

Show available formats (including devices).

-demuxers

Show available demuxers.

-muxers

Show available muxers.

-devices

Show available devices.

-codecs

Show all codecs known to libavcodec.

Note that the term ’codec’ is used throughout this documentation as a shortcut for what is more correctly called a media bitstream format.

-decoders

Show available decoders.

-encoders

Show all available encoders.

-bsfs

Show available bitstream filters.

-protocols

Show available protocols.

-filters

Show available libavfilter filters.

-pix_fmts

Show available pixel formats.

-sample_fmts

Show available sample formats.

-layouts

Show channel names and standard channel layouts.

-dispositions

Show stream dispositions.

-colors

Show recognized color names.

-sources device[,opt1=val1[,opt2=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.

ffmpeg -sources pulse,server=192.168.0.4

-sinks device[,opt1=val1[,opt2=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.

ffmpeg -sinks pulse,server=192.168.0.4

-loglevel [flags+]loglevel | -v [flags+]loglevel

Set logging level and flags used by the library.

The optional flags prefix can consist of the following values:

‘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.

‘level’

Indicates that log output should add a [level] prefix to each message line. This can be used as an alternative to log coloring, e.g. when dumping the log to file.

‘time’

Indicates that log lines should be prefixed with time information.

‘datetime’

Indicates that log lines should be prefixed with date and time information.

Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single flag without affecting other flags or changing loglevel. When setting both flags and loglevel, a ’+’ separator is expected between the last flags value and before loglevel.

loglevel is a string or a number containing one of the following values:

‘quiet, -8’

Show nothing at all; be silent.

‘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.

‘fatal, 8’

Only show fatal errors. These are errors after which the process absolutely cannot continue.

‘error, 16’

Show all errors, including ones which can be recovered from.

‘warning, 24’

Show all warnings and errors. Any message related to possibly incorrect or unexpected events will be shown.

‘info, 32’

Show informative messages during processing. This is in addition to warnings and errors. This is the default value.

‘verbose, 40’

Same as info, except more verbose.

‘debug, 48’

Show everything, including debugging information.

‘trace, 56’

For example to enable repeated log output, add the level prefix, and set loglevel to verbose:

ffmpeg -loglevel repeat+level+verbose -i input output

Another example that enables repeated log output without affecting current state of level prefix flag or loglevel:

ffmpeg [...] -loglevel +repeat

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 AV_LOG_FORCE_NOCOLOR, or can be forced setting the environment variable AV_LOG_FORCE_COLOR.

-report

Dump full command line and log output to a file named program-YYYYMMDD-HHMMSS.log in the current directory. This file can be useful for bug reports. It also implies -loglevel debug.

Setting the environment variable 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 “Quoting and escaping” section in the ffmpeg-utils manual).

The following options are recognized:

file

set the file name to use for the report; %p is expanded to the name of the program, %t is expanded to a timestamp, %% is expanded to a plain %

level

set the log verbosity level using a numerical value (see -loglevel).

For example, to output a report to a file named ffreport.log using a log level of 32 (alias for log level info):

FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output

Errors in parsing the environment variable are not fatal, and will not appear in the report.

-hide_banner

Suppress printing banner.

All FFmpeg tools will normally show a copyright notice, build options and library versions. This option can be used to suppress printing this information.

-cpuflags flags (global)

Allows setting and clearing cpu flags. This option is intended for testing. Do not use it unless you know what you’re doing.

ffmpeg -cpuflags -sse+mmx ...
ffmpeg -cpuflags mmx ...
ffmpeg -cpuflags 0 ...

Possible flags for this option are:

‘x86’

‘mmx’

‘mmxext’

‘sse’

‘sse2’

‘sse2slow’

‘sse3’

‘sse3slow’

‘ssse3’

‘atom’

‘sse4.1’

‘sse4.2’

‘avx’

‘avx2’

‘xop’

‘fma3’

‘fma4’

‘3dnow’

‘3dnowext’

‘bmi1’

‘bmi2’

‘cmov’

‘ARM’

‘armv5te’

‘armv6’

‘armv6t2’

‘vfp’

‘vfpv3’

‘neon’

‘setend’

‘AArch64’

‘armv8’

‘vfp’

‘neon’

‘PowerPC’

‘altivec’

‘Specific Processors’

‘pentium2’

‘pentium3’

‘pentium4’

‘k6’

‘k62’

‘athlon’

‘athlonxp’

‘k8’

-cpucount count (global)

Override detection of CPU count. This option is intended for testing. Do not use it unless you know what you’re doing.

ffmpeg -cpucount 2

-max_alloc bytes

Set the maximum size limit for allocating a block on the heap by ffmpeg’s family of malloc functions. Exercise extreme caution when using this option. Don’t use if you do not understand the full consequence of doing so. Default is INT_MAX.

3.3 AVOptions

These options are provided directly by the libavformat, libavdevice and libavcodec libraries. To see the list of available AVOptions, use the -help option. They are separated into two categories:

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.

private

These options are specific to the given container, device or codec. Private options are listed under their corresponding containers/devices/codecs.

For example to write an ID3v2.3 header instead of a default ID3v2.4 to an MP3 file, use the id3v2_version private option of the MP3 muxer:

ffmpeg -i input.flac -id3v2_version 3 out.mp3

All codec AVOptions are per-stream, and thus a stream specifier should be attached to them:

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

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.

Note: the -nooption syntax cannot be used for boolean AVOptions, use -option 0/-option 1.

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.

3.4 Main options

-f format

Force format to use.

-unit

Show the unit of the displayed values.

-prefix

Use SI prefixes for the displayed values. Unless the "-byte_binary_prefix" option is used all the prefixes are decimal.

-byte_binary_prefix

Force the use of binary prefixes for byte values.

-sexagesimal

Use sexagesimal format HH:MM:SS.MICROSECONDS for time values.

-pretty

Prettify the format of the displayed values, it corresponds to the options "-unit -prefix -byte_binary_prefix -sexagesimal".

-output_format, -of, -print_format writer_name[=writer_options]

Set the output printing format.

writer_name specifies the name of the writer, and writer_options specifies the options to be passed to the writer.

For example for printing the output in JSON format, specify:

-output_format json

For more details on the available output printing formats, see the Writers section below.

-sections

Print sections structure and section information, and exit. The output is not meant to be parsed by a machine.

-select_streams stream_specifier

Select only the streams specified by stream_specifier. This option affects only the options related to streams (e.g. show_streams, show_packets, etc.).

For example to show only audio streams, you can use the command:

ffprobe -show_streams -select_streams a INPUT

To show only video packets belonging to the video stream with index 1:

ffprobe -show_packets -select_streams v:1 INPUT

-show_data

Show payload data, as a hexadecimal and ASCII dump (other formats can be selected using -data_dump_format). Coupled with -show_packets, it will dump the packets’ data. Coupled with -show_streams, it will dump the codec extradata.

The dump is printed as the "data" field. It may contain newlines.

-show_data_hash algorithm

Show a hash of payload data, for packets with -show_packets and for codec extradata with -show_streams.

-data_dump_format format

Select a format used for the data dumps enabled with the -show_data option. The default is xxd which is a hexdump format compatible with the well-known xxd program. base64 is also supported.

-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".

-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".

-show_entries section_entries

Set list of entries to show.

Entries are specified according to the following syntax. section_entries contains a list of section entries separated by :. 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 ,.

If section name is specified but is followed by no =, 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 = 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:

LOCAL_SECTION_ENTRIES ::= SECTION_ENTRY_NAME[,LOCAL_SECTION_ENTRIES]
SECTION_ENTRY         ::= SECTION_NAME[=[LOCAL_SECTION_ENTRIES]]
SECTION_ENTRIES       ::= SECTION_ENTRY[:SECTION_ENTRIES]

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:

packet=pts_time,duration_time,stream_index : stream=index,codec_type

To show all the entries in the section "format", but only the codec type in the section "stream", specify the argument:

format : stream=codec_type

To show all the tags in the stream and format sections:

stream_tags : format_tags

To show only the title tag (if available) in the stream sections:

stream_tags=title

-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".

-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".

-show_log loglevel

Show logging information from the decoder about each frame according to the value set in loglevel, (see -loglevel). This option requires -show_frames.

The information for each log message is printed within a dedicated section with name "LOG".

-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".

-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".

-show_stream_groups

Show information about stream groups and their streams contained in the input multimedia stream.

Each media stream information is printed within a dedicated section with name "STREAM_GROUP_STREAM".

-show_chapters

Show information about chapters stored in the format.

Each chapter is printed within a dedicated section with name "CHAPTER".

-count_frames

Count the number of frames per stream and report it in the corresponding stream section.

-count_packets

Count the number of packets per stream and report it in the corresponding stream section.

-read_intervals read_intervals

Read only the specified intervals. read_intervals must be a sequence of interval specifications separated by ",". 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 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.

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:

INTERVAL  ::= [START|+START_OFFSET][%[END|+END_OFFSET]]
INTERVALS ::= INTERVAL[,INTERVALS]

A few examples follow.

• Seek to time 10, read packets until 20 seconds after the found seek point, then seek to position 01:30 (1 minute and thirty seconds) and read packets until position 01:45.

  10%+20,01:30%01:45
  

• Read only 42 packets after seeking to position 01:23:

  01:23%+#42
  

• Read only the first 20 seconds from the start:

  %+20
  

• Read from the start until position 02:30:

  %02:30
  

-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.

-show_program_version

Show information related to program version.

Version information is printed within a section with name "PROGRAM_VERSION".

-show_library_versions

Show information related to library versions.

Version information for each library is printed within a section with name "LIBRARY_VERSION".

-show_versions

Show information related to program and library versions. This is the equivalent of setting both -show_program_version and -show_library_versions options.

-show_pixel_formats

Show information about all pixel formats supported by FFmpeg.

Pixel format information for each format is printed within a section with name "PIXEL_FORMAT".

-show_optional_fields 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 always/1, never/0 and auto/-1. Default is auto.

-analyze_frames

Analyze frames and/or their side data up to the provided read interval, providing additional information that may be useful at a stream level. Must be paired with the -show_streams option or it will have no effect.

Currently, the additional fields provided by this option when enabled are the closed_captions and film_grain fields.

For example, to analyze the first 20 seconds and populate these fields:

ffprobe -show_streams -analyze_frames -read_intervals "%+20" INPUT

-bitexact

Force bitexact output, useful to produce output which is not dependent on the specific build.

-i input_url

Read input_url.

-o output_url

Write output to output_url. If not specified, the output is sent to stdout.

-c:media_specifier codec_name

-codec:media_specifier codec_name

Force a specific decoder implementation for the stream identified by media_specifier, which can assume the values a (audio), v (video), s (subtitle), and d (data).

4 Writers

A writer defines the output format adopted by 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 key=value pairs, separated by ":".

All writers support the following options:

string_validation, sv

Set string validation mode.

The following values are accepted.

‘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.

‘ignore’

Any validation error will be ignored. This will result in possibly broken output, especially with the json or xml writer.

‘replace’

The writer will substitute invalid UTF-8 sequences or code points with the string specified with the string_validation_replacement.

Default value is ‘replace’.

string_validation_replacement, svr

Set replacement string to use in case string_validation is set to ‘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.

A description of the currently available writers follows.

4.1 default

Default format.

Print each section in the form:

[SECTION]
key1=val1
...
keyN=valN
[/SECTION]

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:".

A description of the accepted options follows.

nokey, nk

If set to 1 specify not to print the key of each field. Default value is 0.

noprint_wrappers, nw

If set to 1 specify not to print the section header and footer. Default value is 0.

4.2 compact, csv

Compact and CSV format.

The csv writer is equivalent to compact, but supports different defaults.

Each section is printed on a single line. If no option is specified, the output has the form:

section|key1=val1| ... |keyN=valN

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.

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 csv writer).

nokey, nk

If set to 1 specify not to print the key of each field. Its default value is 0 (1 for the csv writer).

escape, e

Set the escape mode to use, default to "c" ("csv" for the csv writer).

It can assume one of the following values:

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 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 SEP is converted to ‘\SEP’.

csv

Perform CSV-like escaping, as described in RFC4180. Strings containing a newline (‘\n’), a carriage return (‘\r’), a double quote (‘"’), or SEP are enclosed in double-quotes.

none

Perform no escaping.

print_section, p

Print the section name at the beginning of each line if the value is 1, disable it with value set to 0. Default value is 1.

4.3 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 sep_char option).

The description of the accepted options follows.

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 ‘.’.

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.

4.4 ini

INI format output.

Print output in an INI based format.

The following conventions are adopted:

• all key and values are UTF-8
• ‘.’ is the subgroup separator
• newline, ‘\t’, ‘\f’, ‘\b’ and the following characters are escaped
• ‘\’ is the escape character
• ‘#’ is the comment indicator
• ‘=’ is the key/value separator
• ‘:’ is not used but usually parsed as key/value separator

This writer accepts options as a list of key=value pairs, separated by ‘:’.

The description of the accepted options follows.

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.

4.5 json

JSON based format.

Each section is printed using JSON notation.

The description of the accepted options follows.

compact, c

If set to 1 enable compact output, that is each section will be printed on a single line. Default value is 0.

For more information about JSON, see http://www.json.org/.

4.6 xml

XML based format.

The XML output is described in the XML schema description file ffprobe.xsd installed in the FFmpeg datadir.

An updated version of the schema can be retrieved at the 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 ffprobe.xsd schema only when no special global output options (unit, prefix, byte_binary_prefix, sexagesimal etc.) are specified.

The description of the accepted options follows.

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.

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 fully_qualified to 1.

For more information about the XML format, see https://www.w3.org/XML/.

5 Timecode

ffprobe supports Timecode extraction:

• MPEG1/2 timecode is extracted from the GOP, and is available in the video stream details (-show_streams, see timecode).
• MOV timecode is extracted from tmcd track, so is available in the tmcd stream metadata (-show_streams, see TAG:timecode).
• DV, GXF and AVI timecodes are available in format metadata (-show_format, see TAG:timecode).

6 Syntax

This section documents the syntax and formats employed by the FFmpeg libraries and tools.

6.1 Quoting and escaping

FFmpeg adopts the following quoting and escaping mechanism, unless explicitly specified. The following rules are applied:

• ‘'’ and ‘\’ are special characters (respectively used for quoting and escaping). In addition to them, there might be other special characters depending on the specific syntax where the escaping and quoting are employed.
• A special character is escaped by prefixing it with a ‘\’.
• All characters enclosed between ‘''’ are included literally in the parsed string. The quote character ‘'’ itself cannot be quoted, so you may need to close the quote and escape it.
• Leading and trailing whitespaces, unless escaped or quoted, are removed from the parsed string.

Note that you may need to add a second level of escaping when using the command line or a script, which depends on the syntax of the adopted shell language.

The function av_get_token defined in libavutil/avstring.h can be used to parse a token quoted or escaped according to the rules defined above.

The tool tools/ffescape in the FFmpeg source tree can be used to automatically quote or escape a string in a script.

6.1.1 Examples

• Escape the string Crime d'Amour containing the ' special character:

  Crime d\'Amour
  

• The string above contains a quote, so the ' needs to be escaped when quoting it:

  'Crime d'\''Amour'
  

• Include leading or trailing whitespaces using quoting:

  '  this string starts and ends with whitespaces  '
  

• Escaping and quoting can be mixed together:

  ' The string '\'string\'' is a string '
  

• To include a literal ‘\’ you can use either escaping or quoting:

  'c:\foo' can be written as c:\\foo
  

6.2 Date

The accepted syntax is:

[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
now

If the value is "now" it takes the current time.

Time is local time unless Z is appended, in which case it is interpreted as UTC. If the year-month-day part is not specified it takes the current year-month-day.

6.3 Time duration

There are two accepted syntaxes for expressing time duration.

[-][HH:]MM:SS[.m...]

HH expresses the number of hours, MM the number of minutes for a maximum of 2 digits, and SS the number of seconds for a maximum of 2 digits. The m at the end expresses decimal value for SS.

or

[-]S+[.m...][s|ms|us]

S expresses the number of seconds, with the optional decimal part m. The optional literal suffixes ‘s’, ‘ms’ or ‘us’ indicate to interpret the value as seconds, milliseconds or microseconds, respectively.

In both expressions, the optional ‘-’ indicates negative duration.

6.3.1 Examples

The following examples are all valid time duration:

‘55’

55 seconds

‘0.2’

0.2 seconds

‘200ms’

200 milliseconds, that’s 0.2s

‘200000us’

200000 microseconds, that’s 0.2s

‘12:03:45’

12 hours, 03 minutes and 45 seconds

‘23.189’

23.189 seconds

6.4 Video size

Specify the size of the sourced video, it may be a string of the form widthxheight, or the name of a size abbreviation.

The following abbreviations are recognized:

‘ntsc’

720x480

‘pal’

720x576

‘qntsc’

352x240

‘qpal’

352x288

‘sntsc’

640x480

‘spal’

768x576

‘film’

352x240

‘ntsc-film’

352x240

‘sqcif’

128x96

‘qcif’

176x144

‘cif’

352x288

‘4cif’

704x576

‘16cif’

1408x1152

‘qqvga’

160x120

‘qvga’

320x240

‘vga’

640x480

‘svga’

800x600

‘xga’

1024x768

‘uxga’

1600x1200

‘qxga’

2048x1536

‘sxga’

1280x1024

‘qsxga’

2560x2048

‘hsxga’

5120x4096

‘wvga’

852x480

‘wxga’

1366x768

‘wsxga’

1600x1024

‘wuxga’

1920x1200

‘woxga’

2560x1600

‘wqsxga’

3200x2048

‘wquxga’

3840x2400

‘whsxga’

6400x4096

‘whuxga’

7680x4800

‘cga’

320x200

‘ega’

640x350

‘hd480’

852x480

‘hd720’

1280x720

‘hd1080’

1920x1080

‘2k’

2048x1080

‘2kflat’

1998x1080

‘2kscope’

2048x858

‘4k’

4096x2160

‘4kflat’

3996x2160

‘4kscope’

4096x1716

‘nhd’

640x360

‘hqvga’

240x160

‘wqvga’

400x240

‘fwqvga’

432x240

‘hvga’

480x320

‘qhd’

960x540

‘2kdci’

2048x1080

‘4kdci’

4096x2160

‘uhd2160’

3840x2160

‘uhd4320’

7680x4320

6.5 Video rate

Specify the frame rate of a video, expressed as the number of frames generated per second. It has to be a string in the format frame_rate_num/frame_rate_den, an integer number, a float number or a valid video frame rate abbreviation.

The following abbreviations are recognized:

‘ntsc’

30000/1001

‘pal’

25/1

‘qntsc’

30000/1001

‘qpal’

25/1

‘sntsc’

30000/1001

‘spal’

25/1

‘film’

24/1

‘ntsc-film’

24000/1001

6.6 Ratio

A ratio can be expressed as an expression, or in the form numerator:denominator.

Note that a ratio with infinite (1/0) or negative value is considered valid, so you should check on the returned value if you want to exclude those values.

The undefined value can be expressed using the "0:0" string.

6.7 Color

It can be the name of a color as defined below (case insensitive match) or a [0x|#]RRGGBB[AA] sequence, possibly followed by @ and a string representing the alpha component.

The alpha component may be a string composed by "0x" followed by an hexadecimal number or a decimal number between 0.0 and 1.0, which represents the opacity value (‘0x00’ or ‘0.0’ means completely transparent, ‘0xff’ or ‘1.0’ completely opaque). If the alpha component is not specified then ‘0xff’ is assumed.

The string ‘random’ will result in a random color.

The following names of colors are recognized:

‘AliceBlue’

0xF0F8FF

‘AntiqueWhite’

0xFAEBD7

‘Aqua’

0x00FFFF

‘Aquamarine’

0x7FFFD4

‘Azure’

0xF0FFFF

‘Beige’

0xF5F5DC

‘Bisque’

0xFFE4C4

‘Black’

0x000000

‘BlanchedAlmond’

0xFFEBCD

‘Blue’

0x0000FF

‘BlueViolet’

0x8A2BE2

‘Brown’

0xA52A2A

‘BurlyWood’

0xDEB887

‘CadetBlue’

0x5F9EA0

‘Chartreuse’

0x7FFF00

‘Chocolate’

0xD2691E

‘Coral’

0xFF7F50

‘CornflowerBlue’

0x6495ED

‘Cornsilk’

0xFFF8DC

‘Crimson’

0xDC143C

‘Cyan’

0x00FFFF

‘DarkBlue’

0x00008B

‘DarkCyan’

0x008B8B

‘DarkGoldenRod’

0xB8860B

‘DarkGray’

0xA9A9A9

‘DarkGreen’

0x006400

‘DarkKhaki’

0xBDB76B

‘DarkMagenta’

0x8B008B

‘DarkOliveGreen’

0x556B2F

‘Darkorange’

0xFF8C00

‘DarkOrchid’

0x9932CC

‘DarkRed’

0x8B0000

‘DarkSalmon’

0xE9967A

‘DarkSeaGreen’

0x8FBC8F

‘DarkSlateBlue’

0x483D8B

‘DarkSlateGray’

0x2F4F4F

‘DarkTurquoise’

0x00CED1

‘DarkViolet’

0x9400D3

‘DeepPink’

0xFF1493

‘DeepSkyBlue’

0x00BFFF

‘DimGray’

0x696969

‘DodgerBlue’

0x1E90FF

‘FireBrick’

0xB22222

‘FloralWhite’

0xFFFAF0

‘ForestGreen’

0x228B22

‘Fuchsia’

0xFF00FF

‘Gainsboro’

0xDCDCDC

‘GhostWhite’

0xF8F8FF

‘Gold’

0xFFD700

‘GoldenRod’

0xDAA520

‘Gray’

0x808080

‘Green’

0x008000

‘GreenYellow’

0xADFF2F

‘HoneyDew’

0xF0FFF0

‘HotPink’

0xFF69B4

‘IndianRed’

0xCD5C5C

‘Indigo’

0x4B0082

‘Ivory’

0xFFFFF0

‘Khaki’

0xF0E68C

‘Lavender’

0xE6E6FA

‘LavenderBlush’

0xFFF0F5

‘LawnGreen’

0x7CFC00

‘LemonChiffon’

0xFFFACD

‘LightBlue’

0xADD8E6

‘LightCoral’

0xF08080

‘LightCyan’

0xE0FFFF

‘LightGoldenRodYellow’

0xFAFAD2

‘LightGreen’

0x90EE90

‘LightGrey’

0xD3D3D3

‘LightPink’

0xFFB6C1

‘LightSalmon’

0xFFA07A

‘LightSeaGreen’

0x20B2AA

‘LightSkyBlue’

0x87CEFA

‘LightSlateGray’

0x778899

‘LightSteelBlue’

0xB0C4DE

‘LightYellow’

0xFFFFE0

‘Lime’

0x00FF00

‘LimeGreen’

0x32CD32

‘Linen’

0xFAF0E6

‘Magenta’

0xFF00FF

‘Maroon’

0x800000

‘MediumAquaMarine’

0x66CDAA

‘MediumBlue’

0x0000CD

‘MediumOrchid’

0xBA55D3

‘MediumPurple’

0x9370D8

‘MediumSeaGreen’

0x3CB371

‘MediumSlateBlue’

0x7B68EE

‘MediumSpringGreen’

0x00FA9A

‘MediumTurquoise’

0x48D1CC

‘MediumVioletRed’

0xC71585

‘MidnightBlue’

0x191970

‘MintCream’

0xF5FFFA

‘MistyRose’

0xFFE4E1

‘Moccasin’

0xFFE4B5

‘NavajoWhite’

0xFFDEAD

‘Navy’

0x000080

‘OldLace’

0xFDF5E6

‘Olive’

0x808000

‘OliveDrab’

0x6B8E23

‘Orange’

0xFFA500

‘OrangeRed’

0xFF4500

‘Orchid’

0xDA70D6

‘PaleGoldenRod’

0xEEE8AA

‘PaleGreen’

0x98FB98

‘PaleTurquoise’

0xAFEEEE

‘PaleVioletRed’

0xD87093

‘PapayaWhip’

0xFFEFD5

‘PeachPuff’

0xFFDAB9

‘Peru’

0xCD853F

‘Pink’

0xFFC0CB

‘Plum’

0xDDA0DD

‘PowderBlue’

0xB0E0E6

‘Purple’

0x800080

‘Red’

0xFF0000

‘RosyBrown’

0xBC8F8F

‘RoyalBlue’

0x4169E1

‘SaddleBrown’

0x8B4513

‘Salmon’

0xFA8072

‘SandyBrown’

0xF4A460

‘SeaGreen’

0x2E8B57

‘SeaShell’

0xFFF5EE

‘Sienna’

0xA0522D

‘Silver’

0xC0C0C0

‘SkyBlue’

0x87CEEB

‘SlateBlue’

0x6A5ACD

‘SlateGray’

0x708090

‘Snow’

0xFFFAFA

‘SpringGreen’

0x00FF7F

‘SteelBlue’

0x4682B4

‘Tan’

0xD2B48C

‘Teal’

0x008080

‘Thistle’

0xD8BFD8

‘Tomato’

0xFF6347

‘Turquoise’

0x40E0D0

‘Violet’

0xEE82EE

‘Wheat’

0xF5DEB3

‘White’

0xFFFFFF

‘WhiteSmoke’

0xF5F5F5

‘Yellow’

0xFFFF00

‘YellowGreen’

0x9ACD32

6.8 Channel Layout

A channel layout specifies the spatial disposition of the channels in a multi-channel audio stream. To specify a channel layout, FFmpeg makes use of a special syntax.

Individual channels are identified by an id, as given by the table below:

‘FL’

front left

‘FR’

front right

‘FC’

front center

‘LFE’

low frequency

‘BL’

back left

‘BR’

back right

‘FLC’

front left-of-center

‘FRC’

front right-of-center

‘BC’

back center

‘SL’

side left

‘SR’

side right

‘TC’

top center

‘TFL’

top front left

‘TFC’

top front center

‘TFR’

top front right

‘TBL’

top back left

‘TBC’

top back center

‘TBR’

top back right

‘DL’

downmix left

‘DR’

downmix right

‘WL’

wide left

‘WR’

wide right

‘SDL’

surround direct left

‘SDR’

surround direct right

‘LFE2’

low frequency 2

Standard channel layout compositions can be specified by using the following identifiers:

‘mono’

FC

‘stereo’

FL+FR

‘2.1’

FL+FR+LFE

‘3.0’

FL+FR+FC

‘3.0(back)’

FL+FR+BC

‘4.0’

FL+FR+FC+BC

‘quad’

FL+FR+BL+BR

‘quad(side)’

FL+FR+SL+SR

‘3.1’

FL+FR+FC+LFE

‘5.0’

FL+FR+FC+BL+BR

‘5.0(side)’

FL+FR+FC+SL+SR

‘4.1’

FL+FR+FC+LFE+BC

‘5.1’

FL+FR+FC+LFE+BL+BR

‘5.1(side)’

FL+FR+FC+LFE+SL+SR

‘6.0’

FL+FR+FC+BC+SL+SR

‘6.0(front)’

FL+FR+FLC+FRC+SL+SR

‘3.1.2’

FL+FR+FC+LFE+TFL+TFR

‘hexagonal’

FL+FR+FC+BL+BR+BC

‘6.1’

FL+FR+FC+LFE+BC+SL+SR

‘6.1’

FL+FR+FC+LFE+BL+BR+BC

‘6.1(front)’

FL+FR+LFE+FLC+FRC+SL+SR

‘7.0’

FL+FR+FC+BL+BR+SL+SR

‘7.0(front)’

FL+FR+FC+FLC+FRC+SL+SR

‘7.1’

FL+FR+FC+LFE+BL+BR+SL+SR

‘7.1(wide)’

FL+FR+FC+LFE+BL+BR+FLC+FRC

‘7.1(wide-side)’

FL+FR+FC+LFE+FLC+FRC+SL+SR

‘5.1.2’

FL+FR+FC+LFE+BL+BR+TFL+TFR

‘octagonal’

FL+FR+FC+BL+BR+BC+SL+SR

‘cube’

FL+FR+BL+BR+TFL+TFR+TBL+TBR

‘5.1.4’

FL+FR+FC+LFE+BL+BR+TFL+TFR+TBL+TBR

‘7.1.2’

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR

‘7.1.4’

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBL+TBR

‘7.2.3’

FL+FR+FC+LFE+BL+BR+SL+SR+TFL+TFR+TBC+LFE2

‘9.1.4’

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR

‘9.1.6’

FL+FR+FC+LFE+BL+BR+FLC+FRC+SL+SR+TFL+TFR+TBL+TBR+TSL+TSR

‘hexadecagonal’

FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR

‘binaural’

BIL+BIR

‘downmix’

DL+DR

‘22.2’

FL+FR+FC+LFE+BL+BR+FLC+FRC+BC+SL+SR+TC+TFL+TFC+TFR+TBL+TBC+TBR+LFE2+TSL+TSR+BFC+BFL+BFR

A custom channel layout can be specified as a sequence of terms, separated by ’+’. Each term can be:

• the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.), each optionally containing a custom name after a ’@’, (e.g. ‘FL@Left’, ‘FR@Right’, ‘FC@Center’, ‘LFE@Low_Frequency’, etc.)

A standard channel layout can be specified by the following:

• the name of a single channel (e.g. ‘FL’, ‘FR’, ‘FC’, ‘LFE’, etc.)
• the name of a standard channel layout (e.g. ‘mono’, ‘stereo’, ‘4.0’, ‘quad’, ‘5.0’, etc.)
• a number of channels, in decimal, followed by ’c’, yielding the default channel layout for that number of channels (see the function av_channel_layout_default). Note that not all channel counts have a default layout.
• a number of channels, in decimal, followed by ’C’, yielding an unknown channel layout with the specified number of channels. Note that not all channel layout specification strings support unknown channel layouts.
• a channel layout mask, in hexadecimal starting with "0x" (see the AV_CH_* macros in libavutil/channel_layout.h.

Before libavutil version 53 the trailing character "c" to specify a number of channels was optional, but now it is required, while a channel layout mask can also be specified as a decimal number (if and only if not followed by "c" or "C").

See also the function av_channel_layout_from_string defined in libavutil/channel_layout.h.

7 Expression Evaluation

When evaluating an arithmetic expression, FFmpeg uses an internal formula evaluator, implemented through the libavutil/eval.h interface.

An expression may contain unary, binary operators, constants, and functions.

Two expressions expr1 and expr2 can be combined to form another expression "expr1;expr2". expr1 and expr2 are evaluated in turn, and the new expression evaluates to the value of expr2.

The following binary operators are available: +, -, *, /, ^.

The following unary operators are available: +, -.

Some internal variables can be used to store and load intermediary results. They can be accessed using the ld and st functions with an index argument varying from 0 to 9 to specify which internal variable to access.

The following functions are available:

abs(x)

Compute absolute value of x.

acos(x)

Compute arccosine of x.

asin(x)

Compute arcsine of x.

atan(x)

Compute arctangent of x.

atan2(y, x)

Compute principal value of the arc tangent of y/x.

between(x, min, max)

Return 1 if x is greater than or equal to min and lesser than or equal to max, 0 otherwise.

bitand(x, y)

bitor(x, y)

Compute bitwise and/or operation on x and y.

The results of the evaluation of x and y are converted to integers before executing the bitwise operation.

Note that both the conversion to integer and the conversion back to floating point can lose precision. Beware of unexpected results for large numbers (usually 2^53 and larger).

ceil(expr)

Round the value of expression expr upwards to the nearest integer. For example, "ceil(1.5)" is "2.0".

clip(x, min, max)

Return the value of x clipped between min and max.

cos(x)

Compute cosine of x.

cosh(x)

Compute hyperbolic cosine of x.

eq(x, y)

Return 1 if x and y are equivalent, 0 otherwise.

exp(x)

Compute exponential of x (with base e, the Euler’s number).

floor(expr)

Round the value of expression expr downwards to the nearest integer. For example, "floor(-1.5)" is "-2.0".

gauss(x)

Compute Gauss function of x, corresponding to exp(-x*x/2) / sqrt(2*PI).

gcd(x, y)

Return the greatest common divisor of x and y. If both x and y are 0 or either or both are less than zero then behavior is undefined.

gt(x, y)

Return 1 if x is greater than y, 0 otherwise.

gte(x, y)

Return 1 if x is greater than or equal to y, 0 otherwise.

hypot(x, y)

This function is similar to the C function with the same name; it returns "sqrt(x*x + y*y)", the length of the hypotenuse of a right triangle with sides of length x and y, or the distance of the point (x, y) from the origin.

if(x, y)

Evaluate x, and if the result is non-zero return the result of the evaluation of y, return 0 otherwise.

if(x, y, z)

Evaluate x, and if the result is non-zero return the evaluation result of y, otherwise the evaluation result of z.

ifnot(x, y)

Evaluate x, and if the result is zero return the result of the evaluation of y, return 0 otherwise.

ifnot(x, y, z)

Evaluate x, and if the result is zero return the evaluation result of y, otherwise the evaluation result of z.

isinf(x)

Return 1.0 if x is +/-INFINITY, 0.0 otherwise.

isnan(x)

Return 1.0 if x is NAN, 0.0 otherwise.

ld(idx)

Load the value of the internal variable with index idx, which was previously stored with st(idx, expr). The function returns the loaded value.

lerp(x, y, z)

Return linear interpolation between x and y by amount of z.

log(x)

Compute natural logarithm of x.

lt(x, y)

Return 1 if x is lesser than y, 0 otherwise.

lte(x, y)

Return 1 if x is lesser than or equal to y, 0 otherwise.

max(x, y)

Return the maximum between x and y.

min(x, y)

Return the minimum between x and y.

mod(x, y)

Compute the remainder of division of x by y.

not(expr)

Return 1.0 if expr is zero, 0.0 otherwise.

pow(x, y)

Compute the power of x elevated y, it is equivalent to "(x)^(y)".

print(t)

print(t, l)

Print the value of expression t with loglevel l. If l is not specified then a default log level is used. Return the value of the expression printed.

random(idx)

Return a pseudo random value between 0.0 and 1.0. idx is the index of the internal variable used to save the seed/state, which can be previously stored with st(idx).

To initialize the seed, you need to store the seed value as a 64-bit unsigned integer in the internal variable with index idx.

For example, to store the seed with value 42 in the internal variable with index 0 and print a few random values:

st(0,42); print(random(0)); print(random(0)); print(random(0))

randomi(idx, min, max)

Return a pseudo random value in the interval between min and max. idx is the index of the internal variable which will be used to save the seed/state, which can be previously stored with st(idx).

To initialize the seed, you need to store the seed value as a 64-bit unsigned integer in the internal variable with index idx.

root(expr, max)

Find an input value for which the function represented by expr with argument ld(0) is 0 in the interval 0..max.

The expression in expr must denote a continuous function or the result is undefined.

ld(0) is used to represent the function input value, which means that the given expression will be evaluated multiple times with various input values that the expression can access through ld(0). When the expression evaluates to 0 then the corresponding input value will be returned.

round(expr)

Round the value of expression expr to the nearest integer. For example, "round(1.5)" is "2.0".

sgn(x)

Compute sign of x.

sin(x)

Compute sine of x.

sinh(x)

Compute hyperbolic sine of x.

sqrt(expr)

Compute the square root of expr. This is equivalent to "(expr)^.5".

squish(x)

Compute expression 1/(1 + exp(4*x)).

st(idx, expr)

Store the value of the expression expr in an internal variable. idx specifies the index of the variable where to store the value, and it is a value ranging from 0 to 9. The function returns the value stored in the internal variable.

The stored value can be retrieved with ld(var).

Note: variables are currently not shared between expressions.

tan(x)

Compute tangent of x.

tanh(x)

Compute hyperbolic tangent of x.

taylor(expr, x)

taylor(expr, x, idx)

Evaluate a Taylor series at x, given an expression representing the ld(idx)-th derivative of a function at 0.

When the series does not converge the result is undefined.

ld(idx) is used to represent the derivative order in expr, which means that the given expression will be evaluated multiple times with various input values that the expression can access through ld(idx). If idx is not specified then 0 is assumed.

Note, when you have the derivatives at y instead of 0, taylor(expr, x-y) can be used.

time(0)

Return the current (wallclock) time in seconds.

trunc(expr)

Round the value of expression expr towards zero to the nearest integer. For example, "trunc(-1.5)" is "-1.0".

while(cond, expr)

Evaluate expression expr while the expression cond is non-zero, and returns the value of the last expr evaluation, or NAN if cond was always false.

The following constants are available:

PI

area of the unit disc, approximately 3.14

E

exp(1) (Euler’s number), approximately 2.718

PHI

golden ratio (1+sqrt(5))/2, approximately 1.618

Assuming that an expression is considered "true" if it has a non-zero value, note that:

* works like AND

+ works like OR

For example the construct:

if (A AND B) then C

is equivalent to:

if(A*B, C)

In your C code, you can extend the list of unary and binary functions, and define recognized constants, so that they are available for your expressions.

The evaluator also recognizes the International System unit prefixes. If ’i’ is appended after the prefix, binary prefixes are used, which are based on powers of 1024 instead of powers of 1000. The ’B’ postfix multiplies the value by 8, and can be appended after a unit prefix or used alone. This allows using for example ’KB’, ’MiB’, ’G’ and ’B’ as number postfix.

The list of available International System prefixes follows, with indication of the corresponding powers of 10 and of 2.

y

10^-24 / 2^-80

z

10^-21 / 2^-70

a

10^-18 / 2^-60

f

10^-15 / 2^-50

p

10^-12 / 2^-40

n

10^-9 / 2^-30

u

10^-6 / 2^-20

m

10^-3 / 2^-10

c

10^-2

d

10^-1

h

10^2

k

10^3 / 2^10

K

10^3 / 2^10

M

10^6 / 2^20

G

10^9 / 2^30

T

10^12 / 2^40

P

10^15 / 2^50

E

10^18 / 2^60

Z

10^21 / 2^70

Y

10^24 / 2^80

8 Codec Options

libavcodec provides some generic global options, which can be set on all the encoders and decoders. In addition, each codec may support so-called private options, which are specific for a given codec.

Sometimes, a global option may only affect a specific kind of codec, and may be nonsensical or ignored by another, so you need to be aware of the meaning of the specified options. Also some options are meant only for decoding or encoding.

Options may be set by specifying -option value in the FFmpeg tools, or by setting the value explicitly in the AVCodecContext options or using the libavutil/opt.h API for programmatic use.

The list of supported options follow:

b integer (encoding,audio,video)

Set bitrate in bits/s. Default value is 200K.

ab integer (encoding,audio)

Set audio bitrate (in bits/s). Default value is 128K.

bt integer (encoding,video)

Set video bitrate tolerance (in bits/s). In 1-pass mode, bitrate tolerance specifies how far ratecontrol is willing to deviate from the target average bitrate value. This is not related to min/max bitrate. Lowering tolerance too much has an adverse effect on quality.

flags flags (decoding/encoding,audio,video,subtitles)

Set generic flags.

Possible values:

‘mv4’

Use four motion vector by macroblock (mpeg4).

‘qpel’

Use 1/4 pel motion compensation.

‘loop’

Use loop filter.

‘qscale’

Use fixed qscale.

‘pass1’

Use internal 2pass ratecontrol in first pass mode.

‘pass2’

Use internal 2pass ratecontrol in second pass mode.

‘gray’

Only decode/encode grayscale.

‘psnr’

Set error[?] variables during encoding.

‘truncated’

Input bitstream might be randomly truncated.

‘drop_changed’

Don’t output frames whose parameters differ from first decoded frame in stream. Error AVERROR_INPUT_CHANGED is returned when a frame is dropped.

‘ildct’

Use interlaced DCT.

‘low_delay’

Force low delay.

‘global_header’

Place global headers in extradata instead of every keyframe.

‘bitexact’

Only write platform-, build- and time-independent data. (except (I)DCT). This ensures that file and data checksums are reproducible and match between platforms. Its primary use is for regression testing.

‘aic’

Apply H263 advanced intra coding / mpeg4 ac prediction.

‘ilme’

Apply interlaced motion estimation.

‘cgop’

Use closed gop.

‘output_corrupt’

Output even potentially corrupted frames.

time_base rational number

Set codec time base.

It is the fundamental unit of time (in seconds) in terms of which frame timestamps are represented. For fixed-fps content, timebase should be 1 / frame_rate and timestamp increments should be identically 1.

g integer (encoding,video)

Set the group of picture (GOP) size. Default value is 12.

ar integer (decoding/encoding,audio)

Set audio sampling rate (in Hz).

ac integer (decoding/encoding,audio)

Set number of audio channels.

cutoff integer (encoding,audio)

Set cutoff bandwidth. (Supported only by selected encoders, see their respective documentation sections.)

frame_size integer (encoding,audio)

Set audio frame size.

Each submitted frame except the last must contain exactly frame_size samples per channel. May be 0 when the codec has CODEC_CAP_VARIABLE_FRAME_SIZE set, in that case the frame size is not restricted. It is set by some decoders to indicate constant frame size.

frame_number integer

Set the frame number.

delay integer

qcomp float (encoding,video)

Set video quantizer scale compression (VBR). It is used as a constant in the ratecontrol equation. Recommended range for default rc_eq: 0.0-1.0.

qblur float (encoding,video)

Set video quantizer scale blur (VBR).

qmin integer (encoding,video)

Set min video quantizer scale (VBR). Must be included between -1 and 69, default value is 2.

qmax integer (encoding,video)

Set max video quantizer scale (VBR). Must be included between -1 and 1024, default value is 31.

qdiff integer (encoding,video)

Set max difference between the quantizer scale (VBR).

bf integer (encoding,video)

Set max number of B frames between non-B-frames.

Must be an integer between -1 and 16. 0 means that B-frames are disabled. If a value of -1 is used, it will choose an automatic value depending on the encoder.

Default value is 0.

b_qfactor float (encoding,video)

Set qp factor between P and B frames.

codec_tag integer

bug flags (decoding,video)

Workaround not auto detected encoder bugs.

Possible values:

‘autodetect’

‘xvid_ilace’

Xvid interlacing bug (autodetected if fourcc==XVIX)

‘ump4’

(autodetected if fourcc==UMP4)

‘no_padding’

padding bug (autodetected)

‘amv’

‘qpel_chroma’

‘std_qpel’

old standard qpel (autodetected per fourcc/version)

‘qpel_chroma2’

‘direct_blocksize’

direct-qpel-blocksize bug (autodetected per fourcc/version)

‘edge’

edge padding bug (autodetected per fourcc/version)

‘hpel_chroma’

‘dc_clip’

‘ms’

Workaround various bugs in microsoft broken decoders.

‘trunc’

trancated frames

strict integer (decoding/encoding,audio,video)

Specify how strictly to follow the standards.

Possible values:

‘very’

strictly conform to an older more strict version of the spec or reference software

‘strict’

strictly conform to all the things in the spec no matter what consequences

‘normal’

‘unofficial’

allow unofficial extensions

‘experimental’

allow non standardized experimental things, experimental (unfinished/work in progress/not well tested) decoders and encoders. Note: experimental decoders can pose a security risk, do not use this for decoding untrusted input.

b_qoffset float (encoding,video)

Set QP offset between P and B frames.

err_detect flags (decoding,audio,video)

Set error detection flags.

Possible values:

‘crccheck’

verify embedded CRCs

‘bitstream’

detect bitstream specification deviations

‘buffer’

detect improper bitstream length

‘explode’

abort decoding on minor error detection

‘ignore_err’

ignore decoding errors, and continue decoding. This is useful if you want to analyze the content of a video and thus want everything to be decoded no matter what. This option will not result in a video that is pleasing to watch in case of errors.

‘careful’

consider things that violate the spec and have not been seen in the wild as errors

‘compliant’

consider all spec non compliancies as errors

‘aggressive’

consider things that a sane encoder should not do as an error

has_b_frames integer

block_align integer

rc_override_count integer

maxrate integer (encoding,audio,video)

Set max bitrate tolerance (in bits/s). Requires bufsize to be set.

minrate integer (encoding,audio,video)

Set min bitrate tolerance (in bits/s). Most useful in setting up a CBR encode. It is of little use elsewise.

bufsize integer (encoding,audio,video)

Set ratecontrol buffer size (in bits).

i_qfactor float (encoding,video)

Set QP factor between P and I frames.

i_qoffset float (encoding,video)

Set QP offset between P and I frames.

dct integer (encoding,video)

Set DCT algorithm.

Possible values:

‘auto’

autoselect a good one (default)

‘fastint’

fast integer

‘int’

accurate integer

‘mmx’

‘altivec’

‘faan’

floating point AAN DCT

lumi_mask float (encoding,video)

Compress bright areas stronger than medium ones.

tcplx_mask float (encoding,video)

Set temporal complexity masking.

scplx_mask float (encoding,video)

Set spatial complexity masking.

p_mask float (encoding,video)

Set inter masking.

dark_mask float (encoding,video)

Compress dark areas stronger than medium ones.

idct integer (decoding/encoding,video)

Select IDCT implementation.

Possible values:

‘auto’

‘int’

‘simple’

‘simplemmx’

‘simpleauto’

Automatically pick a IDCT compatible with the simple one

‘arm’

‘altivec’

‘sh4’

‘simplearm’

‘simplearmv5te’

‘simplearmv6’

‘simpleneon’

‘xvid’

‘faani’

floating point AAN IDCT

slice_count integer

ec flags (decoding,video)

Set error concealment strategy.

Possible values:

‘guess_mvs’

iterative motion vector (MV) search (slow)

‘deblock’

use strong deblock filter for damaged MBs

‘favor_inter’

favor predicting from the previous frame instead of the current

bits_per_coded_sample integer

aspect rational number (encoding,video)

Set sample aspect ratio.

sar rational number (encoding,video)

Set sample aspect ratio. Alias to aspect.

debug flags (decoding/encoding,audio,video,subtitles)

Print specific debug info.

Possible values:

‘pict’

picture info

‘rc’

rate control

‘bitstream’

‘mb_type’

macroblock (MB) type

‘qp’

per-block quantization parameter (QP)

‘dct_coeff’

‘green_metadata’

display complexity metadata for the upcoming frame, GoP or for a given duration.

‘skip’

‘startcode’

‘er’

error recognition

‘mmco’

memory management control operations (H.264)

‘bugs’

‘buffers’

picture buffer allocations

‘thread_ops’

threading operations

‘nomc’

skip motion compensation

cmp integer (encoding,video)

Set full pel me compare function.

Possible values:

‘sad’

sum of absolute differences, fast (default)

‘sse’

sum of squared errors

‘satd’

sum of absolute Hadamard transformed differences

‘dct’

sum of absolute DCT transformed differences

‘psnr’

sum of squared quantization errors (avoid, low quality)

‘bit’

number of bits needed for the block

‘rd’

rate distortion optimal, slow

‘zero’

0

‘vsad’

sum of absolute vertical differences

‘vsse’

sum of squared vertical differences

‘nsse’

noise preserving sum of squared differences

‘w53’

5/3 wavelet, only used in snow

‘w97’

9/7 wavelet, only used in snow

‘dctmax’

‘chroma’

subcmp integer (encoding,video)

Set sub pel me compare function.

Possible values:

‘sad’

sum of absolute differences, fast (default)

‘sse’

sum of squared errors

‘satd’

sum of absolute Hadamard transformed differences

‘dct’

sum of absolute DCT transformed differences

‘psnr’

sum of squared quantization errors (avoid, low quality)

‘bit’

number of bits needed for the block

‘rd’

rate distortion optimal, slow

‘zero’

0

‘vsad’

sum of absolute vertical differences

‘vsse’

sum of squared vertical differences

‘nsse’

noise preserving sum of squared differences

‘w53’

5/3 wavelet, only used in snow

‘w97’

9/7 wavelet, only used in snow

‘dctmax’

‘chroma’

mbcmp integer (encoding,video)

Set macroblock compare function.

Possible values:

‘sad’

sum of absolute differences, fast (default)

‘sse’

sum of squared errors

‘satd’

sum of absolute Hadamard transformed differences

‘dct’

sum of absolute DCT transformed differences

‘psnr’

sum of squared quantization errors (avoid, low quality)

‘bit’

number of bits needed for the block

‘rd’

rate distortion optimal, slow

‘zero’

0

‘vsad’

sum of absolute vertical differences

‘vsse’

sum of squared vertical differences

‘nsse’

noise preserving sum of squared differences

‘w53’

5/3 wavelet, only used in snow

‘w97’

9/7 wavelet, only used in snow

‘dctmax’

‘chroma’

ildctcmp integer (encoding,video)

Set interlaced dct compare function.

Possible values:

‘sad’

sum of absolute differences, fast (default)

‘sse’

sum of squared errors

‘satd’

sum of absolute Hadamard transformed differences

‘dct’

sum of absolute DCT transformed differences

‘psnr’

sum of squared quantization errors (avoid, low quality)

‘bit’

number of bits needed for the block

‘rd’

rate distortion optimal, slow

‘zero’

0

‘vsad’

sum of absolute vertical differences

‘vsse’

sum of squared vertical differences

‘nsse’

noise preserving sum of squared differences

‘w53’

5/3 wavelet, only used in snow

‘w97’

9/7 wavelet, only used in snow

‘dctmax’

‘chroma’

dia_size integer (encoding,video)

Set diamond type & size for motion estimation.

‘(1024, INT_MAX)’

full motion estimation(slowest)

‘(768, 1024]’

umh motion estimation

‘(512, 768]’

hex motion estimation

‘(256, 512]’

l2s diamond motion estimation

‘[2,256]’

var diamond motion estimation

‘(-1, 2)’

small diamond motion estimation

‘-1’

funny diamond motion estimation

‘(INT_MIN, -1)’

sab diamond motion estimation

last_pred integer (encoding,video)

Set amount of motion predictors from the previous frame.

precmp integer (encoding,video)

Set pre motion estimation compare function.

Possible values:

‘sad’

sum of absolute differences, fast (default)

‘sse’

sum of squared errors

‘satd’

sum of absolute Hadamard transformed differences

‘dct’

sum of absolute DCT transformed differences

‘psnr’

sum of squared quantization errors (avoid, low quality)

‘bit’

number of bits needed for the block

‘rd’

rate distortion optimal, slow

‘zero’

0

‘vsad’

sum of absolute vertical differences

‘vsse’

sum of squared vertical differences

‘nsse’

noise preserving sum of squared differences

‘w53’

5/3 wavelet, only used in snow

‘w97’

9/7 wavelet, only used in snow

‘dctmax’

‘chroma’

pre_dia_size integer (encoding,video)

Set diamond type & size for motion estimation pre-pass.

subq integer (encoding,video)

Set sub pel motion estimation quality.

me_range integer (encoding,video)

Set limit motion vectors range (1023 for DivX player).

global_quality integer (encoding,audio,video)

slice_flags integer

mbd integer (encoding,video)

Set macroblock decision algorithm (high quality mode).

Possible values:

‘simple’

use mbcmp (default)

‘bits’

use fewest bits

‘rd’

use best rate distortion

rc_init_occupancy integer (encoding,video)

Set number of bits which should be loaded into the rc buffer before decoding starts.

flags2 flags (decoding/encoding,audio,video,subtitles)

Possible values:

‘fast’

Allow non spec compliant speedup tricks.

‘noout’

Skip bitstream encoding.

‘ignorecrop’

Ignore cropping information from sps.

‘local_header’

Place global headers at every keyframe instead of in extradata.

‘chunks’

Frame data might be split into multiple chunks.

‘showall’

Show all frames before the first keyframe.

‘export_mvs’

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) for codecs that support it. See also doc/examples/export_mvs.c.

‘skip_manual’

Do not skip samples and export skip information as frame side data.

‘ass_ro_flush_noop’

Do not reset ASS ReadOrder field on flush.

‘icc_profiles’

Generate/parse embedded ICC profiles from/to colorimetry tags.

export_side_data flags (decoding/encoding,audio,video,subtitles)

Possible values:

‘mvs’

Export motion vectors into frame side-data (see AV_FRAME_DATA_MOTION_VECTORS) for codecs that support it. See also doc/examples/export_mvs.c.

‘prft’

Export encoder Producer Reference Time into packet side-data (see AV_PKT_DATA_PRFT) for codecs that support it.

‘venc_params’

Export video encoding parameters through frame side data (see AV_FRAME_DATA_VIDEO_ENC_PARAMS) for codecs that support it. At present, those are H.264 and VP9.

‘film_grain’

Export film grain parameters through frame side data (see AV_FRAME_DATA_FILM_GRAIN_PARAMS). Supported at present by AV1 decoders.

‘enhancements’

Export picture enhancement metadata through frame side data, e.g. LCEVC (see AV_FRAME_DATA_LCEVC).

threads integer (decoding/encoding,video)

Set the number of threads to be used, in case the selected codec implementation supports multi-threading.

Possible values:

‘auto, 0’

automatically select the number of threads to set

Default value is ‘auto’.

dc integer (encoding,video)

Set intra_dc_precision.

nssew integer (encoding,video)

Set nsse weight.

skip_top integer (decoding,video)

Set number of macroblock rows at the top which are skipped.

skip_bottom integer (decoding,video)

Set number of macroblock rows at the bottom which are skipped.

profile integer (encoding,audio,video)

Set encoder codec profile. Default value is ‘unknown’. Encoder specific profiles are documented in the relevant encoder documentation.

level integer (encoding,audio,video)

Set the encoder level. This level depends on the specific codec, and might correspond to the profile level. It is set by default to ‘unknown’.

Possible values:

‘unknown’

lowres integer (decoding,audio,video)

Decode at 1= 1/2, 2=1/4, 3=1/8 resolutions.

mblmin integer (encoding,video)

Set min macroblock lagrange factor (VBR).

mblmax integer (encoding,video)

Set max macroblock lagrange factor (VBR).

skip_loop_filter integer (decoding,video)

skip_idct integer (decoding,video)

skip_frame integer (decoding,video)

Make decoder discard processing depending on the frame type selected by the option value.

skip_loop_filter skips frame loop filtering, skip_idct skips frame IDCT/dequantization, skip_frame skips decoding.

Possible values:

‘none’

Discard no frame.

‘default’

Discard useless frames like 0-sized frames.

‘noref’

Discard all non-reference frames.

‘bidir’

Discard all bidirectional frames.

‘nokey’

Discard all frames excepts keyframes.

‘nointra’

Discard all frames except I frames.

‘all’

Discard all frames.

Default value is ‘default’.

bidir_refine integer (encoding,video)

Refine the two motion vectors used in bidirectional macroblocks.

keyint_min integer (encoding,video)

Set minimum interval between IDR-frames.

refs integer (encoding,video)

Set reference frames to consider for motion compensation.

trellis integer (encoding,audio,video)

Set rate-distortion optimal quantization.

mv0_threshold integer (encoding,video)

compression_level integer (encoding,audio,video)

bits_per_raw_sample integer

channel_layout integer (decoding/encoding,audio)

See (ffmpeg-utils)the Channel Layout section in the ffmpeg-utils(1) manual for the required syntax.

rc_max_vbv_use float (encoding,video)

rc_min_vbv_use float (encoding,video)

color_primaries integer (decoding/encoding,video)

Possible values:

‘bt709’

BT.709

‘bt470m’

BT.470 M

‘bt470bg’

BT.470 BG

‘smpte170m’

SMPTE 170 M

‘smpte240m’

SMPTE 240 M

‘film’

Film

‘bt2020’

BT.2020

‘smpte428’

‘smpte428_1’

SMPTE ST 428-1

‘smpte431’

SMPTE 431-2

‘smpte432’

SMPTE 432-1

‘jedec-p22’

JEDEC P22

color_trc integer (decoding/encoding,video)

Possible values:

‘bt709’

BT.709

‘gamma22’

BT.470 M

‘gamma28’

BT.470 BG

‘smpte170m’

SMPTE 170 M

‘smpte240m’

SMPTE 240 M

‘linear’

Linear

‘log’

‘log100’

Log

‘log_sqrt’

‘log316’

Log square root

‘iec61966_2_4’

‘iec61966-2-4’

IEC 61966-2-4

‘bt1361’

‘bt1361e’

BT.1361

‘iec61966_2_1’

‘iec61966-2-1’

IEC 61966-2-1

‘bt2020_10’

‘bt2020_10bit’

BT.2020 - 10 bit

‘bt2020_12’

‘bt2020_12bit’

BT.2020 - 12 bit

‘smpte2084’

SMPTE ST 2084

‘smpte428’

‘smpte428_1’

SMPTE ST 428-1

‘arib-std-b67’

ARIB STD-B67

colorspace integer (decoding/encoding,video)

Possible values:

‘rgb’

RGB

‘bt709’

BT.709

‘fcc’

FCC

‘bt470bg’

BT.470 BG

‘smpte170m’

SMPTE 170 M

‘smpte240m’

SMPTE 240 M

‘ycocg’

YCOCG

‘bt2020nc’

‘bt2020_ncl’

BT.2020 NCL

‘bt2020c’

‘bt2020_cl’

BT.2020 CL

‘smpte2085’

SMPTE 2085

‘chroma-derived-nc’

Chroma-derived NCL

‘chroma-derived-c’

Chroma-derived CL

‘ictcp’

ICtCp

color_range integer (decoding/encoding,video)

If used as input parameter, it serves as a hint to the decoder, which color_range the input has. Possible values:

‘tv’

‘mpeg’

‘limited’

MPEG (219*2^(n-8))

‘pc’

‘jpeg’

‘full’

JPEG (2^n-1)

chroma_sample_location integer (decoding/encoding,video)

Possible values:

‘left’

‘center’

‘topleft’

‘top’

‘bottomleft’

‘bottom’

alpha_mode integer (decoding/encoding,video)

Possible values:

‘premultiplied’

‘straight’

log_level_offset integer

Set the log level offset.

slices integer (encoding,video)

Number of slices, used in parallelized encoding.

thread_type flags (decoding/encoding,video)

Select which multithreading methods to use.

Use of ‘frame’ will increase decoding delay by one frame per thread, so clients which cannot provide future frames should not use it.

Possible values:

‘slice’

Decode more than one part of a single frame at once.

Multithreading using slices works only when the video was encoded with slices.

‘frame’

Decode more than one frame at once.

Default value is ‘slice+frame’.

audio_service_type integer (encoding,audio)

Set audio service type.

Possible values:

‘ma’

Main Audio Service

‘ef’

Effects

‘vi’

Visually Impaired

‘hi’

Hearing Impaired

‘di’

Dialogue

‘co’

Commentary

‘em’

Emergency

‘vo’

Voice Over

‘ka’

Karaoke

request_sample_fmt sample_fmt (decoding,audio)

Set sample format audio decoders should prefer. Default value is none.

pkt_timebase rational number

sub_charenc encoding (decoding,subtitles)

Set the input subtitles character encoding.

field_order field_order (video)

Set/override the field order of the video. Possible values:

‘progressive’

Progressive video

‘tt’

Interlaced video, top field coded and displayed first

‘bb’

Interlaced video, bottom field coded and displayed first

‘tb’

Interlaced video, top coded first, bottom displayed first

‘bt’

Interlaced video, bottom coded first, top displayed first

skip_alpha bool (decoding,video)

Set to 1 to disable processing alpha (transparency). This works like the ‘gray’ flag in the flags option which skips chroma information instead of alpha. Default is 0.

codec_whitelist list (input)

"," separated list of allowed decoders. By default all are allowed.

dump_separator string (input)

Separator used to separate the fields printed on the command line about the Stream parameters. For example, to separate the fields with newlines and indentation:

ffprobe -dump_separator "
                          "  -i ~/videos/matrixbench_mpeg2.mpg

max_pixels integer (decoding/encoding,video)

Maximum number of pixels per image. This value can be used to avoid out of memory failures due to large images.

apply_cropping bool (decoding,video)

Enable cropping if cropping parameters are multiples of the required alignment for the left and top parameters. If the alignment is not met the cropping will be partially applied to maintain alignment. Default is 1 (enabled). Note: The required alignment depends on if AV_CODEC_FLAG_UNALIGNED is set and the CPU. AV_CODEC_FLAG_UNALIGNED cannot be changed from the command line. Also hardware decoders will not apply left/top Cropping.

9 Decoders

Decoders are configured elements in FFmpeg which allow the decoding of multimedia streams.

When you configure your FFmpeg build, all the supported native decoders are enabled by default. Decoders requiring an external library must be enabled manually via the corresponding --enable-lib option. You can list all available decoders using the configure option --list-decoders.

You can disable all the decoders with the configure option --disable-decoders and selectively enable / disable single decoders with the options --enable-decoder=DECODER / --disable-decoder=DECODER.

The option -decoders of the ff* tools will display the list of enabled decoders.

10 Video Decoders

A description of some of the currently available video decoders follows.

10.1 av1

AOMedia Video 1 (AV1) decoder.

10.1.1 Options

operating_point

Select an operating point of a scalable AV1 bitstream (0 - 31). Default is 0.

10.2 hevc

HEVC (AKA ITU-T H.265 or ISO/IEC 23008-2) decoder.

The decoder supports MV-HEVC multiview streams with at most two views. Views to be output are selected by supplying a list of view IDs to the decoder (the view_ids option). This option may be set either statically before decoder init, or from the get_format() callback - useful for the case when the view count or IDs change dynamically during decoding.

Only the base layer is decoded by default.

Note that if you are using the ffmpeg CLI tool, you should be using view specifiers as documented in its manual, rather than the options documented here.

10.2.1 Options

view_ids (MV-HEVC)

Specify a list of view IDs that should be output. This option can also be set to a single ’-1’, which will cause all views defined in the VPS to be decoded and output.

view_ids_available (MV-HEVC)

This option may be read by the caller to retrieve an array of view IDs available in the active VPS. The array is empty for single-layer video.

The value of this option is guaranteed to be accurate when read from the get_format() callback. It may also be set at other times (e.g. after opening the decoder), but the value is informational only and may be incorrect (e.g. when the stream contains multiple distinct VPS NALUs).

view_pos_available (MV-HEVC)

This option may be read by the caller to retrieve an array of view positions (left, right, or unspecified) available in the active VPS, as AVStereo3DView values. When the array is available, its elements apply to the corresponding elements of view_ids_available, i.e. view_pos_available[i] contains the position of view with ID view_ids_available[i].

Same validity restrictions as for view_ids_available apply to this option.

10.3 rawvideo

Raw video decoder.

This decoder decodes rawvideo streams.

10.3.1 Options

top top_field_first

Specify the assumed field type of the input video.

-1

the video is assumed to be progressive (default)

0

bottom-field-first is assumed

1

top-field-first is assumed

10.4 libdav1d

dav1d AV1 decoder.

libdav1d allows libavcodec to decode the AOMedia Video 1 (AV1) codec. Requires the presence of the libdav1d headers and library during configuration. You need to explicitly configure the build with --enable-libdav1d.

10.4.1 Options

The following options are supported by the libdav1d wrapper.

max_frame_delay

Set max amount of frames the decoder may buffer internally. The default value is 0 (autodetect).

filmgrain

Apply film grain to the decoded video if present in the bitstream. Defaults to the internal default of the library. This option is deprecated and will be removed in the future. See the global option export_side_data to export Film Grain parameters instead of applying it.

oppoint

Select an operating point of a scalable AV1 bitstream (0 - 31). Defaults to the internal default of the library.

alllayers

Output all spatial layers of a scalable AV1 bitstream. The default value is false.

10.5 libdavs2

AVS2-P2/IEEE1857.4 video decoder wrapper.

This decoder allows libavcodec to decode AVS2 streams with davs2 library.

10.6 libuavs3d

AVS3-P2/IEEE1857.10 video decoder.

libuavs3d allows libavcodec to decode AVS3 streams. Requires the presence of the libuavs3d headers and library during configuration. You need to explicitly configure the build with --enable-libuavs3d.

10.6.1 Options

The following option is supported by the libuavs3d wrapper.

frame_threads

Set amount of frame threads to use during decoding. The default value is 0 (autodetect).

10.7 libxevd

eXtra-fast Essential Video Decoder (XEVD) MPEG-5 EVC decoder wrapper.

This decoder requires the presence of the libxevd headers and library during configuration. You need to explicitly configure the build with --enable-libxevd.

The xevd project website is at https://github.com/mpeg5/xevd.

10.7.1 Options

The following options are supported by the libxevd wrapper. The xevd-equivalent options or values are listed in parentheses for easy migration.

To get a more accurate and extensive documentation of the libxevd options, invoke the command xevd_app --help or consult the libxevd documentation.

threads (threads)

Force to use a specific number of threads

10.8 QSV Decoders

The family of Intel QuickSync Video decoders (VC1, MPEG-2, H.264, HEVC, JPEG/MJPEG, VP8, VP9, AV1, VVC).

10.8.1 Common Options

The following options are supported by all qsv decoders.

async_depth

Internal parallelization depth, the higher the value the higher the latency.

gpu_copy

A GPU-accelerated copy between video and system memory

‘default’

‘on’

‘off’

10.8.2 HEVC Options

Extra options for hevc_qsv.

load_plugin

A user plugin to load in an internal session

‘none’

‘hevc_sw’

‘hevc_hw’

load_plugins

A :-separate list of hexadecimal plugin UIDs to load in an internal session

10.9 v210

Uncompressed 4:2:2 10-bit decoder.

10.9.1 Options

custom_stride

Set the line size of the v210 data in bytes. The default value is 0 (autodetect). You can use the special -1 value for a strideless v210 as seen in BOXX files.

11 Audio Decoders

A description of some of the currently available audio decoders follows.

11.1 ac3

AC-3 audio decoder.

This decoder implements part of ATSC A/52:2010 and ETSI TS 102 366, as well as the undocumented RealAudio 3 (a.k.a. dnet).

11.1.1 AC-3 Decoder Options

-drc_scale value

Dynamic Range Scale Factor. The factor to apply to dynamic range values from the AC-3 stream. This factor is applied exponentially. The default value is 1. There are 3 notable scale factor ranges:

drc_scale == 0

DRC disabled. Produces full range audio.

0 < drc_scale <= 1

DRC enabled. Applies a fraction of the stream DRC value. Audio reproduction is between full range and full compression.

drc_scale > 1

DRC enabled. Applies drc_scale asymmetrically. Loud sounds are fully compressed. Soft sounds are enhanced.

11.2 flac

FLAC audio decoder.

This decoder aims to implement the complete FLAC specification from Xiph.

11.2.1 FLAC Decoder options

-use_buggy_lpc

The lavc FLAC encoder used to produce buggy streams with high lpc values (like the default value). This option makes it possible to decode such streams correctly by using lavc’s old buggy lpc logic for decoding.

11.3 ffwavesynth

Internal wave synthesizer.

This decoder generates wave patterns according to predefined sequences. Its use is purely internal and the format of the data it accepts is not publicly documented.

11.4 libcelt

libcelt decoder wrapper.

libcelt allows libavcodec to decode the Xiph CELT ultra-low delay audio codec. Requires the presence of the libcelt headers and library during configuration. You need to explicitly configure the build with --enable-libcelt.

11.5 libgsm

libgsm decoder wrapper.

libgsm allows libavcodec to decode the GSM full rate audio codec. Requires the presence of the libgsm headers and library during configuration. You need to explicitly configure the build with --enable-libgsm.

This decoder supports both the ordinary GSM and the Microsoft variant.

11.6 libilbc

libilbc decoder wrapper.

libilbc allows libavcodec to decode the Internet Low Bitrate Codec (iLBC) audio codec. Requires the presence of the libilbc headers and library during configuration. You need to explicitly configure the build with --enable-libilbc.

11.6.1 Options

The following option is supported by the libilbc wrapper.

enhance

Enable the enhancement of the decoded audio when set to 1. The default value is 0 (disabled).

11.7 libmpeghdec

libmpeghdec decoder wrapper.

libmpeghdec allows libmpeghdec to decode the MPEG-H 3D audio codec. Requires the presence of the libmpeghdec headers and library during configuration. You need to explicitly configure the build with --enable-libmpeghdec --enable-nonfree.

11.8 libopencore-amrnb

libopencore-amrnb decoder wrapper.

libopencore-amrnb allows libavcodec to decode the Adaptive Multi-Rate Narrowband audio codec. Using it requires the presence of the libopencore-amrnb headers and library during configuration. You need to explicitly configure the build with --enable-libopencore-amrnb.

An FFmpeg native decoder for AMR-NB exists, so users can decode AMR-NB without this library.

11.9 libopencore-amrwb

libopencore-amrwb decoder wrapper.

libopencore-amrwb allows libavcodec to decode the Adaptive Multi-Rate Wideband audio codec. Using it requires the presence of the libopencore-amrwb headers and library during configuration. You need to explicitly configure the build with --enable-libopencore-amrwb.

An FFmpeg native decoder for AMR-WB exists, so users can decode AMR-WB without this library.

11.10 libopus

libopus decoder wrapper.

libopus allows libavcodec to decode the Opus Interactive Audio Codec. Requires the presence of the libopus headers and library during configuration. You need to explicitly configure the build with --enable-libopus.

An FFmpeg native decoder for Opus exists, so users can decode Opus without this library.

12 Subtitles Decoders

12.1 libaribb24

ARIB STD-B24 caption decoder.

Implements profiles A and C of the ARIB STD-B24 standard.

12.1.1 libaribb24 Decoder Options

-aribb24-base-path path

Sets the base path for the libaribb24 library. This is utilized for reading of configuration files (for custom unicode conversions), and for dumping of non-text symbols as images under that location.

Unset by default.

-aribb24-skip-ruby-text boolean

Tells the decoder wrapper to skip text blocks that contain half-height ruby text.

Enabled by default.

12.2 libaribcaption

Yet another ARIB STD-B24 caption decoder using external libaribcaption library.

Implements profiles A and C of the Japanese ARIB STD-B24 standard, Brazilian ABNT NBR 15606-1, and Philippines version of ISDB-T.

Requires the presence of the libaribcaption headers and library (https://github.com/xqq/libaribcaption) during configuration. You need to explicitly configure the build with --enable-libaribcaption. If both libaribb24 and libaribcaption are enabled, libaribcaption decoder precedes.

12.2.1 libaribcaption Decoder Options

-sub_type subtitle_type

Specifies the format of the decoded subtitles.

‘bitmap’

Graphical image.

‘ass’

ASS formatted text.

‘text’

Simple text based output without formatting.

The default is ass as same as libaribb24 decoder. Some present players (e.g., mpv) expect ASS format for ARIB caption.

-caption_encoding encoding_scheme

Specifies the encoding scheme of input subtitle text.

‘auto’

Automatically detect text encoding (default).

‘jis’

8bit-char JIS encoding defined in ARIB STD B24. This encoding used in Japan for ISDB captions.

‘utf8’

UTF-8 encoding defined in ARIB STD B24. This encoding is used in Philippines for ISDB-T captions.

‘latin’

Latin character encoding defined in ABNT NBR 15606-1. This encoding is used in South America for SBTVD / ISDB-Tb captions.

-font font_name[,font_name2,...]

Specify comma-separated list of font family names to be used for bitmap or ass type subtitle rendering. Only first font name is used for ass type subtitle.

If not specified, use internally defined default font family.

-ass_single_rect boolean

ARIB STD-B24 specifies that some captions may be displayed at different positions at a time (multi-rectangle subtitle). Since some players (e.g., old mpv) can’t handle multiple ASS rectangles in a single AVSubtitle, or multiple ASS rectangles of indeterminate duration with the same start timestamp, this option can change the behavior so that all the texts are displayed in a single ASS rectangle.

The default is false.

If your player cannot handle AVSubtitles with multiple ASS rectangles properly, set this option to true or define ASS_SINGLE_RECT=1 to change default behavior at compilation.

-force_outline_text boolean

Specify whether always render outline text for all characters regardless of the indication by character style.

The default is false.

-outline_width number (0.0 - 3.0)

Specify width for outline text, in dots (relative).

The default is 1.5.

-ignore_background boolean

Specify whether to ignore background color rendering.

The default is false.

-ignore_ruby boolean

Specify whether to ignore rendering for ruby-like (furigana) characters.

The default is false.

-replace_drcs boolean

Specify whether to render replaced DRCS characters as Unicode characters.

The default is true.

-replace_msz_ascii boolean

Specify whether to replace MSZ (Middle Size; half width) fullwidth alphanumerics with halfwidth alphanumerics.

The default is true.

-replace_msz_japanese boolean

Specify whether to replace some MSZ (Middle Size; half width) fullwidth japanese special characters with halfwidth ones.

The default is true.

-replace_msz_glyph boolean

Specify whether to replace MSZ (Middle Size; half width) characters with halfwidth glyphs if the fonts supports it. This option works under FreeType or DirectWrite renderer with Adobe-Japan1 compliant fonts. e.g., IBM Plex Sans JP, Morisawa BIZ UDGothic, Morisawa BIZ UDMincho, Yu Gothic, Yu Mincho, and Meiryo.

The default is true.

-canvas_size image_size

Specify the resolution of the canvas to render subtitles to; usually, this should be frame size of input video. This only applies when -subtitle_type is set to bitmap.

The libaribcaption decoder assumes input frame size for bitmap rendering as below:

1. PROFILE_A : 1440 x 1080 with SAR (PAR) 4:3
2. PROFILE_C : 320 x 180 with SAR (PAR) 1:1

If actual frame size of input video does not match above assumption, the rendered captions may be distorted. To make the captions undistorted, add -canvas_size option to specify actual input video size.

Note that the -canvas_size option is not required for video with different size but same aspect ratio. In such cases, the caption will be stretched or shrunk to actual video size if -canvas_size option is not specified. If -canvas_size option is specified with different size, the caption will be stretched or shrunk as specified size with calculated SAR.

12.2.2 libaribcaption decoder usage examples

Display MPEG-TS file with ARIB subtitle by ffplay tool:

ffplay -sub_type bitmap MPEG.TS

Display MPEG-TS file with input frame size 1920x1080 by ffplay tool:

ffplay -sub_type bitmap -canvas_size 1920x1080 MPEG.TS

Embed ARIB subtitle in transcoded video:

ffmpeg -sub_type bitmap -i src.m2t -filter_complex "[0:v][0:s]overlay" -vcodec h264 dest.mp4

12.3 dvbsub

12.3.1 Options

compute_clut

-2

Compute clut once if no matching CLUT is in the stream.

-1

Compute clut if no matching CLUT is in the stream.

0

Never compute CLUT

1

Always compute CLUT and override the one provided in the stream.

dvb_substream

Selects the dvb substream, or all substreams if -1 which is default.

12.4 dvdsub