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