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