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