X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Favconv.texi;h=6aaf445d55a2b3fd5c08de8723fbb4e1cc10236c;hb=2e5bde956519ae19cedfa482e199518e495bcaf5;hp=2ebfe9fe4475f81c75b48be0b1e7dee892730cca;hpb=c9cc76290f8139a012a12efe7e581276b8bd8dff;p=ffmpeg diff --git a/doc/avconv.texi b/doc/avconv.texi index 2ebfe9fe447..6aaf445d55a 100644 --- a/doc/avconv.texi +++ b/doc/avconv.texi @@ -79,6 +79,143 @@ The format option may be needed for raw input files. @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 @@ -113,6 +250,13 @@ input file name @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 @@ -142,9 +286,15 @@ Set the file size limit. @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. @@ -210,6 +360,12 @@ the stream. Use @code{-filters} to show all the available filters 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). @@ -249,6 +405,9 @@ Technical note -- attachments are implemented as codec extradata, so this 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 @@ -338,6 +497,14 @@ abbreviations are recognized: 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}) @@ -353,13 +520,8 @@ Disable video recording. @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), @@ -372,7 +534,7 @@ avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL 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 @@ -400,10 +562,6 @@ Discard threshold. @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} @@ -426,6 +584,80 @@ The timestamps must be specified in ascending order. @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 valus 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 @@ -475,13 +707,6 @@ Set the subtitle codec. This is an alias for @code{-codec:s}. 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 @@ -538,6 +763,11 @@ To map all the streams except the second audio, use negative mappings 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}) @@ -600,7 +830,10 @@ Dump each input packet to stderr. @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. @@ -632,7 +865,7 @@ This option has been deprecated. Use the @code{asyncts} audio filter instead. 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. @@ -663,13 +896,9 @@ avconv -i h264.mp4 -c:v copy -bsf:v h264_mp4toannexb -an out.h264 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 @@ -685,6 +914,9 @@ the matching type. 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 @@ -707,6 +939,23 @@ graph will be added to the output file automatically, so we can simply write @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 @@ -923,11 +1172,11 @@ only formats accepting a normal integer are suitable. 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: @@ -946,6 +1195,7 @@ avconv -i src.ext -lmax 21*QP2LAMBDA dst.ext @c man end EXAMPLES @include eval.texi +@include decoders.texi @include encoders.texi @include demuxers.texi @include muxers.texi