Replace leftover uses of -aframes|-dframes|-vframes with -frames:a|d|v
[libav.git] / doc / avconv.texi
CommitLineData
6291d7e4
AK
1\input texinfo @c -*- texinfo -*-
2
3@settitle avconv Documentation
4@titlepage
5@center @titlefont{avconv Documentation}
6@end titlepage
7
8@top
9
10@contents
11
12@chapter Synopsis
13
14The generic syntax is:
15
16@example
17@c man begin SYNOPSIS
eb054463 18avconv [global options] [[infile options][@option{-i} @var{infile}]]... @{[outfile options] @var{outfile}@}...
6291d7e4
AK
19@c man end
20@end example
21
22@chapter Description
23@c man begin DESCRIPTION
24
25avconv is a very fast video and audio converter that can also grab from
26a live audio/video source. It can also convert between arbitrary sample
27rates and resize video on the fly with a high quality polyphase filter.
28
d9b49e72
AK
29avconv reads from an arbitrary number of input "files" (which can be regular
30files, pipes, network streams, grabbing devices, etc.), specified by the
31@code{-i} option, and writes to an arbitrary number of output "files", which are
da9cea77 32specified by a plain output filename. Anything found on the command line which
d9b49e72
AK
33cannot be interpreted as an option is considered to be an output filename.
34
35Each input or output file can in principle contain any number of streams of
36different types (video/audio/subtitle/attachment/data). Allowed number and/or
37types of streams can be limited by the container format. Selecting, which
38streams from which inputs go into output, is done either automatically or with
39the @code{-map} option (see the Stream selection chapter).
40
41To refer to input files in options, you must use their indices (0-based). E.g.
42the first input file is @code{0}, the second is @code{1} etc. Similarly, streams
43within a file are referred to by their indices. E.g. @code{2:3} refers to the
44fourth stream in the third input file. See also the Stream specifiers chapter.
45
6291d7e4
AK
46As a general rule, options are applied to the next specified
47file. Therefore, order is important, and you can have the same
48option on the command line multiple times. Each occurrence is
49then applied to the next input or output file.
57650c70 50Exceptions from this rule are the global options (e.g. verbosity level),
eb054463 51which should be specified first.
6291d7e4 52
d9b49e72
AK
53Do not mix input and output files -- first specify all input files, then all
54output files. Also do not mix options which belong to different files. All
55options apply ONLY to the next input or output file and are reset between files.
56
6291d7e4
AK
57@itemize
58@item
59To set the video bitrate of the output file to 64kbit/s:
60@example
61avconv -i input.avi -b 64k output.avi
62@end example
63
64@item
65To force the frame rate of the output file to 24 fps:
66@example
67avconv -i input.avi -r 24 output.avi
68@end example
69
70@item
71To force the frame rate of the input file (valid for raw formats only)
72to 1 fps and the frame rate of the output file to 24 fps:
73@example
74avconv -r 1 -i input.m2v -r 24 output.avi
75@end example
76@end itemize
77
78The format option may be needed for raw input files.
79
6291d7e4
AK
80@c man end DESCRIPTION
81
2b1f105f
AK
82@chapter Detailed description
83@c man begin DETAILED DESCRIPTION
84
85The transcoding process in @command{avconv} for each output can be described by
86the following diagram:
87
88@example
3a5a9654
TG
89 _______ ______________
90| | | |
91| input | demuxer | encoded data | decoder
92| file | ---------> | packets | -----+
93|_______| |______________| |
94 v
95 _________
96 | |
97 | decoded |
98 | frames |
99 |_________|
100 ________ ______________ |
101| | | | |
102| output | <-------- | encoded data | <----+
103| file | muxer | packets | encoder
104|________| |______________|
105
2b1f105f
AK
106
107@end example
108
109@command{avconv} calls the libavformat library (containing demuxers) to read
110input files and get packets containing encoded data from them. When there are
111multiple input files, @command{avconv} tries to keep them synchronized by
112tracking lowest timestamp on any active input stream.
113
114Encoded packets are then passed to the decoder (unless streamcopy is selected
115for the stream, see further for a description). The decoder produces
116uncompressed frames (raw video/PCM audio/...) which can be processed further by
117filtering (see next section). After filtering the frames are passed to the
118encoder, which encodes them and outputs encoded packets again. Finally those are
119passed to the muxer, which writes the encoded packets to the output file.
120
121@section Filtering
122Before encoding, @command{avconv} can process raw audio and video frames using
123filters from the libavfilter library. Several chained filters form a filter
124graph. @command{avconv} distinguishes between two types of filtergraphs -
125simple and complex.
126
127@subsection Simple filtergraphs
128Simple filtergraphs are those that have exactly one input and output, both of
129the same type. In the above diagram they can be represented by simply inserting
130an additional step between decoding and encoding:
131
132@example
006c2533
LB
133 _________ ______________
134| | | |
135| decoded | | encoded data |
136| frames |\ /| packets |
137|_________| \ / |______________|
138 \ __________ /
139 simple \ | | / encoder
140 filtergraph \| filtered |/
141 | frames |
142 |__________|
2b1f105f
AK
143
144@end example
145
146Simple filtergraphs are configured with the per-stream @option{-filter} option
147(with @option{-vf} and @option{-af} aliases for video and audio respectively).
148A simple filtergraph for video can look for example like this:
149
150@example
3a5a9654
TG
151 _______ _____________ _______ ________
152| | | | | | | |
153| input | ---> | deinterlace | ---> | scale | ---> | output |
154|_______| |_____________| |_______| |________|
2b1f105f
AK
155
156@end example
157
158Note that some filters change frame properties but not frame contents. E.g. the
159@code{fps} filter in the example above changes number of frames, but does not
160touch the frame contents. Another example is the @code{setpts} filter, which
161only sets timestamps and otherwise passes the frames unchanged.
162
163@subsection Complex filtergraphs
164Complex filtergraphs are those which cannot be described as simply a linear
165processing chain applied to one stream. This is the case e.g. when the graph has
166more than one input and/or output, or when output stream type is different from
167input. They can be represented with the following diagram:
168
169@example
170 _________
171| |
172| input 0 |\ __________
173|_________| \ | |
174 \ _________ /| output 0 |
175 \ | | / |__________|
176 _________ \| complex | /
177| | | |/
178| input 1 |---->| filter |\
179|_________| | | \ __________
180 /| graph | \ | |
181 / | | \| output 1 |
182 _________ / |_________| |__________|
183| | /
184| input 2 |/
185|_________|
186
187@end example
188
189Complex filtergraphs are configured with the @option{-filter_complex} option.
190Note that this option is global, since a complex filtergraph by its nature
191cannot be unambiguously associated with a single stream or file.
192
193A trivial example of a complex filtergraph is the @code{overlay} filter, which
194has two video inputs and one video output, containing one video overlaid on top
195of the other. Its audio counterpart is the @code{amix} filter.
196
197@section Stream copy
198Stream copy is a mode selected by supplying the @code{copy} parameter to the
199@option{-codec} option. It makes @command{avconv} omit the decoding and encoding
200step for the specified stream, so it does only demuxing and muxing. It is useful
201for changing the container format or modifying container-level metadata. The
202diagram above will in this case simplify to this:
203
204@example
205 _______ ______________ ________
206| | | | | |
207| input | demuxer | encoded data | muxer | output |
208| file | ---------> | packets | -------> | file |
209|_______| |______________| |________|
210
211@end example
212
213Since there is no decoding or encoding, it is very fast and there is no quality
214loss. However it might not work in some cases because of many factors. Applying
215filters is obviously also impossible, since filters work on uncompressed data.
216
217@c man end DETAILED DESCRIPTION
218
3d4f0dab
AK
219@chapter Stream selection
220@c man begin STREAM SELECTION
221
f5bae2c6 222By default avconv tries to pick the "best" stream of each type present in input
3d4f0dab
AK
223files and add them to each output file. For video, this means the highest
224resolution, for audio the highest channel count. For subtitle it's simply the
225first subtitle stream.
226
227You can disable some of those defaults by using @code{-vn/-an/-sn} options. For
228full manual control, use the @code{-map} option, which disables the defaults just
229described.
230
231@c man end STREAM SELECTION
232
6291d7e4
AK
233@chapter Options
234@c man begin OPTIONS
235
b3dd2010 236@include avtools-common-opts.texi
6291d7e4
AK
237
238@section Main options
239
240@table @option
241
172efad7 242@item -f @var{fmt} (@emph{input/output})
d159060a
AK
243Force input or output file format. The format is normally autodetected for input
244files and guessed from file extension for output files, so this option is not
245needed in most cases.
6291d7e4 246
172efad7 247@item -i @var{filename} (@emph{input})
6291d7e4
AK
248input file name
249
172efad7 250@item -y (@emph{global})
d159060a 251Overwrite output files without asking.
6291d7e4 252
7748dd41
VG
253@item -n (@emph{global})
254Immediately exit when output files already exist.
255
16b0c929 256@item -loop @var{number} (@emph{input})
cd0e0881
AH
257Set number of times input stream shall be looped. Loop 0 means no loop,
258loop -1 means infinite loop.
16b0c929 259
172efad7
AK
260@item -c[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
261@itemx -codec[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
92f1940e
AK
262Select an encoder (when used before an output file) or a decoder (when used
263before an input file) for one or more streams. @var{codec} is the name of a
264decoder/encoder or a special value @code{copy} (output only) to indicate that
265the stream is not to be reencoded.
266
92f1940e
AK
267For example
268@example
269avconv -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
270@end example
271encodes all video streams with libx264 and copies all audio streams.
272
273For each stream, the last matching @code{c} option is applied, so
274@example
275avconv -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
276@end example
277will copy all the streams except the second video, which will be encoded with
278libx264, and the 138th audio, which will be encoded with libvorbis.
279
172efad7 280@item -t @var{duration} (@emph{output})
d159060a
AK
281Stop writing the output after its duration reaches @var{duration}.
282@var{duration} may be a number in seconds, or in @code{hh:mm:ss[.xxx]} form.
6291d7e4 283
172efad7 284@item -fs @var{limit_size} (@emph{output})
6291d7e4
AK
285Set the file size limit.
286
172efad7 287@item -ss @var{position} (@emph{input/output})
cf4976ed 288When used as an input option (before @code{-i}), seeks in this input file to
811bd078
AK
289@var{position}. Note the in most formats it is not possible to seek exactly, so
290@command{avconv} will seek to the closest seek point before @var{position}.
291When transcoding and @option{-accurate_seek} is enabled (the default), this
292extra segment between the seek point and @var{position} will be decoded and
293discarded. When doing stream copy or when @option{-noaccurate_seek} is used, it
294will be preserved.
295
296When used as an output option (before an output filename), decodes but discards
297input until the timestamps reach @var{position}.
cf4976ed
AK
298
299@var{position} may be either in seconds or in @code{hh:mm:ss[.xxx]} form.
6291d7e4 300
172efad7 301@item -itsoffset @var{offset} (@emph{input})
6291d7e4
AK
302Set the input time offset in seconds.
303@code{[-]hh:mm:ss[.xxx]} syntax is also supported.
6291d7e4
AK
304The offset is added to the timestamps of the input files.
305Specifying a positive offset means that the corresponding
d159060a 306streams are delayed by @var{offset} seconds.
6291d7e4 307
172efad7 308@item -metadata[:metadata_specifier] @var{key}=@var{value} (@emph{output,per-metadata})
6291d7e4
AK
309Set a metadata key/value pair.
310
039267f1
AK
311An optional @var{metadata_specifier} may be given to set metadata
312on streams or chapters. See @code{-map_metadata} documentation for
313details.
314
315This option overrides metadata set with @code{-map_metadata}. It is
316also possible to delete metadata by using an empty value.
317
6291d7e4
AK
318For example, for setting the title in the output file:
319@example
320avconv -i in.avi -metadata title="my title" out.flv
321@end example
322
a7b5e841 323To set the language of the first audio stream:
039267f1 324@example
a7b5e841 325avconv -i INPUT -metadata:s:a:0 language=eng OUTPUT
039267f1
AK
326@end example
327
172efad7 328@item -target @var{type} (@emph{output})
d159060a
AK
329Specify target file type (@code{vcd}, @code{svcd}, @code{dvd}, @code{dv},
330@code{dv50}). @var{type} may be prefixed with @code{pal-}, @code{ntsc-} or
331@code{film-} to use the corresponding standard. All the format options
332(bitrate, codecs, buffer sizes) are then set automatically. You can just type:
6291d7e4
AK
333
334@example
335avconv -i myfile.avi -target vcd /tmp/vcd.mpg
336@end example
337
338Nevertheless you can specify additional options as long as you know
339they do not conflict with the standard, as in:
340
341@example
342avconv -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
343@end example
344
172efad7 345@item -dframes @var{number} (@emph{output})
043b0b9f
DB
346Set the number of data frames to record. This is an obsolete alias for
347@code{-frames:d}, which you should use instead.
6291d7e4 348
172efad7 349@item -frames[:@var{stream_specifier}] @var{framecount} (@emph{output,per-stream})
96139b5e
AK
350Stop writing to the stream after @var{framecount} frames.
351
172efad7
AK
352@item -q[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
353@itemx -qscale[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
77d9c454
AK
354Use fixed quality scale (VBR). The meaning of @var{q} is
355codec-dependent.
356
667d9818 357@item -filter[:@var{stream_specifier}] @var{filter_graph} (@emph{output,per-stream})
8e5ce590
AK
358@var{filter_graph} is a description of the filter graph to apply to
359the stream. Use @code{-filters} to show all the available filters
360(including also sources and sinks).
3b266da3
AK
361
362See also the @option{-filter_complex} option if you want to create filter graphs
363with multiple inputs and/or outputs.
a4208b9b
AK
364
365@item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
366This option is similar to @option{-filter}, the only difference is that its
367argument is the name of the file from which a filtergraph description is to be
368read.
369
3ec34462
AK
370@item -pre[:@var{stream_specifier}] @var{preset_name} (@emph{output,per-stream})
371Specify the preset for matching stream(s).
8e5ce590 372
3460dd8a
AK
373@item -stats (@emph{global})
374Print encoding progress/statistics. On by default.
375
4dbc6cee
AK
376@item -attach @var{filename} (@emph{output})
377Add an attachment to the output file. This is supported by a few formats
378like Matroska for e.g. fonts used in rendering subtitles. Attachments
379are implemented as a specific type of stream, so this option will add
380a new stream to the file. It is then possible to use per-stream options
381on this stream in the usual way. Attachment streams created with this
382option will be created after all the other streams (i.e. those created
383with @code{-map} or automatic mappings).
384
385Note that for Matroska you also have to set the mimetype metadata tag:
386@example
387avconv -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
388@end example
389(assuming that the attachment stream will be third in the output file).
390
a2c0b830
AK
391@item -dump_attachment[:@var{stream_specifier}] @var{filename} (@emph{input,per-stream})
392Extract the matching attachment stream into a file named @var{filename}. If
393@var{filename} is empty, then the value of the @code{filename} metadata tag
394will be used.
395
396E.g. to extract the first attachment to a file named 'out.ttf':
397@example
398avconv -dump_attachment:t:0 out.ttf INPUT
399@end example
400To extract all attachments to files determined by the @code{filename} tag:
401@example
402avconv -dump_attachment:t "" INPUT
403@end example
404
405Technical note -- attachments are implemented as codec extradata, so this
406option can actually be used to extract extradata from any stream, not just
407attachments.
408
16302246
MS
409@item -noautorotate
410Disable automatically rotating video based on file metadata.
411
6291d7e4
AK
412@end table
413
414@section Video Options
415
416@table @option
172efad7 417@item -vframes @var{number} (@emph{output})
043b0b9f
DB
418Set the number of video frames to record. This is an obsolete alias for
419@code{-frames:v}, which you should use instead.
172efad7 420@item -r[:@var{stream_specifier}] @var{fps} (@emph{input/output,per-stream})
c9cc7629
AK
421Set frame rate (Hz value, fraction or abbreviation).
422
423As an input option, ignore any timestamps stored in the file and instead
424generate timestamps assuming constant frame rate @var{fps}.
425
426As an output option, duplicate or drop input frames to achieve constant output
427frame rate @var{fps} (note that this actually causes the @code{fps} filter to be
428inserted to the end of the corresponding filtergraph).
429
172efad7 430@item -s[:@var{stream_specifier}] @var{size} (@emph{input/output,per-stream})
4f81a507
AK
431Set frame size.
432
433As an input option, this is a shortcut for the @option{video_size} private
434option, recognized by some demuxers for which the frame size is either not
435stored in the file or is configurable -- e.g. raw video or video grabbers.
436
437As an output option, this inserts the @code{scale} video filter to the
438@emph{end} of the corresponding filtergraph. Please use the @code{scale} filter
439directly to insert it at the beginning or some other place.
440
441The format is @samp{wxh} (default - same as source). The following
442abbreviations are recognized:
6291d7e4
AK
443@table @samp
444@item sqcif
445128x96
446@item qcif
447176x144
448@item cif
449352x288
450@item 4cif
451704x576
452@item 16cif
4531408x1152
454@item qqvga
455160x120
456@item qvga
457320x240
458@item vga
459640x480
460@item svga
461800x600
462@item xga
4631024x768
464@item uxga
4651600x1200
466@item qxga
4672048x1536
468@item sxga
4691280x1024
470@item qsxga
4712560x2048
472@item hsxga
4735120x4096
474@item wvga
475852x480
476@item wxga
4771366x768
478@item wsxga
4791600x1024
480@item wuxga
4811920x1200
482@item woxga
4832560x1600
484@item wqsxga
4853200x2048
486@item wquxga
4873840x2400
488@item whsxga
4896400x4096
490@item whuxga
4917680x4800
492@item cga
493320x200
494@item ega
495640x350
496@item hd480
497852x480
498@item hd720
4991280x720
500@item hd1080
5011920x1080
e93ca480
LB
502@item 2kdci
5032048x1080
504@item 4kdci
5054096x2160
219b39a7 506@item uhd2160
e93ca480 5073840x2160
219b39a7 508@item uhd4320
e93ca480 5097680x4320
6291d7e4
AK
510@end table
511
172efad7 512@item -aspect[:@var{stream_specifier}] @var{aspect} (@emph{output,per-stream})
6291d7e4
AK
513Set the video display aspect ratio specified by @var{aspect}.
514
515@var{aspect} can be a floating point number string, or a string of the
516form @var{num}:@var{den}, where @var{num} and @var{den} are the
517numerator and denominator of the aspect ratio. For example "4:3",
518"16:9", "1.3333", and "1.7777" are valid argument values.
519
172efad7 520@item -vn (@emph{output})
6291d7e4 521Disable video recording.
4fea8959 522
172efad7 523@item -vcodec @var{codec} (@emph{output})
92f1940e 524Set the video codec. This is an alias for @code{-codec:v}.
f4ad238c 525
038c0b1e 526@item -pass[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
6291d7e4
AK
527Select the pass number (1 or 2). It is used to do two-pass
528video encoding. The statistics of the video are recorded in the first
529pass into a log file (see also the option -passlogfile),
530and in the second pass that log file is used to generate the video
531at the exact requested bitrate.
532On pass 1, you may just deactivate audio and set output to null,
533examples for Windows and Unix:
534@example
92f1940e
AK
535avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
536avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
6291d7e4
AK
537@end example
538
bbcedade 539@item -passlogfile[:@var{stream_specifier}] @var{prefix} (@emph{output,per-stream})
6291d7e4
AK
540Set two-pass log file name prefix to @var{prefix}, the default file name
541prefix is ``av2pass''. The complete file name will be
542@file{PREFIX-N.log}, where N is a number specific to the output
543stream.
544
172efad7 545@item -vf @var{filter_graph} (@emph{output})
6291d7e4
AK
546@var{filter_graph} is a description of the filter graph to apply to
547the input video.
548Use the option "-filters" to show all the available filters (including
8e5ce590 549also sources and sinks). This is an alias for @code{-filter:v}.
6291d7e4
AK
550
551@end table
552
553@section Advanced Video Options
554
555@table @option
172efad7 556@item -pix_fmt[:@var{stream_specifier}] @var{format} (@emph{input/output,per-stream})
b2254d83 557Set pixel format. Use @code{-pix_fmts} to show all the supported
6291d7e4 558pixel formats.
172efad7 559@item -sws_flags @var{flags} (@emph{input/output})
6291d7e4 560Set SwScaler flags.
6291d7e4
AK
561@item -vdt @var{n}
562Discard threshold.
6291d7e4 563
172efad7 564@item -rc_override[:@var{stream_specifier}] @var{override} (@emph{output,per-stream})
6291d7e4 565rate control override for specific intervals
6291d7e4 566
6291d7e4
AK
567@item -vstats
568Dump video coding statistics to @file{vstats_HHMMSS.log}.
569@item -vstats_file @var{file}
570Dump video coding statistics to @var{file}.
172efad7 571@item -top[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
6291d7e4
AK
572top=1/bottom=0/auto=-1 field first
573@item -dc @var{precision}
574Intra_dc_precision.
172efad7 575@item -vtag @var{fourcc/tag} (@emph{output})
013887eb 576Force video tag/fourcc. This is an alias for @code{-tag:v}.
172efad7 577@item -qphist (@emph{global})
6291d7e4 578Show QP histogram.
172efad7 579@item -force_key_frames[:@var{stream_specifier}] @var{time}[,@var{time}...] (@emph{output,per-stream})
6291d7e4
AK
580Force key frames at the specified timestamps, more precisely at the first
581frames after each specified time.
582This option can be useful to ensure that a seek point is present at a
583chapter mark or any other designated place in the output file.
584The timestamps must be specified in ascending order.
a2aeeb22
AK
585
586@item -copyinkf[:@var{stream_specifier}] (@emph{output,per-stream})
587When doing stream copy, copy also non-key frames found at the
588beginning.
07fd0a22
AK
589
590@item -hwaccel[:@var{stream_specifier}] @var{hwaccel} (@emph{input,per-stream})
591Use hardware acceleration to decode the matching stream(s). The allowed values
592of @var{hwaccel} are:
593@table @option
594@item none
595Do not use any hardware acceleration (the default).
596
597@item auto
598Automatically select the hardware acceleration method.
7671dd7c 599
1839fafa
AK
600@item vda
601Use Apple VDA hardware acceleration.
602
7671dd7c
AK
603@item vdpau
604Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration.
35177ba7
HL
605
606@item dxva2
607Use DXVA2 (DirectX Video Acceleration) hardware acceleration.
fb472e1a
AK
608
609@item qsv
610Use the Intel QuickSync Video acceleration for video transcoding.
611
612Unlike most other values, this option does not enable accelerated decoding (that
613is used automatically whenever a qsv decoder is selected), but accelerated
614transcoding, without copying the frames into the system memory.
615
616For it to work, both the decoder and the encoder must support QSV acceleration
617and no filters must be used.
07fd0a22
AK
618@end table
619
620This option has no effect if the selected hwaccel is not available or not
621supported by the chosen decoder.
622
623Note that most acceleration methods are intended for playback and will not be
624faster than software decoding on modern CPUs. Additionally, @command{avconv}
625will usually need to copy the decoded frames from the GPU memory into the system
626memory, resulting in further performance loss. This option is thus mainly
627useful for testing.
628
629@item -hwaccel_device[:@var{stream_specifier}] @var{hwaccel_device} (@emph{input,per-stream})
630Select a device to use for hardware acceleration.
631
632This option only makes sense when the @option{-hwaccel} option is also
633specified. Its exact meaning depends on the specific hardware acceleration
634method chosen.
7671dd7c
AK
635
636@table @option
637@item vdpau
638For VDPAU, this option specifies the X11 display/screen to use. If this option
639is not specified, the value of the @var{DISPLAY} environment variable is used
35177ba7
HL
640
641@item dxva2
642For DXVA2, this option should contain the number of the display adapter to use.
643If this option is not specified, the default adapter is used.
fb472e1a
AK
644
645@item qsv
41ed7ab4 646For QSV, this option corresponds to the values of MFX_IMPL_* . Allowed values
fb472e1a
AK
647are:
648@table @option
649@item auto
650@item sw
651@item hw
652@item auto_any
653@item hw_any
654@item hw2
655@item hw3
656@item hw4
657@end table
7671dd7c 658@end table
c23999be
TG
659
660@item -hwaccels
661List all hardware acceleration methods supported in this build of avconv.
662
6291d7e4
AK
663@end table
664
665@section Audio Options
666
667@table @option
172efad7 668@item -aframes @var{number} (@emph{output})
043b0b9f
DB
669Set the number of audio frames to record. This is an obsolete alias for
670@code{-frames:a}, which you should use instead.
172efad7 671@item -ar[:@var{stream_specifier}] @var{freq} (@emph{input/output,per-stream})
6291d7e4
AK
672Set the audio sampling frequency. For output streams it is set by
673default to the frequency of the corresponding input stream. For input
674streams this option only makes sense for audio grabbing devices and raw
675demuxers and is mapped to the corresponding demuxer options.
172efad7 676@item -aq @var{q} (@emph{output})
77d9c454 677Set the audio quality (codec-specific, VBR). This is an alias for -q:a.
172efad7 678@item -ac[:@var{stream_specifier}] @var{channels} (@emph{input/output,per-stream})
6291d7e4
AK
679Set the number of audio channels. For output streams it is set by
680default to the number of input audio channels. For input streams
681this option only makes sense for audio grabbing devices and raw demuxers
682and is mapped to the corresponding demuxer options.
172efad7 683@item -an (@emph{output})
6291d7e4 684Disable audio recording.
172efad7 685@item -acodec @var{codec} (@emph{input/output})
92f1940e 686Set the audio codec. This is an alias for @code{-codec:a}.
172efad7 687@item -sample_fmt[:@var{stream_specifier}] @var{sample_fmt} (@emph{output,per-stream})
2b56db58 688Set the audio sample format. Use @code{-sample_fmts} to get a list
05bffc12 689of supported sample formats.
369cb092
AK
690@item -af @var{filter_graph} (@emph{output})
691@var{filter_graph} is a description of the filter graph to apply to
692the input audio.
693Use the option "-filters" to show all the available filters (including
694also sources and sinks). This is an alias for @code{-filter:a}.
6291d7e4
AK
695@end table
696
697@section Advanced Audio options:
698
699@table @option
172efad7 700@item -atag @var{fourcc/tag} (@emph{output})
013887eb 701Force audio tag/fourcc. This is an alias for @code{-tag:a}.
6291d7e4
AK
702@end table
703
704@section Subtitle options:
705
706@table @option
172efad7 707@item -scodec @var{codec} (@emph{input/output})
92f1940e 708Set the subtitle codec. This is an alias for @code{-codec:s}.
172efad7 709@item -sn (@emph{output})
6291d7e4 710Disable subtitle recording.
6291d7e4
AK
711@end table
712
6291d7e4
AK
713@section Advanced options
714
715@table @option
3b266da3 716@item -map [-]@var{input_file_id}[:@var{stream_specifier}][,@var{sync_file_id}[:@var{stream_specifier}]] | @var{[linklabel]} (@emph{output})
6291d7e4 717
8d2e4a7e 718Designate one or more input streams as a source for the output file. Each input
6291d7e4
AK
719stream is identified by the input file index @var{input_file_id} and
720the input stream index @var{input_stream_id} within the input
8d2e4a7e 721file. Both indices start at 0. If specified,
172efad7 722@var{sync_file_id}:@var{stream_specifier} sets which input stream
6291d7e4
AK
723is used as a presentation sync reference.
724
3d4f0dab 725The first @code{-map} option on the command line specifies the
6291d7e4
AK
726source for output stream 0, the second @code{-map} option specifies
727the source for output stream 1, etc.
728
8d2e4a7e
AK
729A @code{-} character before the stream identifier creates a "negative" mapping.
730It disables matching streams from already created mappings.
731
3b266da3
AK
732An alternative @var{[linklabel]} form will map outputs from complex filter
733graphs (see the @option{-filter_complex} option) to the output file.
734@var{linklabel} must correspond to a defined output link label in the graph.
735
8d2e4a7e
AK
736For example, to map ALL streams from the first input file to output
737@example
f5bae2c6 738avconv -i INPUT -map 0 output
8d2e4a7e
AK
739@end example
740
6291d7e4 741For example, if you have two audio streams in the first input file,
8d2e4a7e 742these streams are identified by "0:0" and "0:1". You can use
3d4f0dab 743@code{-map} to select which streams to place in an output file. For
6291d7e4
AK
744example:
745@example
8d2e4a7e 746avconv -i INPUT -map 0:1 out.wav
6291d7e4 747@end example
8d2e4a7e 748will map the input stream in @file{INPUT} identified by "0:1" to
6291d7e4
AK
749the (single) output stream in @file{out.wav}.
750
751For example, to select the stream with index 2 from input file
8d2e4a7e
AK
752@file{a.mov} (specified by the identifier "0:2"), and stream with
753index 6 from input @file{b.mov} (specified by the identifier "1:6"),
6291d7e4
AK
754and copy them to the output file @file{out.mov}:
755@example
92f1940e 756avconv -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
8d2e4a7e
AK
757@end example
758
759To select all video and the third audio stream from an input file:
760@example
761avconv -i INPUT -map 0:v -map 0:a:2 OUTPUT
762@end example
763
764To map all the streams except the second audio, use negative mappings
765@example
766avconv -i INPUT -map 0 -map -0:a:1 OUTPUT
6291d7e4
AK
767@end example
768
481a3667
AK
769To pick the English audio stream:
770@example
771avconv -i INPUT -map 0:m:language:eng OUTPUT
772@end example
773
3d4f0dab 774Note that using this option disables the default mappings for this output file.
6291d7e4 775
a7b5e841 776@item -map_metadata[:@var{metadata_spec_out}] @var{infile}[:@var{metadata_spec_in}] (@emph{output,per-metadata})
e6e6060c
AK
777Set metadata information of the next output file from @var{infile}. Note that
778those are file indices (zero-based), not filenames.
a7b5e841
AK
779Optional @var{metadata_spec_in/out} parameters specify, which metadata to copy.
780A metadata specifier can have the following forms:
781@table @option
782@item @var{g}
783global metadata, i.e. metadata that applies to the whole file
784
785@item @var{s}[:@var{stream_spec}]
786per-stream metadata. @var{stream_spec} is a stream specifier as described
787in the @ref{Stream specifiers} chapter. In an input metadata specifier, the first
788matching stream is copied from. In an output metadata specifier, all matching
789streams are copied to.
790
791@item @var{c}:@var{chapter_index}
792per-chapter metadata. @var{chapter_index} is the zero-based chapter index.
793
794@item @var{p}:@var{program_index}
795per-program metadata. @var{program_index} is the zero-based program index.
796@end table
797If metadata specifier is omitted, it defaults to global.
6291d7e4 798
e6e6060c 799By default, global metadata is copied from the first input file,
6291d7e4
AK
800per-stream and per-chapter metadata is copied along with streams/chapters. These
801default mappings are disabled by creating any mapping of the relevant type. A negative
802file index can be used to create a dummy mapping that just disables automatic copying.
803
804For example to copy metadata from the first stream of the input file to global metadata
805of the output file:
806@example
e6e6060c 807avconv -i in.ogg -map_metadata 0:s:0 out.mp3
6291d7e4 808@end example
a7b5e841
AK
809
810To do the reverse, i.e. copy global metadata to all audio streams:
811@example
812avconv -i in.mkv -map_metadata:s:a 0:g out.mkv
813@end example
814Note that simple @code{0} would work as well in this example, since global
815metadata is assumed by default.
816
172efad7 817@item -map_chapters @var{input_file_index} (@emph{output})
b9aac90b
AK
818Copy chapters from input file with index @var{input_file_index} to the next
819output file. If no chapter mapping is specified, then chapters are copied from
820the first input file with at least one chapter. Use a negative file index to
821disable any chapter copying.
6291d7e4
AK
822@item -debug
823Print specific debug info.
172efad7 824@item -benchmark (@emph{global})
6291d7e4
AK
825Show benchmarking information at the end of an encode.
826Shows CPU time used and maximum memory consumption.
827Maximum memory consumption is not supported on all systems,
828it will usually display as 0 if not supported.
5aa3fcec
AK
829@item -timelimit @var{duration} (@emph{global})
830Exit after avconv has been running for @var{duration} seconds.
172efad7 831@item -dump (@emph{global})
d159060a 832Dump each input packet to stderr.
172efad7 833@item -hex (@emph{global})
6291d7e4 834When dumping packets, also dump the payload.
172efad7 835@item -re (@emph{input})
205a4502
MS
836Read input at native frame rate. Mainly used to simulate a grab device
837or live input stream (e.g. when reading from a file). Should not be used
838with actual grab devices or live input streams (where it can cause packet
839loss).
6291d7e4
AK
840@item -vsync @var{parameter}
841Video sync method.
842
843@table @option
e8c04f62 844@item passthrough
6291d7e4 845Each frame is passed with its timestamp from the demuxer to the muxer.
e8c04f62 846@item cfr
6291d7e4
AK
847Frames will be duplicated and dropped to achieve exactly the requested
848constant framerate.
e8c04f62 849@item vfr
6291d7e4
AK
850Frames are passed through with their timestamp or dropped so as to
851prevent 2 frames from having the same timestamp.
e8c04f62 852@item auto
6291d7e4
AK
853Chooses between 1 and 2 depending on muxer capabilities. This is the
854default method.
855@end table
856
857With -map you can select from which stream the timestamps should be
858taken. You can leave either video or audio unchanged and sync the
859remaining stream(s) to the unchanged one.
860
861@item -async @var{samples_per_second}
862Audio sync method. "Stretches/squeezes" the audio stream to match the timestamps,
863the parameter is the maximum samples per second by which the audio is changed.
864-async 1 is a special case where only the start of the audio stream is corrected
865without any later correction.
6eeb9a04 866This option has been deprecated. Use the @code{asyncts} audio filter instead.
6291d7e4
AK
867@item -copyts
868Copy timestamps from input to output.
869@item -copytb
870Copy input stream time base from input to output when stream copying.
3c0df905 871@item -shortest (@emph{output})
6291d7e4
AK
872Finish encoding when the shortest input stream ends.
873@item -dts_delta_threshold
874Timestamp discontinuity delta threshold.
172efad7 875@item -muxdelay @var{seconds} (@emph{input})
6291d7e4 876Set the maximum demux-decode delay.
172efad7 877@item -muxpreload @var{seconds} (@emph{input})
6291d7e4 878Set the initial demux-decode delay.
172efad7 879@item -streamid @var{output-stream-index}:@var{new-value} (@emph{output})
6291d7e4
AK
880Assign a new stream-id value to an output stream. This option should be
881specified prior to the output filename to which it applies.
882For the situation where multiple output files exist, a streamid
883may be reassigned to a different value.
884
885For example, to set the stream 0 PID to 33 and the stream 1 PID to 36 for
886an output mpegts file:
887@example
888avconv -i infile -streamid 0:33 -streamid 1:36 out.ts
889@end example
d821cbe2 890
172efad7 891@item -bsf[:@var{stream_specifier}] @var{bitstream_filters} (@emph{output,per-stream})
41ed7ab4 892Set bitstream filters for matching streams. @var{bitstream_filters} is
d821cbe2
AK
893a comma-separated list of bitstream filters. Use the @code{-bsfs} option
894to get the list of bitstream filters.
895@example
d6a77e2b 896avconv -i h264.mp4 -c:v copy -bsf:v h264_mp4toannexb -an out.h264
d821cbe2
AK
897@end example
898@example
d6a77e2b 899avconv -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
d821cbe2 900@end example
013887eb 901
746dca48 902@item -tag[:@var{stream_specifier}] @var{codec_tag} (@emph{input/output,per-stream})
013887eb 903Force a tag/fourcc for matching streams.
4138cd29 904
3b266da3
AK
905@item -filter_complex @var{filtergraph} (@emph{global})
906Define a complex filter graph, i.e. one with arbitrary number of inputs and/or
907outputs. For simple graphs -- those with one input and one output of the same
908type -- see the @option{-filter} options. @var{filtergraph} is a description of
909the filter graph, as described in @ref{Filtergraph syntax}.
910
911Input link labels must refer to input streams using the
912@code{[file_index:stream_specifier]} syntax (i.e. the same as @option{-map}
913uses). If @var{stream_specifier} matches multiple streams, the first one will be
914used. An unlabeled input will be connected to the first unused input stream of
915the matching type.
916
917Output link labels are referred to with @option{-map}. Unlabeled outputs are
918added to the first output file.
919
ab296097
AK
920Note that with this option it is possible to use only lavfi sources without
921normal input files.
922
3b266da3
AK
923For example, to overlay an image over video
924@example
925avconv -i video.mkv -i image.png -filter_complex '[0:v][1:v]overlay[out]' -map
926'[out]' out.mkv
927@end example
928Here @code{[0:v]} refers to the first video stream in the first input file,
929which is linked to the first (main) input of the overlay filter. Similarly the
930first video stream in the second input is linked to the second (overlay) input
931of overlay.
932
933Assuming there is only one video stream in each input file, we can omit input
934labels, so the above is equivalent to
935@example
936avconv -i video.mkv -i image.png -filter_complex 'overlay[out]' -map
937'[out]' out.mkv
938@end example
939
940Furthermore we can omit the output label and the single output from the filter
941graph will be added to the output file automatically, so we can simply write
942@example
943avconv -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
944@end example
ab296097
AK
945
946To generate 5 seconds of pure red video using lavfi @code{color} source:
947@example
948avconv -filter_complex 'color=red' -t 5 out.mkv
949@end example
a4208b9b
AK
950
951@item -filter_complex_script @var{filename} (@emph{global})
952This option is similar to @option{-filter_complex}, the only difference is that
953its argument is the name of the file from which a complex filtergraph
954description is to be read.
955
811bd078
AK
956@item -accurate_seek (@emph{input})
957This option enables or disables accurate seeking in input files with the
958@option{-ss} option. It is enabled by default, so seeking is accurate when
959transcoding. Use @option{-noaccurate_seek} to disable it, which may be useful
960e.g. when copying some streams and transcoding the others.
961
398f015f
AK
962@item -max_muxing_queue_size @var{packets} (@emph{output,per-stream})
963When transcoding audio and/or video streams, avconv will not begin writing into
964the output until it has one packet for each such stream. While waiting for that
965to happen, packets for other streams are buffered. This option sets the size of
966this buffer, in packets, for the matching output stream.
967
968The default value of this option should be high enough for most uses, so only
969touch this option if you are sure that you need it.
970
6291d7e4 971@end table
7478ab5a 972@c man end OPTIONS
6291d7e4 973
6291d7e4
AK
974@chapter Tips
975@c man begin TIPS
976
977@itemize
978@item
979For streaming at very low bitrate application, use a low frame rate
980and a small GOP size. This is especially true for RealVideo where
981the Linux player does not seem to be very fast, so it can miss
982frames. An example is:
983
984@example
985avconv -g 3 -r 3 -t 10 -b 50k -s qcif -f rv10 /tmp/b.rm
986@end example
987
988@item
989The parameter 'q' which is displayed while encoding is the current
990quantizer. The value 1 indicates that a very good quality could
991be achieved. The value 31 indicates the worst quality. If q=31 appears
992too often, it means that the encoder cannot compress enough to meet
993your bitrate. You must either increase the bitrate, decrease the
994frame rate or decrease the frame size.
995
996@item
997If your computer is not fast enough, you can speed up the
998compression at the expense of the compression ratio. You can use
3607dc2b 999'-me zero' to speed up motion estimation, and '-g 0' to disable
6291d7e4
AK
1000motion estimation completely (you have only I-frames, which means it
1001is about as good as JPEG compression).
1002
1003@item
1004To have very low audio bitrates, reduce the sampling frequency
1005(down to 22050 Hz for MPEG audio, 22050 or 11025 for AC-3).
1006
1007@item
1008To have a constant quality (but a variable bitrate), use the option
1009'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
1010quality).
1011
6291d7e4
AK
1012@end itemize
1013@c man end TIPS
1014
1015@chapter Examples
1016@c man begin EXAMPLES
1017
3ec34462
AK
1018@section Preset files
1019
1020A preset file contains a sequence of @var{option=value} pairs, one for
1021each line, specifying a sequence of options which can be specified also on
1022the command line. Lines starting with the hash ('#') character are ignored and
1023are used to provide comments. Empty lines are also ignored. Check the
8096fdf0 1024@file{presets} directory in the Libav source tree for examples.
3ec34462
AK
1025
1026Preset files are specified with the @code{pre} option, this option takes a
1027preset name as input. Avconv searches for a file named @var{preset_name}.avpreset in
1028the directories @file{$AVCONV_DATADIR} (if set), and @file{$HOME/.avconv}, and in
1029the data directory defined at configuration time (usually @file{$PREFIX/share/avconv})
1030in that order. For example, if the argument is @code{libx264-max}, it will
1031search for the file @file{libx264-max.avpreset}.
1032
6291d7e4
AK
1033@section Video and Audio grabbing
1034
1035If you specify the input format and device then avconv can grab video
1036and audio directly.
1037
1038@example
1039avconv -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
1040@end example
1041
1042Note that you must activate the right video source and channel before
1043launching avconv with any TV viewer such as
1044@uref{http://linux.bytesex.org/xawtv/, xawtv} by Gerd Knorr. You also
1045have to set the audio recording levels correctly with a
1046standard mixer.
1047
1048@section X11 grabbing
1049
1050Grab the X11 display with avconv via
1051
1052@example
1053avconv -f x11grab -s cif -r 25 -i :0.0 /tmp/out.mpg
1054@end example
1055
10560.0 is display.screen number of your X11 server, same as
1057the DISPLAY environment variable.
1058
1059@example
1060avconv -f x11grab -s cif -r 25 -i :0.0+10,20 /tmp/out.mpg
1061@end example
1062
10630.0 is display.screen number of your X11 server, same as the DISPLAY environment
1064variable. 10 is the x-offset and 20 the y-offset for the grabbing.
1065
1066@section Video and Audio file format conversion
1067
1068Any supported file format and protocol can serve as input to avconv:
1069
1070Examples:
1071@itemize
1072@item
1073You can use YUV files as input:
1074
1075@example
1076avconv -i /tmp/test%d.Y /tmp/out.mpg
1077@end example
1078
1079It will use the files:
1080@example
1081/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
1082/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
1083@end example
1084
1085The Y files use twice the resolution of the U and V files. They are
1086raw files, without header. They can be generated by all decent video
1087decoders. You must specify the size of the image with the @option{-s} option
1088if avconv cannot guess it.
1089
1090@item
1091You can input from a raw YUV420P file:
1092
1093@example
1094avconv -i /tmp/test.yuv /tmp/out.avi
1095@end example
1096
1097test.yuv is a file containing raw YUV planar data. Each frame is composed
1098of the Y plane followed by the U and V planes at half vertical and
1099horizontal resolution.
1100
1101@item
1102You can output to a raw YUV420P file:
1103
1104@example
1105avconv -i mydivx.avi hugefile.yuv
1106@end example
1107
1108@item
1109You can set several input files and output files:
1110
1111@example
1112avconv -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
1113@end example
1114
1115Converts the audio file a.wav and the raw YUV video file a.yuv
1116to MPEG file a.mpg.
1117
1118@item
1119You can also do audio and video conversions at the same time:
1120
1121@example
1122avconv -i /tmp/a.wav -ar 22050 /tmp/a.mp2
1123@end example
1124
1125Converts a.wav to MPEG audio at 22050 Hz sample rate.
1126
1127@item
1128You can encode to several formats at the same time and define a
1129mapping from input stream to output streams:
1130
1131@example
64db1a82 1132avconv -i /tmp/a.wav -map 0:a -b 64k /tmp/a.mp2 -map 0:a -b 128k /tmp/b.mp2
6291d7e4
AK
1133@end example
1134
1135Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
1136file:index' specifies which input stream is used for each output
1137stream, in the order of the definition of output streams.
1138
1139@item
1140You can transcode decrypted VOBs:
1141
1142@example
64db1a82 1143avconv -i snatch_1.vob -f avi -c:v mpeg4 -b:v 800k -g 300 -bf 2 -c:a libmp3lame -b:a 128k snatch.avi
6291d7e4
AK
1144@end example
1145
1146This is a typical DVD ripping example; the input is a VOB file, the
1147output an AVI file with MPEG-4 video and MP3 audio. Note that in this
1148command we use B-frames so the MPEG-4 stream is DivX5 compatible, and
1149GOP size is 300 which means one intra frame every 10 seconds for 29.97fps
1150input video. Furthermore, the audio stream is MP3-encoded so you need
1151to enable LAME support by passing @code{--enable-libmp3lame} to configure.
1152The mapping is particularly useful for DVD transcoding
1153to get the desired audio language.
1154
1155NOTE: To see the supported input formats, use @code{avconv -formats}.
1156
1157@item
1158You can extract images from a video, or create a video from many images:
1159
1160For extracting images from a video:
1161@example
1162avconv -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
1163@end example
1164
1165This will extract one video frame per second from the video and will
1166output them in files named @file{foo-001.jpeg}, @file{foo-002.jpeg},
1167etc. Images will be rescaled to fit the new WxH values.
1168
1169If you want to extract just a limited number of frames, you can use the
043b0b9f
DB
1170above command in combination with the @code{-frames:v} or @code{-t} option,
1171or in combination with -ss to start extracting from a certain point in time.
6291d7e4
AK
1172
1173For creating a video from many images:
1174@example
1175avconv -f image2 -i foo-%03d.jpeg -r 12 -s WxH foo.avi
1176@end example
1177
1178The syntax @code{foo-%03d.jpeg} specifies to use a decimal number
1179composed of three digits padded with zeroes to express the sequence
1180number. It is the same syntax supported by the C printf function, but
1181only formats accepting a normal integer are suitable.
1182
1183@item
1184You can put many streams of the same type in the output:
1185
1186@example
775a0b04 1187avconv -i test1.avi -i test2.avi -map 1:1 -map 1:0 -map 0:1 -map 0:0 -c copy -y test12.nut
6291d7e4
AK
1188@end example
1189
775a0b04
DB
1190The resulting output file @file{test12.nut} will contain the first four streams
1191from the input files in reverse order.
6291d7e4 1192
4fea8959
AK
1193@item
1194To force CBR video output:
1195@example
1196avconv -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
1197@end example
1198
1199@item
1200The four options lmin, lmax, mblmin and mblmax use 'lambda' units,
1201but you may use the QP2LAMBDA constant to easily convert from 'q' units:
1202@example
1203avconv -i src.ext -lmax 21*QP2LAMBDA dst.ext
1204@end example
1205
6291d7e4
AK
1206@end itemize
1207@c man end EXAMPLES
1208
1209@include eval.texi
a17ab0e4 1210@include decoders.texi
6291d7e4
AK
1211@include encoders.texi
1212@include demuxers.texi
1213@include muxers.texi
1214@include indevs.texi
1215@include outdevs.texi
1216@include protocols.texi
1217@include bitstream_filters.texi
1218@include filters.texi
1219@include metadata.texi
1220
1221@ignore
1222
1223@setfilename avconv
1224@settitle avconv video converter
1225
1226@c man begin SEEALSO
2e87b4c5 1227avplay(1), avprobe(1) and the Libav HTML documentation
6291d7e4
AK
1228@c man end
1229
1230@c man begin AUTHORS
1231The Libav developers
1232@c man end
1233
1234@end ignore
1235
1236@bye