avconv_opt: Add an option that lists all supported hwaccels
[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
172efad7
AK
256@item -c[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
257@itemx -codec[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
92f1940e
AK
258Select an encoder (when used before an output file) or a decoder (when used
259before an input file) for one or more streams. @var{codec} is the name of a
260decoder/encoder or a special value @code{copy} (output only) to indicate that
261the stream is not to be reencoded.
262
92f1940e
AK
263For example
264@example
265avconv -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
266@end example
267encodes all video streams with libx264 and copies all audio streams.
268
269For each stream, the last matching @code{c} option is applied, so
270@example
271avconv -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
272@end example
273will copy all the streams except the second video, which will be encoded with
274libx264, and the 138th audio, which will be encoded with libvorbis.
275
172efad7 276@item -t @var{duration} (@emph{output})
d159060a
AK
277Stop writing the output after its duration reaches @var{duration}.
278@var{duration} may be a number in seconds, or in @code{hh:mm:ss[.xxx]} form.
6291d7e4 279
172efad7 280@item -fs @var{limit_size} (@emph{output})
6291d7e4
AK
281Set the file size limit.
282
172efad7 283@item -ss @var{position} (@emph{input/output})
cf4976ed 284When used as an input option (before @code{-i}), seeks in this input file to
811bd078
AK
285@var{position}. Note the in most formats it is not possible to seek exactly, so
286@command{avconv} will seek to the closest seek point before @var{position}.
287When transcoding and @option{-accurate_seek} is enabled (the default), this
288extra segment between the seek point and @var{position} will be decoded and
289discarded. When doing stream copy or when @option{-noaccurate_seek} is used, it
290will be preserved.
291
292When used as an output option (before an output filename), decodes but discards
293input until the timestamps reach @var{position}.
cf4976ed
AK
294
295@var{position} may be either in seconds or in @code{hh:mm:ss[.xxx]} form.
6291d7e4 296
172efad7 297@item -itsoffset @var{offset} (@emph{input})
6291d7e4
AK
298Set the input time offset in seconds.
299@code{[-]hh:mm:ss[.xxx]} syntax is also supported.
6291d7e4
AK
300The offset is added to the timestamps of the input files.
301Specifying a positive offset means that the corresponding
d159060a 302streams are delayed by @var{offset} seconds.
6291d7e4 303
172efad7 304@item -metadata[:metadata_specifier] @var{key}=@var{value} (@emph{output,per-metadata})
6291d7e4
AK
305Set a metadata key/value pair.
306
039267f1
AK
307An optional @var{metadata_specifier} may be given to set metadata
308on streams or chapters. See @code{-map_metadata} documentation for
309details.
310
311This option overrides metadata set with @code{-map_metadata}. It is
312also possible to delete metadata by using an empty value.
313
6291d7e4
AK
314For example, for setting the title in the output file:
315@example
316avconv -i in.avi -metadata title="my title" out.flv
317@end example
318
a7b5e841 319To set the language of the first audio stream:
039267f1 320@example
a7b5e841 321avconv -i INPUT -metadata:s:a:0 language=eng OUTPUT
039267f1
AK
322@end example
323
172efad7 324@item -target @var{type} (@emph{output})
d159060a
AK
325Specify target file type (@code{vcd}, @code{svcd}, @code{dvd}, @code{dv},
326@code{dv50}). @var{type} may be prefixed with @code{pal-}, @code{ntsc-} or
327@code{film-} to use the corresponding standard. All the format options
328(bitrate, codecs, buffer sizes) are then set automatically. You can just type:
6291d7e4
AK
329
330@example
331avconv -i myfile.avi -target vcd /tmp/vcd.mpg
332@end example
333
334Nevertheless you can specify additional options as long as you know
335they do not conflict with the standard, as in:
336
337@example
338avconv -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
339@end example
340
172efad7 341@item -dframes @var{number} (@emph{output})
96139b5e 342Set the number of data frames to record. This is an alias for @code{-frames:d}.
6291d7e4 343
172efad7 344@item -frames[:@var{stream_specifier}] @var{framecount} (@emph{output,per-stream})
96139b5e
AK
345Stop writing to the stream after @var{framecount} frames.
346
172efad7
AK
347@item -q[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
348@itemx -qscale[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
77d9c454
AK
349Use fixed quality scale (VBR). The meaning of @var{q} is
350codec-dependent.
351
667d9818 352@item -filter[:@var{stream_specifier}] @var{filter_graph} (@emph{output,per-stream})
8e5ce590
AK
353@var{filter_graph} is a description of the filter graph to apply to
354the stream. Use @code{-filters} to show all the available filters
355(including also sources and sinks).
3b266da3
AK
356
357See also the @option{-filter_complex} option if you want to create filter graphs
358with multiple inputs and/or outputs.
a4208b9b
AK
359
360@item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
361This option is similar to @option{-filter}, the only difference is that its
362argument is the name of the file from which a filtergraph description is to be
363read.
364
3ec34462
AK
365@item -pre[:@var{stream_specifier}] @var{preset_name} (@emph{output,per-stream})
366Specify the preset for matching stream(s).
8e5ce590 367
3460dd8a
AK
368@item -stats (@emph{global})
369Print encoding progress/statistics. On by default.
370
4dbc6cee
AK
371@item -attach @var{filename} (@emph{output})
372Add an attachment to the output file. This is supported by a few formats
373like Matroska for e.g. fonts used in rendering subtitles. Attachments
374are implemented as a specific type of stream, so this option will add
375a new stream to the file. It is then possible to use per-stream options
376on this stream in the usual way. Attachment streams created with this
377option will be created after all the other streams (i.e. those created
378with @code{-map} or automatic mappings).
379
380Note that for Matroska you also have to set the mimetype metadata tag:
381@example
382avconv -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
383@end example
384(assuming that the attachment stream will be third in the output file).
385
a2c0b830
AK
386@item -dump_attachment[:@var{stream_specifier}] @var{filename} (@emph{input,per-stream})
387Extract the matching attachment stream into a file named @var{filename}. If
388@var{filename} is empty, then the value of the @code{filename} metadata tag
389will be used.
390
391E.g. to extract the first attachment to a file named 'out.ttf':
392@example
393avconv -dump_attachment:t:0 out.ttf INPUT
394@end example
395To extract all attachments to files determined by the @code{filename} tag:
396@example
397avconv -dump_attachment:t "" INPUT
398@end example
399
400Technical note -- attachments are implemented as codec extradata, so this
401option can actually be used to extract extradata from any stream, not just
402attachments.
403
16302246
MS
404@item -noautorotate
405Disable automatically rotating video based on file metadata.
406
6291d7e4
AK
407@end table
408
409@section Video Options
410
411@table @option
172efad7 412@item -vframes @var{number} (@emph{output})
96139b5e 413Set the number of video frames to record. This is an alias for @code{-frames:v}.
172efad7 414@item -r[:@var{stream_specifier}] @var{fps} (@emph{input/output,per-stream})
c9cc7629
AK
415Set frame rate (Hz value, fraction or abbreviation).
416
417As an input option, ignore any timestamps stored in the file and instead
418generate timestamps assuming constant frame rate @var{fps}.
419
420As an output option, duplicate or drop input frames to achieve constant output
421frame rate @var{fps} (note that this actually causes the @code{fps} filter to be
422inserted to the end of the corresponding filtergraph).
423
172efad7 424@item -s[:@var{stream_specifier}] @var{size} (@emph{input/output,per-stream})
4f81a507
AK
425Set frame size.
426
427As an input option, this is a shortcut for the @option{video_size} private
428option, recognized by some demuxers for which the frame size is either not
429stored in the file or is configurable -- e.g. raw video or video grabbers.
430
431As an output option, this inserts the @code{scale} video filter to the
432@emph{end} of the corresponding filtergraph. Please use the @code{scale} filter
433directly to insert it at the beginning or some other place.
434
435The format is @samp{wxh} (default - same as source). The following
436abbreviations are recognized:
6291d7e4
AK
437@table @samp
438@item sqcif
439128x96
440@item qcif
441176x144
442@item cif
443352x288
444@item 4cif
445704x576
446@item 16cif
4471408x1152
448@item qqvga
449160x120
450@item qvga
451320x240
452@item vga
453640x480
454@item svga
455800x600
456@item xga
4571024x768
458@item uxga
4591600x1200
460@item qxga
4612048x1536
462@item sxga
4631280x1024
464@item qsxga
4652560x2048
466@item hsxga
4675120x4096
468@item wvga
469852x480
470@item wxga
4711366x768
472@item wsxga
4731600x1024
474@item wuxga
4751920x1200
476@item woxga
4772560x1600
478@item wqsxga
4793200x2048
480@item wquxga
4813840x2400
482@item whsxga
4836400x4096
484@item whuxga
4857680x4800
486@item cga
487320x200
488@item ega
489640x350
490@item hd480
491852x480
492@item hd720
4931280x720
494@item hd1080
4951920x1080
e93ca480
LB
496@item 2kdci
4972048x1080
498@item 4kdci
4994096x2160
219b39a7 500@item uhd2160
e93ca480 5013840x2160
219b39a7 502@item uhd4320
e93ca480 5037680x4320
6291d7e4
AK
504@end table
505
172efad7 506@item -aspect[:@var{stream_specifier}] @var{aspect} (@emph{output,per-stream})
6291d7e4
AK
507Set the video display aspect ratio specified by @var{aspect}.
508
509@var{aspect} can be a floating point number string, or a string of the
510form @var{num}:@var{den}, where @var{num} and @var{den} are the
511numerator and denominator of the aspect ratio. For example "4:3",
512"16:9", "1.3333", and "1.7777" are valid argument values.
513
172efad7 514@item -vn (@emph{output})
6291d7e4 515Disable video recording.
4fea8959 516
172efad7 517@item -vcodec @var{codec} (@emph{output})
92f1940e 518Set the video codec. This is an alias for @code{-codec:v}.
f4ad238c 519
038c0b1e 520@item -pass[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
6291d7e4
AK
521Select the pass number (1 or 2). It is used to do two-pass
522video encoding. The statistics of the video are recorded in the first
523pass into a log file (see also the option -passlogfile),
524and in the second pass that log file is used to generate the video
525at the exact requested bitrate.
526On pass 1, you may just deactivate audio and set output to null,
527examples for Windows and Unix:
528@example
92f1940e
AK
529avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
530avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
6291d7e4
AK
531@end example
532
bbcedade 533@item -passlogfile[:@var{stream_specifier}] @var{prefix} (@emph{output,per-stream})
6291d7e4
AK
534Set two-pass log file name prefix to @var{prefix}, the default file name
535prefix is ``av2pass''. The complete file name will be
536@file{PREFIX-N.log}, where N is a number specific to the output
537stream.
538
172efad7 539@item -vf @var{filter_graph} (@emph{output})
6291d7e4
AK
540@var{filter_graph} is a description of the filter graph to apply to
541the input video.
542Use the option "-filters" to show all the available filters (including
8e5ce590 543also sources and sinks). This is an alias for @code{-filter:v}.
6291d7e4
AK
544
545@end table
546
547@section Advanced Video Options
548
549@table @option
172efad7 550@item -pix_fmt[:@var{stream_specifier}] @var{format} (@emph{input/output,per-stream})
b2254d83 551Set pixel format. Use @code{-pix_fmts} to show all the supported
6291d7e4 552pixel formats.
172efad7 553@item -sws_flags @var{flags} (@emph{input/output})
6291d7e4 554Set SwScaler flags.
6291d7e4
AK
555@item -vdt @var{n}
556Discard threshold.
6291d7e4 557
172efad7 558@item -rc_override[:@var{stream_specifier}] @var{override} (@emph{output,per-stream})
6291d7e4 559rate control override for specific intervals
6291d7e4 560
6291d7e4
AK
561@item -vstats
562Dump video coding statistics to @file{vstats_HHMMSS.log}.
563@item -vstats_file @var{file}
564Dump video coding statistics to @var{file}.
172efad7 565@item -top[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
6291d7e4
AK
566top=1/bottom=0/auto=-1 field first
567@item -dc @var{precision}
568Intra_dc_precision.
172efad7 569@item -vtag @var{fourcc/tag} (@emph{output})
013887eb 570Force video tag/fourcc. This is an alias for @code{-tag:v}.
172efad7 571@item -qphist (@emph{global})
6291d7e4 572Show QP histogram.
172efad7 573@item -force_key_frames[:@var{stream_specifier}] @var{time}[,@var{time}...] (@emph{output,per-stream})
6291d7e4
AK
574Force key frames at the specified timestamps, more precisely at the first
575frames after each specified time.
576This option can be useful to ensure that a seek point is present at a
577chapter mark or any other designated place in the output file.
578The timestamps must be specified in ascending order.
a2aeeb22
AK
579
580@item -copyinkf[:@var{stream_specifier}] (@emph{output,per-stream})
581When doing stream copy, copy also non-key frames found at the
582beginning.
07fd0a22
AK
583
584@item -hwaccel[:@var{stream_specifier}] @var{hwaccel} (@emph{input,per-stream})
585Use hardware acceleration to decode the matching stream(s). The allowed values
586of @var{hwaccel} are:
587@table @option
588@item none
589Do not use any hardware acceleration (the default).
590
591@item auto
592Automatically select the hardware acceleration method.
7671dd7c 593
1839fafa
AK
594@item vda
595Use Apple VDA hardware acceleration.
596
7671dd7c
AK
597@item vdpau
598Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration.
35177ba7
HL
599
600@item dxva2
601Use DXVA2 (DirectX Video Acceleration) hardware acceleration.
07fd0a22
AK
602@end table
603
604This option has no effect if the selected hwaccel is not available or not
605supported by the chosen decoder.
606
607Note that most acceleration methods are intended for playback and will not be
608faster than software decoding on modern CPUs. Additionally, @command{avconv}
609will usually need to copy the decoded frames from the GPU memory into the system
610memory, resulting in further performance loss. This option is thus mainly
611useful for testing.
612
613@item -hwaccel_device[:@var{stream_specifier}] @var{hwaccel_device} (@emph{input,per-stream})
614Select a device to use for hardware acceleration.
615
616This option only makes sense when the @option{-hwaccel} option is also
617specified. Its exact meaning depends on the specific hardware acceleration
618method chosen.
7671dd7c
AK
619
620@table @option
621@item vdpau
622For VDPAU, this option specifies the X11 display/screen to use. If this option
623is not specified, the value of the @var{DISPLAY} environment variable is used
35177ba7
HL
624
625@item dxva2
626For DXVA2, this option should contain the number of the display adapter to use.
627If this option is not specified, the default adapter is used.
7671dd7c 628@end table
c23999be
TG
629
630@item -hwaccels
631List all hardware acceleration methods supported in this build of avconv.
632
6291d7e4
AK
633@end table
634
635@section Audio Options
636
637@table @option
172efad7 638@item -aframes @var{number} (@emph{output})
96139b5e 639Set the number of audio frames to record. This is an alias for @code{-frames:a}.
172efad7 640@item -ar[:@var{stream_specifier}] @var{freq} (@emph{input/output,per-stream})
6291d7e4
AK
641Set the audio sampling frequency. For output streams it is set by
642default to the frequency of the corresponding input stream. For input
643streams this option only makes sense for audio grabbing devices and raw
644demuxers and is mapped to the corresponding demuxer options.
172efad7 645@item -aq @var{q} (@emph{output})
77d9c454 646Set the audio quality (codec-specific, VBR). This is an alias for -q:a.
172efad7 647@item -ac[:@var{stream_specifier}] @var{channels} (@emph{input/output,per-stream})
6291d7e4
AK
648Set the number of audio channels. For output streams it is set by
649default to the number of input audio channels. For input streams
650this option only makes sense for audio grabbing devices and raw demuxers
651and is mapped to the corresponding demuxer options.
172efad7 652@item -an (@emph{output})
6291d7e4 653Disable audio recording.
172efad7 654@item -acodec @var{codec} (@emph{input/output})
92f1940e 655Set the audio codec. This is an alias for @code{-codec:a}.
172efad7 656@item -sample_fmt[:@var{stream_specifier}] @var{sample_fmt} (@emph{output,per-stream})
2b56db58 657Set the audio sample format. Use @code{-sample_fmts} to get a list
05bffc12 658of supported sample formats.
369cb092
AK
659@item -af @var{filter_graph} (@emph{output})
660@var{filter_graph} is a description of the filter graph to apply to
661the input audio.
662Use the option "-filters" to show all the available filters (including
663also sources and sinks). This is an alias for @code{-filter:a}.
6291d7e4
AK
664@end table
665
666@section Advanced Audio options:
667
668@table @option
172efad7 669@item -atag @var{fourcc/tag} (@emph{output})
013887eb 670Force audio tag/fourcc. This is an alias for @code{-tag:a}.
6291d7e4
AK
671@end table
672
673@section Subtitle options:
674
675@table @option
172efad7 676@item -scodec @var{codec} (@emph{input/output})
92f1940e 677Set the subtitle codec. This is an alias for @code{-codec:s}.
172efad7 678@item -sn (@emph{output})
6291d7e4 679Disable subtitle recording.
6291d7e4
AK
680@end table
681
6291d7e4
AK
682@section Advanced options
683
684@table @option
3b266da3 685@item -map [-]@var{input_file_id}[:@var{stream_specifier}][,@var{sync_file_id}[:@var{stream_specifier}]] | @var{[linklabel]} (@emph{output})
6291d7e4 686
8d2e4a7e 687Designate one or more input streams as a source for the output file. Each input
6291d7e4
AK
688stream is identified by the input file index @var{input_file_id} and
689the input stream index @var{input_stream_id} within the input
8d2e4a7e 690file. Both indices start at 0. If specified,
172efad7 691@var{sync_file_id}:@var{stream_specifier} sets which input stream
6291d7e4
AK
692is used as a presentation sync reference.
693
3d4f0dab 694The first @code{-map} option on the command line specifies the
6291d7e4
AK
695source for output stream 0, the second @code{-map} option specifies
696the source for output stream 1, etc.
697
8d2e4a7e
AK
698A @code{-} character before the stream identifier creates a "negative" mapping.
699It disables matching streams from already created mappings.
700
3b266da3
AK
701An alternative @var{[linklabel]} form will map outputs from complex filter
702graphs (see the @option{-filter_complex} option) to the output file.
703@var{linklabel} must correspond to a defined output link label in the graph.
704
8d2e4a7e
AK
705For example, to map ALL streams from the first input file to output
706@example
f5bae2c6 707avconv -i INPUT -map 0 output
8d2e4a7e
AK
708@end example
709
6291d7e4 710For example, if you have two audio streams in the first input file,
8d2e4a7e 711these streams are identified by "0:0" and "0:1". You can use
3d4f0dab 712@code{-map} to select which streams to place in an output file. For
6291d7e4
AK
713example:
714@example
8d2e4a7e 715avconv -i INPUT -map 0:1 out.wav
6291d7e4 716@end example
8d2e4a7e 717will map the input stream in @file{INPUT} identified by "0:1" to
6291d7e4
AK
718the (single) output stream in @file{out.wav}.
719
720For example, to select the stream with index 2 from input file
8d2e4a7e
AK
721@file{a.mov} (specified by the identifier "0:2"), and stream with
722index 6 from input @file{b.mov} (specified by the identifier "1:6"),
6291d7e4
AK
723and copy them to the output file @file{out.mov}:
724@example
92f1940e 725avconv -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
8d2e4a7e
AK
726@end example
727
728To select all video and the third audio stream from an input file:
729@example
730avconv -i INPUT -map 0:v -map 0:a:2 OUTPUT
731@end example
732
733To map all the streams except the second audio, use negative mappings
734@example
735avconv -i INPUT -map 0 -map -0:a:1 OUTPUT
6291d7e4
AK
736@end example
737
481a3667
AK
738To pick the English audio stream:
739@example
740avconv -i INPUT -map 0:m:language:eng OUTPUT
741@end example
742
3d4f0dab 743Note that using this option disables the default mappings for this output file.
6291d7e4 744
a7b5e841 745@item -map_metadata[:@var{metadata_spec_out}] @var{infile}[:@var{metadata_spec_in}] (@emph{output,per-metadata})
e6e6060c
AK
746Set metadata information of the next output file from @var{infile}. Note that
747those are file indices (zero-based), not filenames.
a7b5e841
AK
748Optional @var{metadata_spec_in/out} parameters specify, which metadata to copy.
749A metadata specifier can have the following forms:
750@table @option
751@item @var{g}
752global metadata, i.e. metadata that applies to the whole file
753
754@item @var{s}[:@var{stream_spec}]
755per-stream metadata. @var{stream_spec} is a stream specifier as described
756in the @ref{Stream specifiers} chapter. In an input metadata specifier, the first
757matching stream is copied from. In an output metadata specifier, all matching
758streams are copied to.
759
760@item @var{c}:@var{chapter_index}
761per-chapter metadata. @var{chapter_index} is the zero-based chapter index.
762
763@item @var{p}:@var{program_index}
764per-program metadata. @var{program_index} is the zero-based program index.
765@end table
766If metadata specifier is omitted, it defaults to global.
6291d7e4 767
e6e6060c 768By default, global metadata is copied from the first input file,
6291d7e4
AK
769per-stream and per-chapter metadata is copied along with streams/chapters. These
770default mappings are disabled by creating any mapping of the relevant type. A negative
771file index can be used to create a dummy mapping that just disables automatic copying.
772
773For example to copy metadata from the first stream of the input file to global metadata
774of the output file:
775@example
e6e6060c 776avconv -i in.ogg -map_metadata 0:s:0 out.mp3
6291d7e4 777@end example
a7b5e841
AK
778
779To do the reverse, i.e. copy global metadata to all audio streams:
780@example
781avconv -i in.mkv -map_metadata:s:a 0:g out.mkv
782@end example
783Note that simple @code{0} would work as well in this example, since global
784metadata is assumed by default.
785
172efad7 786@item -map_chapters @var{input_file_index} (@emph{output})
b9aac90b
AK
787Copy chapters from input file with index @var{input_file_index} to the next
788output file. If no chapter mapping is specified, then chapters are copied from
789the first input file with at least one chapter. Use a negative file index to
790disable any chapter copying.
6291d7e4
AK
791@item -debug
792Print specific debug info.
172efad7 793@item -benchmark (@emph{global})
6291d7e4
AK
794Show benchmarking information at the end of an encode.
795Shows CPU time used and maximum memory consumption.
796Maximum memory consumption is not supported on all systems,
797it will usually display as 0 if not supported.
5aa3fcec
AK
798@item -timelimit @var{duration} (@emph{global})
799Exit after avconv has been running for @var{duration} seconds.
172efad7 800@item -dump (@emph{global})
d159060a 801Dump each input packet to stderr.
172efad7 802@item -hex (@emph{global})
6291d7e4 803When dumping packets, also dump the payload.
172efad7 804@item -re (@emph{input})
205a4502
MS
805Read input at native frame rate. Mainly used to simulate a grab device
806or live input stream (e.g. when reading from a file). Should not be used
807with actual grab devices or live input streams (where it can cause packet
808loss).
6291d7e4
AK
809@item -vsync @var{parameter}
810Video sync method.
811
812@table @option
e8c04f62 813@item passthrough
6291d7e4 814Each frame is passed with its timestamp from the demuxer to the muxer.
e8c04f62 815@item cfr
6291d7e4
AK
816Frames will be duplicated and dropped to achieve exactly the requested
817constant framerate.
e8c04f62 818@item vfr
6291d7e4
AK
819Frames are passed through with their timestamp or dropped so as to
820prevent 2 frames from having the same timestamp.
e8c04f62 821@item auto
6291d7e4
AK
822Chooses between 1 and 2 depending on muxer capabilities. This is the
823default method.
824@end table
825
826With -map you can select from which stream the timestamps should be
827taken. You can leave either video or audio unchanged and sync the
828remaining stream(s) to the unchanged one.
829
830@item -async @var{samples_per_second}
831Audio sync method. "Stretches/squeezes" the audio stream to match the timestamps,
832the parameter is the maximum samples per second by which the audio is changed.
833-async 1 is a special case where only the start of the audio stream is corrected
834without any later correction.
6eeb9a04 835This option has been deprecated. Use the @code{asyncts} audio filter instead.
6291d7e4
AK
836@item -copyts
837Copy timestamps from input to output.
838@item -copytb
839Copy input stream time base from input to output when stream copying.
3c0df905 840@item -shortest (@emph{output})
6291d7e4
AK
841Finish encoding when the shortest input stream ends.
842@item -dts_delta_threshold
843Timestamp discontinuity delta threshold.
172efad7 844@item -muxdelay @var{seconds} (@emph{input})
6291d7e4 845Set the maximum demux-decode delay.
172efad7 846@item -muxpreload @var{seconds} (@emph{input})
6291d7e4 847Set the initial demux-decode delay.
172efad7 848@item -streamid @var{output-stream-index}:@var{new-value} (@emph{output})
6291d7e4
AK
849Assign a new stream-id value to an output stream. This option should be
850specified prior to the output filename to which it applies.
851For the situation where multiple output files exist, a streamid
852may be reassigned to a different value.
853
854For example, to set the stream 0 PID to 33 and the stream 1 PID to 36 for
855an output mpegts file:
856@example
857avconv -i infile -streamid 0:33 -streamid 1:36 out.ts
858@end example
d821cbe2 859
172efad7 860@item -bsf[:@var{stream_specifier}] @var{bitstream_filters} (@emph{output,per-stream})
d821cbe2
AK
861Set bitstream filters for matching streams. @var{bistream_filters} is
862a comma-separated list of bitstream filters. Use the @code{-bsfs} option
863to get the list of bitstream filters.
864@example
d6a77e2b 865avconv -i h264.mp4 -c:v copy -bsf:v h264_mp4toannexb -an out.h264
d821cbe2
AK
866@end example
867@example
d6a77e2b 868avconv -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
d821cbe2 869@end example
013887eb 870
746dca48 871@item -tag[:@var{stream_specifier}] @var{codec_tag} (@emph{input/output,per-stream})
013887eb 872Force a tag/fourcc for matching streams.
4138cd29 873
3b266da3
AK
874@item -filter_complex @var{filtergraph} (@emph{global})
875Define a complex filter graph, i.e. one with arbitrary number of inputs and/or
876outputs. For simple graphs -- those with one input and one output of the same
877type -- see the @option{-filter} options. @var{filtergraph} is a description of
878the filter graph, as described in @ref{Filtergraph syntax}.
879
880Input link labels must refer to input streams using the
881@code{[file_index:stream_specifier]} syntax (i.e. the same as @option{-map}
882uses). If @var{stream_specifier} matches multiple streams, the first one will be
883used. An unlabeled input will be connected to the first unused input stream of
884the matching type.
885
886Output link labels are referred to with @option{-map}. Unlabeled outputs are
887added to the first output file.
888
ab296097
AK
889Note that with this option it is possible to use only lavfi sources without
890normal input files.
891
3b266da3
AK
892For example, to overlay an image over video
893@example
894avconv -i video.mkv -i image.png -filter_complex '[0:v][1:v]overlay[out]' -map
895'[out]' out.mkv
896@end example
897Here @code{[0:v]} refers to the first video stream in the first input file,
898which is linked to the first (main) input of the overlay filter. Similarly the
899first video stream in the second input is linked to the second (overlay) input
900of overlay.
901
902Assuming there is only one video stream in each input file, we can omit input
903labels, so the above is equivalent to
904@example
905avconv -i video.mkv -i image.png -filter_complex 'overlay[out]' -map
906'[out]' out.mkv
907@end example
908
909Furthermore we can omit the output label and the single output from the filter
910graph will be added to the output file automatically, so we can simply write
911@example
912avconv -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
913@end example
ab296097
AK
914
915To generate 5 seconds of pure red video using lavfi @code{color} source:
916@example
917avconv -filter_complex 'color=red' -t 5 out.mkv
918@end example
a4208b9b
AK
919
920@item -filter_complex_script @var{filename} (@emph{global})
921This option is similar to @option{-filter_complex}, the only difference is that
922its argument is the name of the file from which a complex filtergraph
923description is to be read.
924
811bd078
AK
925@item -accurate_seek (@emph{input})
926This option enables or disables accurate seeking in input files with the
927@option{-ss} option. It is enabled by default, so seeking is accurate when
928transcoding. Use @option{-noaccurate_seek} to disable it, which may be useful
929e.g. when copying some streams and transcoding the others.
930
6291d7e4 931@end table
7478ab5a 932@c man end OPTIONS
6291d7e4 933
6291d7e4
AK
934@chapter Tips
935@c man begin TIPS
936
937@itemize
938@item
939For streaming at very low bitrate application, use a low frame rate
940and a small GOP size. This is especially true for RealVideo where
941the Linux player does not seem to be very fast, so it can miss
942frames. An example is:
943
944@example
945avconv -g 3 -r 3 -t 10 -b 50k -s qcif -f rv10 /tmp/b.rm
946@end example
947
948@item
949The parameter 'q' which is displayed while encoding is the current
950quantizer. The value 1 indicates that a very good quality could
951be achieved. The value 31 indicates the worst quality. If q=31 appears
952too often, it means that the encoder cannot compress enough to meet
953your bitrate. You must either increase the bitrate, decrease the
954frame rate or decrease the frame size.
955
956@item
957If your computer is not fast enough, you can speed up the
958compression at the expense of the compression ratio. You can use
3607dc2b 959'-me zero' to speed up motion estimation, and '-g 0' to disable
6291d7e4
AK
960motion estimation completely (you have only I-frames, which means it
961is about as good as JPEG compression).
962
963@item
964To have very low audio bitrates, reduce the sampling frequency
965(down to 22050 Hz for MPEG audio, 22050 or 11025 for AC-3).
966
967@item
968To have a constant quality (but a variable bitrate), use the option
969'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
970quality).
971
6291d7e4
AK
972@end itemize
973@c man end TIPS
974
975@chapter Examples
976@c man begin EXAMPLES
977
3ec34462
AK
978@section Preset files
979
980A preset file contains a sequence of @var{option=value} pairs, one for
981each line, specifying a sequence of options which can be specified also on
982the command line. Lines starting with the hash ('#') character are ignored and
983are used to provide comments. Empty lines are also ignored. Check the
8096fdf0 984@file{presets} directory in the Libav source tree for examples.
3ec34462
AK
985
986Preset files are specified with the @code{pre} option, this option takes a
987preset name as input. Avconv searches for a file named @var{preset_name}.avpreset in
988the directories @file{$AVCONV_DATADIR} (if set), and @file{$HOME/.avconv}, and in
989the data directory defined at configuration time (usually @file{$PREFIX/share/avconv})
990in that order. For example, if the argument is @code{libx264-max}, it will
991search for the file @file{libx264-max.avpreset}.
992
6291d7e4
AK
993@section Video and Audio grabbing
994
995If you specify the input format and device then avconv can grab video
996and audio directly.
997
998@example
999avconv -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
1000@end example
1001
1002Note that you must activate the right video source and channel before
1003launching avconv with any TV viewer such as
1004@uref{http://linux.bytesex.org/xawtv/, xawtv} by Gerd Knorr. You also
1005have to set the audio recording levels correctly with a
1006standard mixer.
1007
1008@section X11 grabbing
1009
1010Grab the X11 display with avconv via
1011
1012@example
1013avconv -f x11grab -s cif -r 25 -i :0.0 /tmp/out.mpg
1014@end example
1015
10160.0 is display.screen number of your X11 server, same as
1017the DISPLAY environment variable.
1018
1019@example
1020avconv -f x11grab -s cif -r 25 -i :0.0+10,20 /tmp/out.mpg
1021@end example
1022
10230.0 is display.screen number of your X11 server, same as the DISPLAY environment
1024variable. 10 is the x-offset and 20 the y-offset for the grabbing.
1025
1026@section Video and Audio file format conversion
1027
1028Any supported file format and protocol can serve as input to avconv:
1029
1030Examples:
1031@itemize
1032@item
1033You can use YUV files as input:
1034
1035@example
1036avconv -i /tmp/test%d.Y /tmp/out.mpg
1037@end example
1038
1039It will use the files:
1040@example
1041/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
1042/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
1043@end example
1044
1045The Y files use twice the resolution of the U and V files. They are
1046raw files, without header. They can be generated by all decent video
1047decoders. You must specify the size of the image with the @option{-s} option
1048if avconv cannot guess it.
1049
1050@item
1051You can input from a raw YUV420P file:
1052
1053@example
1054avconv -i /tmp/test.yuv /tmp/out.avi
1055@end example
1056
1057test.yuv is a file containing raw YUV planar data. Each frame is composed
1058of the Y plane followed by the U and V planes at half vertical and
1059horizontal resolution.
1060
1061@item
1062You can output to a raw YUV420P file:
1063
1064@example
1065avconv -i mydivx.avi hugefile.yuv
1066@end example
1067
1068@item
1069You can set several input files and output files:
1070
1071@example
1072avconv -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
1073@end example
1074
1075Converts the audio file a.wav and the raw YUV video file a.yuv
1076to MPEG file a.mpg.
1077
1078@item
1079You can also do audio and video conversions at the same time:
1080
1081@example
1082avconv -i /tmp/a.wav -ar 22050 /tmp/a.mp2
1083@end example
1084
1085Converts a.wav to MPEG audio at 22050 Hz sample rate.
1086
1087@item
1088You can encode to several formats at the same time and define a
1089mapping from input stream to output streams:
1090
1091@example
64db1a82 1092avconv -i /tmp/a.wav -map 0:a -b 64k /tmp/a.mp2 -map 0:a -b 128k /tmp/b.mp2
6291d7e4
AK
1093@end example
1094
1095Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
1096file:index' specifies which input stream is used for each output
1097stream, in the order of the definition of output streams.
1098
1099@item
1100You can transcode decrypted VOBs:
1101
1102@example
64db1a82 1103avconv -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
1104@end example
1105
1106This is a typical DVD ripping example; the input is a VOB file, the
1107output an AVI file with MPEG-4 video and MP3 audio. Note that in this
1108command we use B-frames so the MPEG-4 stream is DivX5 compatible, and
1109GOP size is 300 which means one intra frame every 10 seconds for 29.97fps
1110input video. Furthermore, the audio stream is MP3-encoded so you need
1111to enable LAME support by passing @code{--enable-libmp3lame} to configure.
1112The mapping is particularly useful for DVD transcoding
1113to get the desired audio language.
1114
1115NOTE: To see the supported input formats, use @code{avconv -formats}.
1116
1117@item
1118You can extract images from a video, or create a video from many images:
1119
1120For extracting images from a video:
1121@example
1122avconv -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
1123@end example
1124
1125This will extract one video frame per second from the video and will
1126output them in files named @file{foo-001.jpeg}, @file{foo-002.jpeg},
1127etc. Images will be rescaled to fit the new WxH values.
1128
1129If you want to extract just a limited number of frames, you can use the
1130above command in combination with the -vframes or -t option, or in
1131combination with -ss to start extracting from a certain point in time.
1132
1133For creating a video from many images:
1134@example
1135avconv -f image2 -i foo-%03d.jpeg -r 12 -s WxH foo.avi
1136@end example
1137
1138The syntax @code{foo-%03d.jpeg} specifies to use a decimal number
1139composed of three digits padded with zeroes to express the sequence
1140number. It is the same syntax supported by the C printf function, but
1141only formats accepting a normal integer are suitable.
1142
1143@item
1144You can put many streams of the same type in the output:
1145
1146@example
775a0b04 1147avconv -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
1148@end example
1149
775a0b04
DB
1150The resulting output file @file{test12.nut} will contain the first four streams
1151from the input files in reverse order.
6291d7e4 1152
4fea8959
AK
1153@item
1154To force CBR video output:
1155@example
1156avconv -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
1157@end example
1158
1159@item
1160The four options lmin, lmax, mblmin and mblmax use 'lambda' units,
1161but you may use the QP2LAMBDA constant to easily convert from 'q' units:
1162@example
1163avconv -i src.ext -lmax 21*QP2LAMBDA dst.ext
1164@end example
1165
6291d7e4
AK
1166@end itemize
1167@c man end EXAMPLES
1168
1169@include eval.texi
a17ab0e4 1170@include decoders.texi
6291d7e4
AK
1171@include encoders.texi
1172@include demuxers.texi
1173@include muxers.texi
1174@include indevs.texi
1175@include outdevs.texi
1176@include protocols.texi
1177@include bitstream_filters.texi
1178@include filters.texi
1179@include metadata.texi
1180
1181@ignore
1182
1183@setfilename avconv
1184@settitle avconv video converter
1185
1186@c man begin SEEALSO
2e87b4c5 1187avplay(1), avprobe(1) and the Libav HTML documentation
6291d7e4
AK
1188@c man end
1189
1190@c man begin AUTHORS
1191The Libav developers
1192@c man end
1193
1194@end ignore
1195
1196@bye