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