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