@c man end DESCRIPTION
+@chapter Detailed description
+@c man begin DETAILED DESCRIPTION
+
+The transcoding process in @command{avconv} for each output can be described by
+the following diagram:
+
+@example
+ _______ ______________
+| | | |
+| input | demuxer | encoded data | decoder
+| file | ---------> | packets | -----+
+|_______| |______________| |
+ v
+ _________
+ | |
+ | decoded |
+ | frames |
+ |_________|
+ ________ ______________ |
+| | | | |
+| output | <-------- | encoded data | <----+
+| file | muxer | packets | encoder
+|________| |______________|
+
+
+@end example
+
+@command{avconv} calls the libavformat library (containing demuxers) to read
+input files and get packets containing encoded data from them. When there are
+multiple input files, @command{avconv} tries to keep them synchronized by
+tracking lowest timestamp on any active input stream.
+
+Encoded packets are then passed to the decoder (unless streamcopy is selected
+for the stream, see further for a description). The decoder produces
+uncompressed frames (raw video/PCM audio/...) which can be processed further by
+filtering (see next section). After filtering the frames are passed to the
+encoder, which encodes them and outputs encoded packets again. Finally those are
+passed to the muxer, which writes the encoded packets to the output file.
+
+@section Filtering
+Before encoding, @command{avconv} can process raw audio and video frames using
+filters from the libavfilter library. Several chained filters form a filter
+graph. @command{avconv} distinguishes between two types of filtergraphs -
+simple and complex.
+
+@subsection Simple filtergraphs
+Simple filtergraphs are those that have exactly one input and output, both of
+the same type. In the above diagram they can be represented by simply inserting
+an additional step between decoding and encoding:
+
+@example
+ _________ ______________
+| | | |
+| decoded | | encoded data |
+| frames |\ /| packets |
+|_________| \ / |______________|
+ \ __________ /
+ simple \ | | / encoder
+ filtergraph \| filtered |/
+ | frames |
+ |__________|
+
+@end example
+
+Simple filtergraphs are configured with the per-stream @option{-filter} option
+(with @option{-vf} and @option{-af} aliases for video and audio respectively).
+A simple filtergraph for video can look for example like this:
+
+@example
+ _______ _____________ _______ ________
+| | | | | | | |
+| input | ---> | deinterlace | ---> | scale | ---> | output |
+|_______| |_____________| |_______| |________|
+
+@end example
+
+Note that some filters change frame properties but not frame contents. E.g. the
+@code{fps} filter in the example above changes number of frames, but does not
+touch the frame contents. Another example is the @code{setpts} filter, which
+only sets timestamps and otherwise passes the frames unchanged.
+
+@subsection Complex filtergraphs
+Complex filtergraphs are those which cannot be described as simply a linear
+processing chain applied to one stream. This is the case e.g. when the graph has
+more than one input and/or output, or when output stream type is different from
+input. They can be represented with the following diagram:
+
+@example
+ _________
+| |
+| input 0 |\ __________
+|_________| \ | |
+ \ _________ /| output 0 |
+ \ | | / |__________|
+ _________ \| complex | /
+| | | |/
+| input 1 |---->| filter |\
+|_________| | | \ __________
+ /| graph | \ | |
+ / | | \| output 1 |
+ _________ / |_________| |__________|
+| | /
+| input 2 |/
+|_________|
+
+@end example
+
+Complex filtergraphs are configured with the @option{-filter_complex} option.
+Note that this option is global, since a complex filtergraph by its nature
+cannot be unambiguously associated with a single stream or file.
+
+A trivial example of a complex filtergraph is the @code{overlay} filter, which
+has two video inputs and one video output, containing one video overlaid on top
+of the other. Its audio counterpart is the @code{amix} filter.
+
+@section Stream copy
+Stream copy is a mode selected by supplying the @code{copy} parameter to the
+@option{-codec} option. It makes @command{avconv} omit the decoding and encoding
+step for the specified stream, so it does only demuxing and muxing. It is useful
+for changing the container format or modifying container-level metadata. The
+diagram above will in this case simplify to this:
+
+@example
+ _______ ______________ ________
+| | | | | |
+| input | demuxer | encoded data | muxer | output |
+| file | ---------> | packets | -------> | file |
+|_______| |______________| |________|
+
+@end example
+
+Since there is no decoding or encoding, it is very fast and there is no quality
+loss. However it might not work in some cases because of many factors. Applying
+filters is obviously also impossible, since filters work on uncompressed data.
+
+@c man end DETAILED DESCRIPTION
+
@chapter Stream selection
@c man begin STREAM SELECTION
@item -y (@emph{global})
Overwrite output files without asking.
+@item -n (@emph{global})
+Immediately exit when output files already exist.
+
+@item -loop @var{number} (@emph{input})
+Set number of times input stream shall be looped. Loop 0 means no loop,
+loop -1 means infinite loop.
+
@item -c[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
@itemx -codec[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
Select an encoder (when used before an output file) or a decoder (when used
@item -ss @var{position} (@emph{input/output})
When used as an input option (before @code{-i}), seeks in this input file to
-@var{position}. When used as an output option (before an output filename),
-decodes but discards input until the timestamps reach @var{position}. This is
-slower, but more accurate.
+@var{position}. Note the in most formats it is not possible to seek exactly, so
+@command{avconv} will seek to the closest seek point before @var{position}.
+When transcoding and @option{-accurate_seek} is enabled (the default), this
+extra segment between the seek point and @var{position} will be decoded and
+discarded. When doing stream copy or when @option{-noaccurate_seek} is used, it
+will be preserved.
+
+When used as an output option (before an output filename), decodes but discards
+input until the timestamps reach @var{position}.
@var{position} may be either in seconds or in @code{hh:mm:ss[.xxx]} form.
See also the @option{-filter_complex} option if you want to create filter graphs
with multiple inputs and/or outputs.
+
+@item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
+This option is similar to @option{-filter}, the only difference is that its
+argument is the name of the file from which a filtergraph description is to be
+read.
+
@item -pre[:@var{stream_specifier}] @var{preset_name} (@emph{output,per-stream})
Specify the preset for matching stream(s).
option can actually be used to extract extradata from any stream, not just
attachments.
+@item -noautorotate
+Disable automatically rotating video based on file metadata.
+
@end table
@section Video Options
@item -vframes @var{number} (@emph{output})
Set the number of video frames to record. This is an alias for @code{-frames:v}.
@item -r[:@var{stream_specifier}] @var{fps} (@emph{input/output,per-stream})
-Set frame rate (Hz value, fraction or abbreviation), (default = 25). For output
-streams implies @code{-vsync cfr}.
+Set frame rate (Hz value, fraction or abbreviation).
+
+As an input option, ignore any timestamps stored in the file and instead
+generate timestamps assuming constant frame rate @var{fps}.
+
+As an output option, duplicate or drop input frames to achieve constant output
+frame rate @var{fps} (note that this actually causes the @code{fps} filter to be
+inserted to the end of the corresponding filtergraph).
+
@item -s[:@var{stream_specifier}] @var{size} (@emph{input/output,per-stream})
-Set frame size. The format is @samp{wxh} (default - same as source).
-The following abbreviations are recognized:
+Set frame size.
+
+As an input option, this is a shortcut for the @option{video_size} private
+option, recognized by some demuxers for which the frame size is either not
+stored in the file or is configurable -- e.g. raw video or video grabbers.
+
+As an output option, this inserts the @code{scale} video filter to the
+@emph{end} of the corresponding filtergraph. Please use the @code{scale} filter
+directly to insert it at the beginning or some other place.
+
+The format is @samp{wxh} (default - same as source). The following
+abbreviations are recognized:
@table @samp
@item sqcif
128x96
1280x720
@item hd1080
1920x1080
+@item 2kdci
+2048x1080
+@item 4kdci
+4096x2160
+@item uhd2160
+3840x2160
+@item uhd4320
+7680x4320
@end table
@item -aspect[:@var{stream_specifier}] @var{aspect} (@emph{output,per-stream})
@item -vcodec @var{codec} (@emph{output})
Set the video codec. This is an alias for @code{-codec:v}.
-@item -same_quant
-Use same quantizer as source (implies VBR).
-
-Note that this is NOT SAME QUALITY. Do not use this option unless you know you
-need it.
-@item -pass @var{n}
+@item -pass[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
Select the pass number (1 or 2). It is used to do two-pass
video encoding. The statistics of the video are recorded in the first
pass into a log file (see also the option -passlogfile),
avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
@end example
-@item -passlogfile @var{prefix} (@emph{global})
+@item -passlogfile[:@var{stream_specifier}] @var{prefix} (@emph{output,per-stream})
Set two-pass log file name prefix to @var{prefix}, the default file name
prefix is ``av2pass''. The complete file name will be
@file{PREFIX-N.log}, where N is a number specific to the output
@item -rc_override[:@var{stream_specifier}] @var{override} (@emph{output,per-stream})
rate control override for specific intervals
-@item -deinterlace
-Deinterlace pictures.
-This option is deprecated since the deinterlacing is very low quality.
-Use the yadif filter with @code{-filter:v yadif}.
@item -vstats
Dump video coding statistics to @file{vstats_HHMMSS.log}.
@item -vstats_file @var{file}
@item -copyinkf[:@var{stream_specifier}] (@emph{output,per-stream})
When doing stream copy, copy also non-key frames found at the
beginning.
+
+@item -hwaccel[:@var{stream_specifier}] @var{hwaccel} (@emph{input,per-stream})
+Use hardware acceleration to decode the matching stream(s). The allowed values
+of @var{hwaccel} are:
+@table @option
+@item none
+Do not use any hardware acceleration (the default).
+
+@item auto
+Automatically select the hardware acceleration method.
+
+@item vda
+Use Apple VDA hardware acceleration.
+
+@item vdpau
+Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration.
+
+@item dxva2
+Use DXVA2 (DirectX Video Acceleration) hardware acceleration.
+
+@item qsv
+Use the Intel QuickSync Video acceleration for video transcoding.
+
+Unlike most other values, this option does not enable accelerated decoding (that
+is used automatically whenever a qsv decoder is selected), but accelerated
+transcoding, without copying the frames into the system memory.
+
+For it to work, both the decoder and the encoder must support QSV acceleration
+and no filters must be used.
+@end table
+
+This option has no effect if the selected hwaccel is not available or not
+supported by the chosen decoder.
+
+Note that most acceleration methods are intended for playback and will not be
+faster than software decoding on modern CPUs. Additionally, @command{avconv}
+will usually need to copy the decoded frames from the GPU memory into the system
+memory, resulting in further performance loss. This option is thus mainly
+useful for testing.
+
+@item -hwaccel_device[:@var{stream_specifier}] @var{hwaccel_device} (@emph{input,per-stream})
+Select a device to use for hardware acceleration.
+
+This option only makes sense when the @option{-hwaccel} option is also
+specified. Its exact meaning depends on the specific hardware acceleration
+method chosen.
+
+@table @option
+@item vdpau
+For VDPAU, this option specifies the X11 display/screen to use. If this option
+is not specified, the value of the @var{DISPLAY} environment variable is used
+
+@item dxva2
+For DXVA2, this option should contain the number of the display adapter to use.
+If this option is not specified, the default adapter is used.
+
+@item qsv
+For QSV, this option corresponds to the values of MFX_IMPL_* . Allowed values
+are:
+@table @option
+@item auto
+@item sw
+@item hw
+@item auto_any
+@item hw_any
+@item hw2
+@item hw3
+@item hw4
+@end table
+@end table
+
+@item -hwaccels
+List all hardware acceleration methods supported in this build of avconv.
+
@end table
@section Audio Options
Disable subtitle recording.
@end table
-@section Audio/Video grab options
-
-@table @option
-@item -isync (@emph{global})
-Synchronize read on input.
-@end table
-
@section Advanced options
@table @option
avconv -i INPUT -map 0 -map -0:a:1 OUTPUT
@end example
+To pick the English audio stream:
+@example
+avconv -i INPUT -map 0:m:language:eng OUTPUT
+@end example
+
Note that using this option disables the default mappings for this output file.
@item -map_metadata[:@var{metadata_spec_out}] @var{infile}[:@var{metadata_spec_in}] (@emph{output,per-metadata})
@item -hex (@emph{global})
When dumping packets, also dump the payload.
@item -re (@emph{input})
-Read input at native frame rate. Mainly used to simulate a grab device.
+Read input at native frame rate. Mainly used to simulate a grab device
+or live input stream (e.g. when reading from a file). Should not be used
+with actual grab devices or live input streams (where it can cause packet
+loss).
@item -vsync @var{parameter}
Video sync method.
the parameter is the maximum samples per second by which the audio is changed.
-async 1 is a special case where only the start of the audio stream is corrected
without any later correction.
+This option has been deprecated. Use the @code{asyncts} audio filter instead.
@item -copyts
Copy timestamps from input to output.
@item -copytb
Copy input stream time base from input to output when stream copying.
-@item -shortest
+@item -shortest (@emph{output})
Finish encoding when the shortest input stream ends.
@item -dts_delta_threshold
Timestamp discontinuity delta threshold.
@end example
@item -bsf[:@var{stream_specifier}] @var{bitstream_filters} (@emph{output,per-stream})
-Set bitstream filters for matching streams. @var{bistream_filters} is
+Set bitstream filters for matching streams. @var{bitstream_filters} is
a comma-separated list of bitstream filters. Use the @code{-bsfs} option
to get the list of bitstream filters.
@example
avconv -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
@end example
-@item -tag[:@var{stream_specifier}] @var{codec_tag} (@emph{output,per-stream})
+@item -tag[:@var{stream_specifier}] @var{codec_tag} (@emph{input/output,per-stream})
Force a tag/fourcc for matching streams.
-@item -cpuflags mask (@emph{global})
-Set a mask that's applied to autodetected CPU flags. This option is intended
-for testing. Do not use it unless you know what you're doing.
-
@item -filter_complex @var{filtergraph} (@emph{global})
Define a complex filter graph, i.e. one with arbitrary number of inputs and/or
outputs. For simple graphs -- those with one input and one output of the same
Output link labels are referred to with @option{-map}. Unlabeled outputs are
added to the first output file.
+Note that with this option it is possible to use only lavfi sources without
+normal input files.
+
For example, to overlay an image over video
@example
avconv -i video.mkv -i image.png -filter_complex '[0:v][1:v]overlay[out]' -map
@example
avconv -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
@end example
+
+To generate 5 seconds of pure red video using lavfi @code{color} source:
+@example
+avconv -filter_complex 'color=red' -t 5 out.mkv
+@end example
+
+@item -filter_complex_script @var{filename} (@emph{global})
+This option is similar to @option{-filter_complex}, the only difference is that
+its argument is the name of the file from which a complex filtergraph
+description is to be read.
+
+@item -accurate_seek (@emph{input})
+This option enables or disables accurate seeking in input files with the
+@option{-ss} option. It is enabled by default, so seeking is accurate when
+transcoding. Use @option{-noaccurate_seek} to disable it, which may be useful
+e.g. when copying some streams and transcoding the others.
+
@end table
@c man end OPTIONS
You can put many streams of the same type in the output:
@example
-avconv -i test1.avi -i test2.avi -map 0.3 -map 0.2 -map 0.1 -map 0.0 -c copy test12.nut
+avconv -i test1.avi -i test2.avi -map 1:1 -map 1:0 -map 0:1 -map 0:0 -c copy -y test12.nut
@end example
-The resulting output file @file{test12.avi} will contain first four streams from
-the input file in reverse order.
+The resulting output file @file{test12.nut} will contain the first four streams
+from the input files in reverse order.
@item
To force CBR video output:
@c man end EXAMPLES
@include eval.texi
+@include decoders.texi
@include encoders.texi
@include demuxers.texi
@include muxers.texi