presets: rename presets directory
[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
6291d7e4
AK
29As a general rule, options are applied to the next specified
30file. Therefore, order is important, and you can have the same
31option on the command line multiple times. Each occurrence is
32then applied to the next input or output file.
57650c70 33Exceptions from this rule are the global options (e.g. verbosity level),
eb054463 34which should be specified first.
6291d7e4
AK
35
36@itemize
37@item
38To set the video bitrate of the output file to 64kbit/s:
39@example
40avconv -i input.avi -b 64k output.avi
41@end example
42
43@item
44To force the frame rate of the output file to 24 fps:
45@example
46avconv -i input.avi -r 24 output.avi
47@end example
48
49@item
50To force the frame rate of the input file (valid for raw formats only)
51to 1 fps and the frame rate of the output file to 24 fps:
52@example
53avconv -r 1 -i input.m2v -r 24 output.avi
54@end example
55@end itemize
56
57The format option may be needed for raw input files.
58
6291d7e4
AK
59@c man end DESCRIPTION
60
3d4f0dab
AK
61@chapter Stream selection
62@c man begin STREAM SELECTION
63
f5bae2c6 64By default avconv tries to pick the "best" stream of each type present in input
3d4f0dab
AK
65files and add them to each output file. For video, this means the highest
66resolution, for audio the highest channel count. For subtitle it's simply the
67first subtitle stream.
68
69You can disable some of those defaults by using @code{-vn/-an/-sn} options. For
70full manual control, use the @code{-map} option, which disables the defaults just
71described.
72
73@c man end STREAM SELECTION
74
6291d7e4
AK
75@chapter Options
76@c man begin OPTIONS
77
b3dd2010 78@include avtools-common-opts.texi
6291d7e4
AK
79
80@section Main options
81
82@table @option
83
172efad7 84@item -f @var{fmt} (@emph{input/output})
d159060a
AK
85Force input or output file format. The format is normally autodetected for input
86files and guessed from file extension for output files, so this option is not
87needed in most cases.
6291d7e4 88
172efad7 89@item -i @var{filename} (@emph{input})
6291d7e4
AK
90input file name
91
172efad7 92@item -y (@emph{global})
d159060a 93Overwrite output files without asking.
6291d7e4 94
172efad7
AK
95@item -c[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
96@itemx -codec[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
92f1940e
AK
97Select an encoder (when used before an output file) or a decoder (when used
98before an input file) for one or more streams. @var{codec} is the name of a
99decoder/encoder or a special value @code{copy} (output only) to indicate that
100the stream is not to be reencoded.
101
92f1940e
AK
102For example
103@example
104avconv -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
105@end example
106encodes all video streams with libx264 and copies all audio streams.
107
108For each stream, the last matching @code{c} option is applied, so
109@example
110avconv -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
111@end example
112will copy all the streams except the second video, which will be encoded with
113libx264, and the 138th audio, which will be encoded with libvorbis.
114
172efad7 115@item -t @var{duration} (@emph{output})
d159060a
AK
116Stop writing the output after its duration reaches @var{duration}.
117@var{duration} may be a number in seconds, or in @code{hh:mm:ss[.xxx]} form.
6291d7e4 118
172efad7 119@item -fs @var{limit_size} (@emph{output})
6291d7e4
AK
120Set the file size limit.
121
172efad7 122@item -ss @var{position} (@emph{input/output})
cf4976ed
AK
123When used as an input option (before @code{-i}), seeks in this input file to
124@var{position}. When used as an output option (before an output filename),
125decodes but discards input until the timestamps reach @var{position}. This is
126slower, but more accurate.
127
128@var{position} may be either in seconds or in @code{hh:mm:ss[.xxx]} form.
6291d7e4 129
172efad7 130@item -itsoffset @var{offset} (@emph{input})
6291d7e4
AK
131Set the input time offset in seconds.
132@code{[-]hh:mm:ss[.xxx]} syntax is also supported.
6291d7e4
AK
133The offset is added to the timestamps of the input files.
134Specifying a positive offset means that the corresponding
d159060a 135streams are delayed by @var{offset} seconds.
6291d7e4 136
172efad7 137@item -metadata[:metadata_specifier] @var{key}=@var{value} (@emph{output,per-metadata})
6291d7e4
AK
138Set a metadata key/value pair.
139
039267f1
AK
140An optional @var{metadata_specifier} may be given to set metadata
141on streams or chapters. See @code{-map_metadata} documentation for
142details.
143
144This option overrides metadata set with @code{-map_metadata}. It is
145also possible to delete metadata by using an empty value.
146
6291d7e4
AK
147For example, for setting the title in the output file:
148@example
149avconv -i in.avi -metadata title="my title" out.flv
150@end example
151
039267f1
AK
152To set the language of the second stream:
153@example
154avconv -i INPUT -metadata:s:1 language=eng OUTPUT
155@end example
156
172efad7 157@item -target @var{type} (@emph{output})
d159060a
AK
158Specify target file type (@code{vcd}, @code{svcd}, @code{dvd}, @code{dv},
159@code{dv50}). @var{type} may be prefixed with @code{pal-}, @code{ntsc-} or
160@code{film-} to use the corresponding standard. All the format options
161(bitrate, codecs, buffer sizes) are then set automatically. You can just type:
6291d7e4
AK
162
163@example
164avconv -i myfile.avi -target vcd /tmp/vcd.mpg
165@end example
166
167Nevertheless you can specify additional options as long as you know
168they do not conflict with the standard, as in:
169
170@example
171avconv -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
172@end example
173
172efad7 174@item -dframes @var{number} (@emph{output})
96139b5e 175Set the number of data frames to record. This is an alias for @code{-frames:d}.
6291d7e4 176
172efad7 177@item -frames[:@var{stream_specifier}] @var{framecount} (@emph{output,per-stream})
96139b5e
AK
178Stop writing to the stream after @var{framecount} frames.
179
172efad7
AK
180@item -q[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
181@itemx -qscale[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
77d9c454
AK
182Use fixed quality scale (VBR). The meaning of @var{q} is
183codec-dependent.
184
667d9818 185@item -filter[:@var{stream_specifier}] @var{filter_graph} (@emph{output,per-stream})
8e5ce590
AK
186@var{filter_graph} is a description of the filter graph to apply to
187the stream. Use @code{-filters} to show all the available filters
188(including also sources and sinks).
3ec34462
AK
189@item -pre[:@var{stream_specifier}] @var{preset_name} (@emph{output,per-stream})
190Specify the preset for matching stream(s).
8e5ce590 191
3460dd8a
AK
192@item -stats (@emph{global})
193Print encoding progress/statistics. On by default.
194
6291d7e4
AK
195@end table
196
197@section Video Options
198
199@table @option
172efad7 200@item -vframes @var{number} (@emph{output})
96139b5e 201Set the number of video frames to record. This is an alias for @code{-frames:v}.
172efad7 202@item -r[:@var{stream_specifier}] @var{fps} (@emph{input/output,per-stream})
6291d7e4 203Set frame rate (Hz value, fraction or abbreviation), (default = 25).
172efad7 204@item -s[:@var{stream_specifier}] @var{size} (@emph{input/output,per-stream})
6291d7e4
AK
205Set frame size. The format is @samp{wxh} (avserver default = 160x128, avconv default = same as source).
206The following abbreviations are recognized:
207@table @samp
208@item sqcif
209128x96
210@item qcif
211176x144
212@item cif
213352x288
214@item 4cif
215704x576
216@item 16cif
2171408x1152
218@item qqvga
219160x120
220@item qvga
221320x240
222@item vga
223640x480
224@item svga
225800x600
226@item xga
2271024x768
228@item uxga
2291600x1200
230@item qxga
2312048x1536
232@item sxga
2331280x1024
234@item qsxga
2352560x2048
236@item hsxga
2375120x4096
238@item wvga
239852x480
240@item wxga
2411366x768
242@item wsxga
2431600x1024
244@item wuxga
2451920x1200
246@item woxga
2472560x1600
248@item wqsxga
2493200x2048
250@item wquxga
2513840x2400
252@item whsxga
2536400x4096
254@item whuxga
2557680x4800
256@item cga
257320x200
258@item ega
259640x350
260@item hd480
261852x480
262@item hd720
2631280x720
264@item hd1080
2651920x1080
266@end table
267
172efad7 268@item -aspect[:@var{stream_specifier}] @var{aspect} (@emph{output,per-stream})
6291d7e4
AK
269Set the video display aspect ratio specified by @var{aspect}.
270
271@var{aspect} can be a floating point number string, or a string of the
272form @var{num}:@var{den}, where @var{num} and @var{den} are the
273numerator and denominator of the aspect ratio. For example "4:3",
274"16:9", "1.3333", and "1.7777" are valid argument values.
275
172efad7 276@item -vn (@emph{output})
6291d7e4
AK
277Disable video recording.
278@item -bt @var{tolerance}
279Set video bitrate tolerance (in bits, default 4000k).
280Has a minimum value of: (target_bitrate/target_framerate).
281In 1-pass mode, bitrate tolerance specifies how far ratecontrol is
282willing to deviate from the target average bitrate value. This is
283not related to min/max bitrate. Lowering tolerance too much has
284an adverse effect on quality.
285@item -maxrate @var{bitrate}
286Set max video bitrate (in bit/s).
287Requires -bufsize to be set.
288@item -minrate @var{bitrate}
289Set min video bitrate (in bit/s).
290Most useful in setting up a CBR encode:
291@example
292avconv -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
293@end example
294It is of little use elsewise.
295@item -bufsize @var{size}
296Set video buffer verifier buffer size (in bits).
172efad7 297@item -vcodec @var{codec} (@emph{output})
92f1940e 298Set the video codec. This is an alias for @code{-codec:v}.
f4ad238c 299@item -same_quant
6291d7e4
AK
300Use same quantizer as source (implies VBR).
301
f4ad238c
AK
302Note that this is NOT SAME QUALITY. Do not use this option unless you know you
303need it.
304
6291d7e4
AK
305@item -pass @var{n}
306Select the pass number (1 or 2). It is used to do two-pass
307video encoding. The statistics of the video are recorded in the first
308pass into a log file (see also the option -passlogfile),
309and in the second pass that log file is used to generate the video
310at the exact requested bitrate.
311On pass 1, you may just deactivate audio and set output to null,
312examples for Windows and Unix:
313@example
92f1940e
AK
314avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
315avconv -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
6291d7e4
AK
316@end example
317
172efad7 318@item -passlogfile @var{prefix} (@emph{global})
6291d7e4
AK
319Set two-pass log file name prefix to @var{prefix}, the default file name
320prefix is ``av2pass''. The complete file name will be
321@file{PREFIX-N.log}, where N is a number specific to the output
322stream.
323
172efad7 324@item -vf @var{filter_graph} (@emph{output})
6291d7e4
AK
325@var{filter_graph} is a description of the filter graph to apply to
326the input video.
327Use the option "-filters" to show all the available filters (including
8e5ce590 328also sources and sinks). This is an alias for @code{-filter:v}.
6291d7e4
AK
329
330@end table
331
332@section Advanced Video Options
333
334@table @option
172efad7 335@item -pix_fmt[:@var{stream_specifier}] @var{format} (@emph{input/output,per-stream})
b2254d83 336Set pixel format. Use @code{-pix_fmts} to show all the supported
6291d7e4 337pixel formats.
172efad7 338@item -sws_flags @var{flags} (@emph{input/output})
6291d7e4
AK
339Set SwScaler flags.
340@item -g @var{gop_size}
341Set the group of pictures size.
6291d7e4
AK
342@item -vdt @var{n}
343Discard threshold.
6291d7e4
AK
344@item -qmin @var{q}
345minimum video quantizer scale (VBR)
346@item -qmax @var{q}
347maximum video quantizer scale (VBR)
348@item -qdiff @var{q}
349maximum difference between the quantizer scales (VBR)
350@item -qblur @var{blur}
351video quantizer scale blur (VBR) (range 0.0 - 1.0)
352@item -qcomp @var{compression}
353video quantizer scale compression (VBR) (default 0.5).
354Constant of ratecontrol equation. Recommended range for default rc_eq: 0.0-1.0
355
356@item -lmin @var{lambda}
357minimum video lagrange factor (VBR)
358@item -lmax @var{lambda}
359max video lagrange factor (VBR)
360@item -mblmin @var{lambda}
361minimum macroblock quantizer scale (VBR)
362@item -mblmax @var{lambda}
363maximum macroblock quantizer scale (VBR)
364
365These four options (lmin, lmax, mblmin, mblmax) use 'lambda' units,
366but you may use the QP2LAMBDA constant to easily convert from 'q' units:
367@example
368avconv -i src.ext -lmax 21*QP2LAMBDA dst.ext
369@end example
370
371@item -rc_init_cplx @var{complexity}
372initial complexity for single pass encoding
373@item -b_qfactor @var{factor}
374qp factor between P- and B-frames
375@item -i_qfactor @var{factor}
376qp factor between P- and I-frames
377@item -b_qoffset @var{offset}
378qp offset between P- and B-frames
379@item -i_qoffset @var{offset}
380qp offset between P- and I-frames
381@item -rc_eq @var{equation}
382Set rate control equation (see section "Expression Evaluation")
383(default = @code{tex^qComp}).
384
385When computing the rate control equation expression, besides the
386standard functions defined in the section "Expression Evaluation", the
387following functions are available:
388@table @var
389@item bits2qp(bits)
390@item qp2bits(qp)
391@end table
392
393and the following constants are available:
394@table @var
395@item iTex
396@item pTex
397@item tex
398@item mv
399@item fCode
400@item iCount
401@item mcVar
402@item var
403@item isI
404@item isP
405@item isB
406@item avgQP
407@item qComp
408@item avgIITex
409@item avgPITex
410@item avgPPTex
411@item avgBPTex
412@item avgTex
413@end table
414
172efad7 415@item -rc_override[:@var{stream_specifier}] @var{override} (@emph{output,per-stream})
6291d7e4
AK
416rate control override for specific intervals
417@item -me_method @var{method}
418Set motion estimation method to @var{method}.
419Available methods are (from lowest to best quality):
420@table @samp
421@item zero
422Try just the (0, 0) vector.
423@item phods
424@item log
425@item x1
426@item hex
427@item umh
428@item epzs
429(default method)
430@item full
431exhaustive search (slow and marginally better than epzs)
432@end table
433
6291d7e4
AK
434@item -er @var{n}
435Set error resilience to @var{n}.
436@table @samp
437@item 1
438FF_ER_CAREFUL (default)
439@item 2
440FF_ER_COMPLIANT
441@item 3
442FF_ER_AGGRESSIVE
443@item 4
444FF_ER_VERY_AGGRESSIVE
445@end table
446
447@item -ec @var{bit_mask}
448Set error concealment to @var{bit_mask}. @var{bit_mask} is a bit mask of
449the following values:
450@table @samp
451@item 1
452FF_EC_GUESS_MVS (default = enabled)
453@item 2
454FF_EC_DEBLOCK (default = enabled)
455@end table
456
457@item -bf @var{frames}
458Use 'frames' B-frames (supported for MPEG-1, MPEG-2 and MPEG-4).
459@item -mbd @var{mode}
460macroblock decision
461@table @samp
462@item 0
463FF_MB_DECISION_SIMPLE: Use mb_cmp (cannot change it yet in avconv).
464@item 1
465FF_MB_DECISION_BITS: Choose the one which needs the fewest bits.
466@item 2
467FF_MB_DECISION_RD: rate distortion
468@end table
469
6291d7e4
AK
470@item -bug @var{param}
471Work around encoder bugs that are not auto-detected.
472@item -strict @var{strictness}
473How strictly to follow the standards.
6291d7e4
AK
474
475@item -deinterlace
476Deinterlace pictures.
6291d7e4
AK
477@item -vstats
478Dump video coding statistics to @file{vstats_HHMMSS.log}.
479@item -vstats_file @var{file}
480Dump video coding statistics to @var{file}.
172efad7 481@item -top[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
6291d7e4
AK
482top=1/bottom=0/auto=-1 field first
483@item -dc @var{precision}
484Intra_dc_precision.
172efad7 485@item -vtag @var{fourcc/tag} (@emph{output})
013887eb 486Force video tag/fourcc. This is an alias for @code{-tag:v}.
172efad7 487@item -qphist (@emph{global})
6291d7e4 488Show QP histogram.
172efad7 489@item -force_key_frames[:@var{stream_specifier}] @var{time}[,@var{time}...] (@emph{output,per-stream})
6291d7e4
AK
490Force key frames at the specified timestamps, more precisely at the first
491frames after each specified time.
492This option can be useful to ensure that a seek point is present at a
493chapter mark or any other designated place in the output file.
494The timestamps must be specified in ascending order.
495@end table
496
497@section Audio Options
498
499@table @option
172efad7 500@item -aframes @var{number} (@emph{output})
96139b5e 501Set the number of audio frames to record. This is an alias for @code{-frames:a}.
172efad7 502@item -ar[:@var{stream_specifier}] @var{freq} (@emph{input/output,per-stream})
6291d7e4
AK
503Set the audio sampling frequency. For output streams it is set by
504default to the frequency of the corresponding input stream. For input
505streams this option only makes sense for audio grabbing devices and raw
506demuxers and is mapped to the corresponding demuxer options.
172efad7 507@item -aq @var{q} (@emph{output})
77d9c454 508Set the audio quality (codec-specific, VBR). This is an alias for -q:a.
172efad7 509@item -ac[:@var{stream_specifier}] @var{channels} (@emph{input/output,per-stream})
6291d7e4
AK
510Set the number of audio channels. For output streams it is set by
511default to the number of input audio channels. For input streams
512this option only makes sense for audio grabbing devices and raw demuxers
513and is mapped to the corresponding demuxer options.
172efad7 514@item -an (@emph{output})
6291d7e4 515Disable audio recording.
172efad7 516@item -acodec @var{codec} (@emph{input/output})
92f1940e 517Set the audio codec. This is an alias for @code{-codec:a}.
172efad7 518@item -sample_fmt[:@var{stream_specifier}] @var{sample_fmt} (@emph{output,per-stream})
05bffc12
AK
519Set the audio sample format. Use @code{-help sample_fmts} to get a list
520of supported sample formats.
6291d7e4
AK
521@end table
522
523@section Advanced Audio options:
524
525@table @option
172efad7 526@item -atag @var{fourcc/tag} (@emph{output})
013887eb 527Force audio tag/fourcc. This is an alias for @code{-tag:a}.
6291d7e4
AK
528@item -audio_service_type @var{type}
529Set the type of service that the audio stream contains.
530@table @option
531@item ma
532Main Audio Service (default)
533@item ef
534Effects
535@item vi
536Visually Impaired
537@item hi
538Hearing Impaired
539@item di
540Dialogue
541@item co
542Commentary
543@item em
544Emergency
545@item vo
546Voice Over
547@item ka
548Karaoke
549@end table
6291d7e4
AK
550@end table
551
552@section Subtitle options:
553
554@table @option
172efad7 555@item -scodec @var{codec} (@emph{input/output})
92f1940e 556Set the subtitle codec. This is an alias for @code{-codec:s}.
172efad7 557@item -sn (@emph{output})
6291d7e4 558Disable subtitle recording.
6291d7e4
AK
559@end table
560
561@section Audio/Video grab options
562
563@table @option
172efad7 564@item -isync (@emph{global})
6291d7e4
AK
565Synchronize read on input.
566@end table
567
568@section Advanced options
569
570@table @option
172efad7 571@item -map [-]@var{input_file_id}[:@var{stream_specifier}][,@var{sync_file_id}[:@var{stream_specifier}]] (@emph{output})
6291d7e4 572
8d2e4a7e 573Designate one or more input streams as a source for the output file. Each input
6291d7e4
AK
574stream is identified by the input file index @var{input_file_id} and
575the input stream index @var{input_stream_id} within the input
8d2e4a7e 576file. Both indices start at 0. If specified,
172efad7 577@var{sync_file_id}:@var{stream_specifier} sets which input stream
6291d7e4
AK
578is used as a presentation sync reference.
579
3d4f0dab 580The first @code{-map} option on the command line specifies the
6291d7e4
AK
581source for output stream 0, the second @code{-map} option specifies
582the source for output stream 1, etc.
583
8d2e4a7e
AK
584A @code{-} character before the stream identifier creates a "negative" mapping.
585It disables matching streams from already created mappings.
586
587For example, to map ALL streams from the first input file to output
588@example
f5bae2c6 589avconv -i INPUT -map 0 output
8d2e4a7e
AK
590@end example
591
6291d7e4 592For example, if you have two audio streams in the first input file,
8d2e4a7e 593these streams are identified by "0:0" and "0:1". You can use
3d4f0dab 594@code{-map} to select which streams to place in an output file. For
6291d7e4
AK
595example:
596@example
8d2e4a7e 597avconv -i INPUT -map 0:1 out.wav
6291d7e4 598@end example
8d2e4a7e 599will map the input stream in @file{INPUT} identified by "0:1" to
6291d7e4
AK
600the (single) output stream in @file{out.wav}.
601
602For example, to select the stream with index 2 from input file
8d2e4a7e
AK
603@file{a.mov} (specified by the identifier "0:2"), and stream with
604index 6 from input @file{b.mov} (specified by the identifier "1:6"),
6291d7e4
AK
605and copy them to the output file @file{out.mov}:
606@example
92f1940e 607avconv -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
8d2e4a7e
AK
608@end example
609
610To select all video and the third audio stream from an input file:
611@example
612avconv -i INPUT -map 0:v -map 0:a:2 OUTPUT
613@end example
614
615To map all the streams except the second audio, use negative mappings
616@example
617avconv -i INPUT -map 0 -map -0:a:1 OUTPUT
6291d7e4
AK
618@end example
619
3d4f0dab 620Note that using this option disables the default mappings for this output file.
6291d7e4 621
172efad7 622@item -map_metadata[:@var{metadata_type}][:@var{index}] @var{infile}[:@var{metadata_type}][:@var{index}] (@emph{output,per-metadata})
e6e6060c
AK
623Set metadata information of the next output file from @var{infile}. Note that
624those are file indices (zero-based), not filenames.
625Optional @var{metadata_type} parameters specify, which metadata to copy - (g)lobal
6291d7e4
AK
626(i.e. metadata that applies to the whole file), per-(s)tream, per-(c)hapter or
627per-(p)rogram. All metadata specifiers other than global must be followed by the
e6e6060c 628stream/chapter/program index. If metadata specifier is omitted, it defaults to
6291d7e4
AK
629global.
630
e6e6060c 631By default, global metadata is copied from the first input file,
6291d7e4
AK
632per-stream and per-chapter metadata is copied along with streams/chapters. These
633default mappings are disabled by creating any mapping of the relevant type. A negative
634file index can be used to create a dummy mapping that just disables automatic copying.
635
636For example to copy metadata from the first stream of the input file to global metadata
637of the output file:
638@example
e6e6060c 639avconv -i in.ogg -map_metadata 0:s:0 out.mp3
6291d7e4 640@end example
172efad7 641@item -map_chapters @var{input_file_index} (@emph{output})
b9aac90b
AK
642Copy chapters from input file with index @var{input_file_index} to the next
643output file. If no chapter mapping is specified, then chapters are copied from
644the first input file with at least one chapter. Use a negative file index to
645disable any chapter copying.
6291d7e4
AK
646@item -debug
647Print specific debug info.
172efad7 648@item -benchmark (@emph{global})
6291d7e4
AK
649Show benchmarking information at the end of an encode.
650Shows CPU time used and maximum memory consumption.
651Maximum memory consumption is not supported on all systems,
652it will usually display as 0 if not supported.
5aa3fcec
AK
653@item -timelimit @var{duration} (@emph{global})
654Exit after avconv has been running for @var{duration} seconds.
172efad7 655@item -dump (@emph{global})
d159060a 656Dump each input packet to stderr.
172efad7 657@item -hex (@emph{global})
6291d7e4 658When dumping packets, also dump the payload.
6291d7e4
AK
659@item -ps @var{size}
660Set RTP payload size in bytes.
172efad7 661@item -re (@emph{input})
6291d7e4 662Read input at native frame rate. Mainly used to simulate a grab device.
6291d7e4
AK
663@item -threads @var{count}
664Thread count.
665@item -vsync @var{parameter}
666Video sync method.
667
668@table @option
669@item 0
670Each frame is passed with its timestamp from the demuxer to the muxer.
671@item 1
672Frames will be duplicated and dropped to achieve exactly the requested
673constant framerate.
674@item 2
675Frames are passed through with their timestamp or dropped so as to
676prevent 2 frames from having the same timestamp.
677@item -1
678Chooses between 1 and 2 depending on muxer capabilities. This is the
679default method.
680@end table
681
682With -map you can select from which stream the timestamps should be
683taken. You can leave either video or audio unchanged and sync the
684remaining stream(s) to the unchanged one.
685
686@item -async @var{samples_per_second}
687Audio sync method. "Stretches/squeezes" the audio stream to match the timestamps,
688the parameter is the maximum samples per second by which the audio is changed.
689-async 1 is a special case where only the start of the audio stream is corrected
690without any later correction.
691@item -copyts
692Copy timestamps from input to output.
693@item -copytb
694Copy input stream time base from input to output when stream copying.
695@item -shortest
696Finish encoding when the shortest input stream ends.
697@item -dts_delta_threshold
698Timestamp discontinuity delta threshold.
172efad7 699@item -muxdelay @var{seconds} (@emph{input})
6291d7e4 700Set the maximum demux-decode delay.
172efad7 701@item -muxpreload @var{seconds} (@emph{input})
6291d7e4 702Set the initial demux-decode delay.
172efad7 703@item -streamid @var{output-stream-index}:@var{new-value} (@emph{output})
6291d7e4
AK
704Assign a new stream-id value to an output stream. This option should be
705specified prior to the output filename to which it applies.
706For the situation where multiple output files exist, a streamid
707may be reassigned to a different value.
708
709For example, to set the stream 0 PID to 33 and the stream 1 PID to 36 for
710an output mpegts file:
711@example
712avconv -i infile -streamid 0:33 -streamid 1:36 out.ts
713@end example
d821cbe2 714
172efad7 715@item -bsf[:@var{stream_specifier}] @var{bitstream_filters} (@emph{output,per-stream})
d821cbe2
AK
716Set bitstream filters for matching streams. @var{bistream_filters} is
717a comma-separated list of bitstream filters. Use the @code{-bsfs} option
718to get the list of bitstream filters.
719@example
720avconv -i h264.mp4 -c:v copy -vbsf h264_mp4toannexb -an out.h264
721@end example
722@example
723avconv -i file.mov -an -vn -sbsf mov2textsub -c:s copy -f rawvideo sub.txt
724@end example
013887eb 725
172efad7 726@item -tag[:@var{stream_specifier}] @var{codec_tag} (@emph{output,per-stream})
013887eb 727Force a tag/fourcc for matching streams.
6291d7e4 728@end table
7478ab5a 729@c man end OPTIONS
6291d7e4 730
6291d7e4
AK
731@chapter Tips
732@c man begin TIPS
733
734@itemize
735@item
736For streaming at very low bitrate application, use a low frame rate
737and a small GOP size. This is especially true for RealVideo where
738the Linux player does not seem to be very fast, so it can miss
739frames. An example is:
740
741@example
742avconv -g 3 -r 3 -t 10 -b 50k -s qcif -f rv10 /tmp/b.rm
743@end example
744
745@item
746The parameter 'q' which is displayed while encoding is the current
747quantizer. The value 1 indicates that a very good quality could
748be achieved. The value 31 indicates the worst quality. If q=31 appears
749too often, it means that the encoder cannot compress enough to meet
750your bitrate. You must either increase the bitrate, decrease the
751frame rate or decrease the frame size.
752
753@item
754If your computer is not fast enough, you can speed up the
755compression at the expense of the compression ratio. You can use
756'-me zero' to speed up motion estimation, and '-intra' to disable
757motion estimation completely (you have only I-frames, which means it
758is about as good as JPEG compression).
759
760@item
761To have very low audio bitrates, reduce the sampling frequency
762(down to 22050 Hz for MPEG audio, 22050 or 11025 for AC-3).
763
764@item
765To have a constant quality (but a variable bitrate), use the option
766'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
767quality).
768
6291d7e4
AK
769@end itemize
770@c man end TIPS
771
772@chapter Examples
773@c man begin EXAMPLES
774
3ec34462
AK
775@section Preset files
776
777A preset file contains a sequence of @var{option=value} pairs, one for
778each line, specifying a sequence of options which can be specified also on
779the command line. Lines starting with the hash ('#') character are ignored and
780are used to provide comments. Empty lines are also ignored. Check the
8096fdf0 781@file{presets} directory in the Libav source tree for examples.
3ec34462
AK
782
783Preset files are specified with the @code{pre} option, this option takes a
784preset name as input. Avconv searches for a file named @var{preset_name}.avpreset in
785the directories @file{$AVCONV_DATADIR} (if set), and @file{$HOME/.avconv}, and in
786the data directory defined at configuration time (usually @file{$PREFIX/share/avconv})
787in that order. For example, if the argument is @code{libx264-max}, it will
788search for the file @file{libx264-max.avpreset}.
789
6291d7e4
AK
790@section Video and Audio grabbing
791
792If you specify the input format and device then avconv can grab video
793and audio directly.
794
795@example
796avconv -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
797@end example
798
799Note that you must activate the right video source and channel before
800launching avconv with any TV viewer such as
801@uref{http://linux.bytesex.org/xawtv/, xawtv} by Gerd Knorr. You also
802have to set the audio recording levels correctly with a
803standard mixer.
804
805@section X11 grabbing
806
807Grab the X11 display with avconv via
808
809@example
810avconv -f x11grab -s cif -r 25 -i :0.0 /tmp/out.mpg
811@end example
812
8130.0 is display.screen number of your X11 server, same as
814the DISPLAY environment variable.
815
816@example
817avconv -f x11grab -s cif -r 25 -i :0.0+10,20 /tmp/out.mpg
818@end example
819
8200.0 is display.screen number of your X11 server, same as the DISPLAY environment
821variable. 10 is the x-offset and 20 the y-offset for the grabbing.
822
823@section Video and Audio file format conversion
824
825Any supported file format and protocol can serve as input to avconv:
826
827Examples:
828@itemize
829@item
830You can use YUV files as input:
831
832@example
833avconv -i /tmp/test%d.Y /tmp/out.mpg
834@end example
835
836It will use the files:
837@example
838/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
839/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
840@end example
841
842The Y files use twice the resolution of the U and V files. They are
843raw files, without header. They can be generated by all decent video
844decoders. You must specify the size of the image with the @option{-s} option
845if avconv cannot guess it.
846
847@item
848You can input from a raw YUV420P file:
849
850@example
851avconv -i /tmp/test.yuv /tmp/out.avi
852@end example
853
854test.yuv is a file containing raw YUV planar data. Each frame is composed
855of the Y plane followed by the U and V planes at half vertical and
856horizontal resolution.
857
858@item
859You can output to a raw YUV420P file:
860
861@example
862avconv -i mydivx.avi hugefile.yuv
863@end example
864
865@item
866You can set several input files and output files:
867
868@example
869avconv -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
870@end example
871
872Converts the audio file a.wav and the raw YUV video file a.yuv
873to MPEG file a.mpg.
874
875@item
876You can also do audio and video conversions at the same time:
877
878@example
879avconv -i /tmp/a.wav -ar 22050 /tmp/a.mp2
880@end example
881
882Converts a.wav to MPEG audio at 22050 Hz sample rate.
883
884@item
885You can encode to several formats at the same time and define a
886mapping from input stream to output streams:
887
888@example
64db1a82 889avconv -i /tmp/a.wav -map 0:a -b 64k /tmp/a.mp2 -map 0:a -b 128k /tmp/b.mp2
6291d7e4
AK
890@end example
891
892Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
893file:index' specifies which input stream is used for each output
894stream, in the order of the definition of output streams.
895
896@item
897You can transcode decrypted VOBs:
898
899@example
64db1a82 900avconv -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
901@end example
902
903This is a typical DVD ripping example; the input is a VOB file, the
904output an AVI file with MPEG-4 video and MP3 audio. Note that in this
905command we use B-frames so the MPEG-4 stream is DivX5 compatible, and
906GOP size is 300 which means one intra frame every 10 seconds for 29.97fps
907input video. Furthermore, the audio stream is MP3-encoded so you need
908to enable LAME support by passing @code{--enable-libmp3lame} to configure.
909The mapping is particularly useful for DVD transcoding
910to get the desired audio language.
911
912NOTE: To see the supported input formats, use @code{avconv -formats}.
913
914@item
915You can extract images from a video, or create a video from many images:
916
917For extracting images from a video:
918@example
919avconv -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
920@end example
921
922This will extract one video frame per second from the video and will
923output them in files named @file{foo-001.jpeg}, @file{foo-002.jpeg},
924etc. Images will be rescaled to fit the new WxH values.
925
926If you want to extract just a limited number of frames, you can use the
927above command in combination with the -vframes or -t option, or in
928combination with -ss to start extracting from a certain point in time.
929
930For creating a video from many images:
931@example
932avconv -f image2 -i foo-%03d.jpeg -r 12 -s WxH foo.avi
933@end example
934
935The syntax @code{foo-%03d.jpeg} specifies to use a decimal number
936composed of three digits padded with zeroes to express the sequence
937number. It is the same syntax supported by the C printf function, but
938only formats accepting a normal integer are suitable.
939
940@item
941You can put many streams of the same type in the output:
942
943@example
92f1940e 944avconv -i test1.avi -i test2.avi -map 0.3 -map 0.2 -map 0.1 -map 0.0 -c copy test12.nut
6291d7e4
AK
945@end example
946
3d4f0dab
AK
947The resulting output file @file{test12.avi} will contain first four streams from
948the input file in reverse order.
6291d7e4
AK
949
950@end itemize
951@c man end EXAMPLES
952
953@include eval.texi
954@include encoders.texi
955@include demuxers.texi
956@include muxers.texi
957@include indevs.texi
958@include outdevs.texi
959@include protocols.texi
960@include bitstream_filters.texi
961@include filters.texi
962@include metadata.texi
963
964@ignore
965
966@setfilename avconv
967@settitle avconv video converter
968
969@c man begin SEEALSO
970avplay(1), avprobe(1), avserver(1) and the Libav HTML documentation
971@c man end
972
973@c man begin AUTHORS
974The Libav developers
975@c man end
976
977@end ignore
978
979@bye