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