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