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