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