Extend documentation for the ffmpeg -timestamp option.
[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).
a19caa0f 229@item -croptop @var{size}
4c5f7207 230Set top crop band size (in pixels).
a19caa0f 231@item -cropbottom @var{size}
4c5f7207 232Set bottom crop band size (in pixels).
a19caa0f 233@item -cropleft @var{size}
4c5f7207 234Set left crop band size (in pixels).
a19caa0f 235@item -cropright @var{size}
4c5f7207 236Set right crop band size (in pixels).
a19caa0f 237@item -padtop @var{size}
4c5f7207 238Set top pad band size (in pixels).
a19caa0f 239@item -padbottom @var{size}
4c5f7207 240Set bottom pad band size (in pixels).
a19caa0f 241@item -padleft @var{size}
4c5f7207 242Set left pad band size (in pixels).
a19caa0f 243@item -padright @var{size}
4c5f7207 244Set right pad band size (in pixels).
a19caa0f 245@item -padcolor @var{hex_color}
4c5f7207
DB
246Set color of padded bands. The value for padcolor is expressed
247as a six digit hexadecimal number where the first two digits
248represent red, the middle two digits green and last two digits
249blue (default = 000000 (black)).
9181577c 250@item -vn
4c5f7207 251Disable video recording.
a19caa0f 252@item -bt @var{tolerance}
e3576e25
JGG
253Set video bitrate tolerance (in bits, default 4000k).
254Has a minimum value of: (target_bitrate/target_framerate).
255In 1-pass mode, bitrate tolerance specifies how far ratecontrol is
256willing to deviate from the target average bitrate value. This is
257not related to min/max bitrate. Lowering tolerance too much has
258an adverse effect on quality.
a19caa0f 259@item -maxrate @var{bitrate}
f754bfb9 260Set max video bitrate (in bit/s).
bbc35f51 261Requires -bufsize to be set.
a19caa0f 262@item -minrate @var{bitrate}
f754bfb9 263Set min video bitrate (in bit/s).
bbc35f51 264Most useful in setting up a CBR encode:
265@example
266ffmpeg -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
267@end example
268It is of little use elsewise.
a19caa0f 269@item -bufsize @var{size}
fa78d895 270Set video buffer verifier buffer size (in bits).
a19caa0f 271@item -vcodec @var{codec}
4c5f7207 272Force video codec to @var{codec}. Use the @code{copy} special value to
5ee03c86 273tell that the raw codec data must be copied as is.
18bff752 274@item -sameq
4c5f7207 275Use same video quality as source (implies VBR).
9181577c 276
a19caa0f 277@item -pass @var{n}
c2902c9c
SS
278Select the pass number (1 or 2). It is used to do two-pass
279video encoding. The statistics of the video are recorded in the first
280pass into a log file (see also the option -passlogfile),
281and in the second pass that log file is used to generate the video
282at the exact requested bitrate.
850a8d42
ED
283On pass 1, you may just deactivate audio and set output to null,
284examples for Windows and Unix:
285@example
286ffmpeg -i foo.mov -vcodec libxvid -pass 1 -an -f rawvideo -y NUL
287ffmpeg -i foo.mov -vcodec libxvid -pass 1 -an -f rawvideo -y /dev/null
288@end example
9181577c 289
44fe7113
SS
290@item -passlogfile @var{prefix}
291Set two-pass log file name prefix to @var{prefix}, the default file name
292prefix is ``ffmpeg2pass''. The complete file name will be
293@file{PREFIX-N.log}, where N is a number specific to the output
c2902c9c 294stream.
9181577c 295
4386f941
DB
296@item -newvideo
297Add a new video stream to the current output stream.
298
0fc2c0f6
MC
299@item -vlang @var{code}
300Set the ISO 639 language code (3 letters) of the current video stream.
301
3275ac6a
SS
302@item -vf @var{filter_graph}
303@var{filter_graph} is a description of the filter graph to apply to
304the input video.
305Use the option "-filters" to show all the available filters (including
306also sources and sinks).
307
9181577c
FB
308@end table
309
18bff752 310@section Advanced Video Options
9181577c 311
e99c4e10 312@table @option
a19caa0f 313@item -pix_fmt @var{format}
c3b95b1d
SS
314Set pixel format. Use 'list' as parameter to show all the supported
315pixel formats.
a19caa0f 316@item -sws_flags @var{flags}
35a3bd84 317Set SwScaler flags.
a19caa0f 318@item -g @var{gop_size}
4c5f7207 319Set the group of pictures size.
115329f1 320@item -intra
4c5f7207 321Use only intra frames.
a19caa0f 322@item -vdt @var{n}
4386f941 323Discard threshold.
a19caa0f 324@item -qscale @var{q}
4bef236b 325Use fixed video quantizer scale (VBR).
a19caa0f 326@item -qmin @var{q}
4bef236b 327minimum video quantizer scale (VBR)
a19caa0f 328@item -qmax @var{q}
4bef236b 329maximum video quantizer scale (VBR)
a19caa0f 330@item -qdiff @var{q}
4bef236b 331maximum difference between the quantizer scales (VBR)
a19caa0f 332@item -qblur @var{blur}
3a9b190c 333video quantizer scale blur (VBR) (range 0.0 - 1.0)
a19caa0f 334@item -qcomp @var{compression}
3a9b190c 335video quantizer scale compression (VBR) (default 0.5).
336Constant of ratecontrol equation. Recommended range for default rc_eq: 0.0-1.0
18bff752 337
a19caa0f 338@item -lmin @var{lambda}
9ae711e1 339minimum video lagrange factor (VBR)
a19caa0f 340@item -lmax @var{lambda}
9ae711e1 341max video lagrange factor (VBR)
a19caa0f 342@item -mblmin @var{lambda}
9ae711e1 343minimum macroblock quantizer scale (VBR)
a19caa0f 344@item -mblmax @var{lambda}
9ae711e1
VP
345maximum macroblock quantizer scale (VBR)
346
347These four options (lmin, lmax, mblmin, mblmax) use 'lambda' units,
348but you may use the QP2LAMBDA constant to easily convert from 'q' units:
349@example
350ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
351@end example
352
a19caa0f 353@item -rc_init_cplx @var{complexity}
4c5f7207 354initial complexity for single pass encoding
a19caa0f 355@item -b_qfactor @var{factor}
4c5f7207 356qp factor between P- and B-frames
a19caa0f 357@item -i_qfactor @var{factor}
4c5f7207 358qp factor between P- and I-frames
a19caa0f 359@item -b_qoffset @var{offset}
4c5f7207 360qp offset between P- and B-frames
a19caa0f 361@item -i_qoffset @var{offset}
4c5f7207 362qp offset between P- and I-frames
a19caa0f 363@item -rc_eq @var{equation}
4c5f7207
DB
364Set rate control equation (@pxref{FFmpeg formula
365evaluator}) (default = @code{tex^qComp}).
a19caa0f 366@item -rc_override @var{override}
5ee03c86 367rate control override for specific intervals
a19caa0f 368@item -me_method @var{method}
4c5f7207
DB
369Set motion estimation method to @var{method}.
370Available methods are (from lowest to best quality):
18bff752
FB
371@table @samp
372@item zero
5ee03c86 373Try just the (0, 0) vector.
18bff752
FB
374@item phods
375@item log
376@item x1
c0de00da
SS
377@item hex
378@item umh
18bff752
FB
379@item epzs
380(default method)
381@item full
382exhaustive search (slow and marginally better than epzs)
383@end table
384
a19caa0f 385@item -dct_algo @var{algo}
4c5f7207 386Set DCT algorithm to @var{algo}. Available values are:
18bff752
FB
387@table @samp
388@item 0
389FF_DCT_AUTO (default)
390@item 1
391FF_DCT_FASTINT
392@item 2
393FF_DCT_INT
394@item 3
395FF_DCT_MMX
396@item 4
397FF_DCT_MLIB
398@item 5
399FF_DCT_ALTIVEC
400@end table
401
a19caa0f 402@item -idct_algo @var{algo}
4c5f7207 403Set IDCT algorithm to @var{algo}. Available values are:
18bff752
FB
404@table @samp
405@item 0
406FF_IDCT_AUTO (default)
407@item 1
115329f1 408FF_IDCT_INT
18bff752 409@item 2
115329f1 410FF_IDCT_SIMPLE
18bff752 411@item 3
115329f1 412FF_IDCT_SIMPLEMMX
18bff752 413@item 4
115329f1 414FF_IDCT_LIBMPEG2MMX
18bff752 415@item 5
115329f1 416FF_IDCT_PS2
18bff752 417@item 6
115329f1 418FF_IDCT_MLIB
18bff752 419@item 7
115329f1 420FF_IDCT_ARM
18bff752 421@item 8
115329f1 422FF_IDCT_ALTIVEC
18bff752 423@item 9
115329f1 424FF_IDCT_SH4
18bff752 425@item 10
115329f1 426FF_IDCT_SIMPLEARM
18bff752
FB
427@end table
428
a19caa0f 429@item -er @var{n}
4c5f7207 430Set error resilience to @var{n}.
18bff752 431@table @samp
115329f1 432@item 1
1471c6c2 433FF_ER_CAREFUL (default)
18bff752 434@item 2
5ee03c86 435FF_ER_COMPLIANT
18bff752
FB
436@item 3
437FF_ER_AGGRESSIVE
438@item 4
439FF_ER_VERY_AGGRESSIVE
440@end table
441
a19caa0f 442@item -ec @var{bit_mask}
4c5f7207 443Set error concealment to @var{bit_mask}. @var{bit_mask} is a bit mask of
5ee03c86 444the following values:
18bff752
FB
445@table @samp
446@item 1
4c5f7207 447FF_EC_GUESS_MVS (default = enabled)
18bff752 448@item 2
4c5f7207 449FF_EC_DEBLOCK (default = enabled)
18bff752
FB
450@end table
451
a19caa0f 452@item -bf @var{frames}
4c5f7207 453Use 'frames' B-frames (supported for MPEG-1, MPEG-2 and MPEG-4).
a19caa0f 454@item -mbd @var{mode}
18bff752
FB
455macroblock decision
456@table @samp
457@item 0
4c5f7207 458FF_MB_DECISION_SIMPLE: Use mb_cmp (cannot change it yet in FFmpeg).
18bff752 459@item 1
4c5f7207 460FF_MB_DECISION_BITS: Choose the one which needs the fewest bits.
18bff752 461@item 2
019c8838 462FF_MB_DECISION_RD: rate distortion
18bff752
FB
463@end table
464
465@item -4mv
4c5f7207 466Use four motion vector by macroblock (MPEG-4 only).
18bff752 467@item -part
4c5f7207 468Use data partitioning (MPEG-4 only).
a19caa0f 469@item -bug @var{param}
4c5f7207 470Work around encoder bugs that are not auto-detected.
a19caa0f 471@item -strict @var{strictness}
4c5f7207 472How strictly to follow the standards.
5ee03c86 473@item -aic
4c5f7207 474Enable Advanced intra coding (h263+).
5ee03c86 475@item -umv
4c5f7207 476Enable Unlimited Motion Vector (h263+)
18bff752
FB
477
478@item -deinterlace
4c5f7207 479Deinterlace pictures.
3841e813 480@item -ilme
4c5f7207
DB
481Force interlacing support in encoder (MPEG-2 and MPEG-4 only).
482Use this option if your input file is interlaced and you want
483to keep the interlaced format for minimum losses.
484The alternative is to deinterlace the input stream with
485@option{-deinterlace}, but deinterlacing introduces losses.
18bff752 486@item -psnr
4c5f7207 487Calculate PSNR of compressed frames.
18bff752 488@item -vstats
4c5f7207 489Dump video coding statistics to @file{vstats_HHMMSS.log}.
a19caa0f 490@item -vstats_file @var{file}
b60d1379 491Dump video coding statistics to @var{file}.
a19caa0f 492@item -top @var{n}
4386f941 493top=1/bottom=0/auto=-1 field first
a19caa0f 494@item -dc @var{precision}
4386f941 495Intra_dc_precision.
a19caa0f 496@item -vtag @var{fourcc/tag}
4386f941
DB
497Force video tag/fourcc.
498@item -qphist
499Show QP histogram.
a19caa0f 500@item -vbsf @var{bitstream_filter}
5ad2b4c6 501Bitstream filters available are "dump_extra", "remove_extra", "noise", "h264_mp4toannexb", "imxdump", "mjpegadump".
502@example
503ffmpeg -i h264.mp4 -vcodec copy -vbsf h264_mp4toannexb -an out.h264
504@end example
18bff752
FB
505@end table
506
507@section Audio Options
508
509@table @option
a19caa0f 510@item -aframes @var{number}
4386f941 511Set the number of audio frames to record.
a19caa0f 512@item -ar @var{freq}
4c5f7207 513Set the audio sampling frequency (default = 44100 Hz).
a19caa0f 514@item -ab @var{bitrate}
5438308f 515Set the audio bitrate in bit/s (default = 64k).
385e1658
JVS
516@item -aq @var{q}
517Set the audio quality (codec-specific, VBR).
a19caa0f 518@item -ac @var{channels}
4c5f7207 519Set the number of audio channels (default = 1).
5ee03c86 520@item -an
4c5f7207 521Disable audio recording.
a19caa0f 522@item -acodec @var{codec}
4c5f7207
DB
523Force audio codec to @var{codec}. Use the @code{copy} special value to
524specify that the raw codec data must be copied as is.
de62a89d 525@item -newaudio
18fd519f
DB
526Add a new audio track to the output file. If you want to specify parameters,
527do so before @code{-newaudio} (@code{-acodec}, @code{-ab}, etc..).
de62a89d 528
18fd519f
DB
529Mapping will be done automatically, if the number of output streams is equal to
530the number of input streams, else it will pick the first one that matches. You
de62a89d
VP
531can override the mapping using @code{-map} as usual.
532
533Example:
534@example
5438308f 535ffmpeg -i file.mpg -vcodec copy -acodec ac3 -ab 384k test.mpg -acodec mp2 -ab 192k -newaudio
de62a89d 536@end example
a19caa0f 537@item -alang @var{code}
4386f941
DB
538Set 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
a19caa0f 544@item -atag @var{fourcc/tag}
4386f941 545Force audio tag/fourcc.
a19caa0f 546@item -absf @var{bitstream_filter}
4386f941
DB
547Bitstream filters available are "dump_extra", "remove_extra", "noise", "mp3comp", "mp3decomp".
548@end table
549
550@section Subtitle options:
551
552@table @option
a19caa0f 553@item -scodec @var{codec}
4386f941
DB
554Force subtitle codec ('copy' to copy stream).
555@item -newsubtitle
556Add a new subtitle stream to the current output stream.
a19caa0f 557@item -slang @var{code}
4386f941 558Set the ISO 639 language code (3 letters) of the current subtitle stream.
f0ef7bee
DB
559@item -sn
560Disable subtitle recording.
5ad2b4c6 561@item -sbsf @var{bitstream_filter}
562Bitstream filters available are "mov2textsub", "text2movsub".
563@example
564ffmpeg -i file.mov -an -vn -sbsf mov2textsub -scodec copy -f rawvideo sub.txt
565@end example
18bff752
FB
566@end table
567
568@section Audio/Video grab options
569
570@table @option
a19caa0f 571@item -vc @var{channel}
4c5f7207 572Set video grab channel (DV1394 only).
a19caa0f 573@item -tvstd @var{standard}
4c5f7207 574Set television standard (NTSC, PAL (SECAM)).
cc58300e
RP
575@item -isync
576Synchronize read on input.
18bff752
FB
577@end table
578
579@section Advanced options
580
581@table @option
bb89b0bc 582@item -map @var{input_stream_id}[:@var{sync_stream_id}]
e645a733
BL
583Set stream mapping from input streams to output streams.
584Just enumerate the input streams in the order you want them in the output.
bb89b0bc
SS
585@var{sync_stream_id} if specified sets the input stream to sync
586against.
a19caa0f
SS
587@item -map_meta_data @var{outfile}:@var{infile}
588Set meta data information of @var{outfile} from @var{infile}.
18bff752 589@item -debug
4c5f7207 590Print specific debug info.
115329f1 591@item -benchmark
fc5607f8
RD
592Show benchmarking information at the end of an encode.
593Shows CPU time used and maximum memory consumption.
594Maximum memory consumption is not supported on all systems,
595it will usually display as 0 if not supported.
4386f941 596@item -dump
4c5f7207 597Dump each input packet.
4386f941
DB
598@item -hex
599When dumping packets, also dump the payload.
18bff752 600@item -bitexact
4c5f7207 601Only use bit exact algorithms (for codec testing).
a19caa0f 602@item -ps @var{size}
2b12317a 603Set RTP payload size in bytes.
5ee03c86 604@item -re
4c5f7207 605Read input at native frame rate. Mainly used to simulate a grab device.
4386f941 606@item -loop_input
4c5f7207
DB
607Loop over the input stream. Currently it works only for image
608streams. This option is used for automatic FFserver testing.
a19caa0f 609@item -loop_output @var{number_of_times}
019c8838 610Repeatedly loop output for formats that support looping such as animated GIF
4c5f7207 611(0 will loop the output infinitely).
a19caa0f 612@item -threads @var{count}
4386f941 613Thread count.
a19caa0f 614@item -vsync @var{parameter}
49553ec8
MN
615Video sync method.
6160 Each frame is passed with its timestamp from the demuxer to the muxer
c7512f6b 6171 Frames will be duplicated and dropped to achieve exactly the requested
49553ec8 618 constant framerate.
c7512f6b
JM
6192 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.
49553ec8
MN
622
623With -map you can select from
29c9183c 624which stream the timestamps should be taken. You can leave either video or
c52e13f1 625audio unchanged and sync the remaining stream(s) to the unchanged one.
a19caa0f 626@item -async @var{samples_per_second}
29c9183c 627Audio sync method. "Stretches/squeezes" the audio stream to match the timestamps,
c52e13f1
BL
628the 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
630without any later correction.
43399718
VP
631@item -copyts
632Copy timestamps from input to output.
633@item -shortest
634Finish encoding when the shortest input stream ends.
635@item -dts_delta_threshold
636Timestamp discontinuity delta threshold.
a19caa0f 637@item -muxdelay @var{seconds}
43399718 638Set the maximum demux-decode delay.
a19caa0f 639@item -muxpreload @var{seconds}
43399718 640Set the initial demux-decode delay.
9181577c 641@end table
18bff752 642
4a60e574
SS
643@section Preset files
644
645A preset file contains a sequence of @var{option}=@var{value} pairs,
646one for each line, specifying a sequence of options which would be
647awkward to specify on the command line. Lines starting with the hash
648('#') character are ignored and are used to provide comments. Check
649the @file{ffpresets} directory in the FFmpeg source tree for examples.
650
35c504b6
RP
651Preset files are specified with the @code{vpre}, @code{apre},
652@code{spre}, and @code{fpre} options. The @code{fpre} option takes the
653filename of the preset instead of a preset name as input and can be
654used for any kind of codec. For the @code{vpre}, @code{apre}, and
655@code{spre} options, the options specified in a preset file are
66e9aa74
SS
656applied to the currently selected codec of the same type as the preset
657option.
4a60e574 658
35c504b6
RP
659The argument passed to the @code{vpre}, @code{apre}, and @code{spre}
660preset options identifies the preset file to use according to the
661following rules:
4a60e574
SS
662
663First ffmpeg searches for a file named @var{arg}.ffpreset in the
2328e5a2
RK
664directories @file{$FFMPEG_DATADIR} (if set), and @file{$HOME/.ffmpeg}, and in
665the datadir defined at configuration time (usually @file{PREFIX/share/ffmpeg})
666in that order. For example, if the argument is @code{libx264-max}, it will
bd591ead 667search for the file @file{libx264-max.ffpreset}.
4a60e574
SS
668
669If no such file is found, then ffmpeg will search for a file named
670@var{codec_name}-@var{arg}.ffpreset in the above-mentioned
671directories, where @var{codec_name} is the name of the codec to which
672the preset file options will be applied. For example, if you select
673the video codec with @code{-vcodec libx264} and use @code{-vpre max},
674then it will search for the file @file{libx264-max.ffpreset}.
675
72cdcc0b 676@anchor{FFmpeg formula evaluator}
18bff752
FB
677@section FFmpeg formula evaluator
678
679When evaluating a rate control string, FFmpeg uses an internal formula
115329f1 680evaluator.
18bff752
FB
681
682The following binary operators are available: @code{+}, @code{-},
683@code{*}, @code{/}, @code{^}.
684
685The following unary operators are available: @code{+}, @code{-},
686@code{(...)}.
687
17bdc290
VP
688The following statements are available: @code{ld}, @code{st},
689@code{while}.
690
18bff752
FB
691The 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)
593b3219
VP
699@item atan(x)
700@item asin(x)
701@item acos(x)
18bff752
FB
702@item exp(x)
703@item log(x)
593b3219 704@item abs(x)
18bff752
FB
705@item squish(x)
706@item gauss(x)
593b3219 707@item mod(x, y)
18bff752
FB
708@item max(x, y)
709@item min(x, y)
593b3219
VP
710@item eq(x, y)
711@item gte(x, y)
18bff752 712@item gt(x, y)
593b3219 713@item lte(x, y)
18bff752 714@item lt(x, y)
18bff752
FB
715@item bits2qp(bits)
716@item qp2bits(qp)
717@end table
718
719The 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
e99c4e10
FB
743@c man end
744
9181577c
FB
745@section Protocols
746
831ec935 747The file name can be @file{-} to read from standard input or to write
4c5f7207 748to standard output.
9181577c 749
4c5f7207 750FFmpeg also handles many protocols specified with an URL syntax.
9181577c 751
0584b718 752Use 'ffmpeg -protocols' to see a list of the supported protocols.
9181577c 753
e99c4e10 754The protocol @code{http:} is currently used only to communicate with
4c5f7207 755FFserver (see the FFserver documentation). When FFmpeg will be a
e99c4e10 756video player it will also be used for streaming :-)
9181577c
FB
757
758@chapter Tips
9f41ed5a 759@c man begin TIPS
9181577c
FB
760
761@itemize
9f41ed5a
SS
762@item
763For streaming at very low bitrate application, use a low frame rate
4c5f7207 764and a small GOP size. This is especially true for RealVideo where
e99c4e10
FB
765the Linux player does not seem to be very fast, so it can miss
766frames. An example is:
9181577c
FB
767
768@example
3c0ba870 769ffmpeg -g 3 -r 3 -t 10 -b 50k -s qcif -f rv10 /tmp/b.rm
9181577c
FB
770@end example
771
9f41ed5a
SS
772@item
773The parameter 'q' which is displayed while encoding is the current
4c5f7207
DB
774quantizer. The value 1 indicates that a very good quality could
775be achieved. The value 31 indicates the worst quality. If q=31 appears
e99c4e10 776too often, it means that the encoder cannot compress enough to meet
4c5f7207 777your bitrate. You must either increase the bitrate, decrease the
e99c4e10 778frame rate or decrease the frame size.
9181577c 779
9f41ed5a
SS
780@item
781If your computer is not fast enough, you can speed up the
e99c4e10
FB
782compression at the expense of the compression ratio. You can use
783'-me zero' to speed up motion estimation, and '-intra' to disable
4c5f7207 784motion estimation completely (you have only I-frames, which means it
e99c4e10 785is about as good as JPEG compression).
9181577c 786
9f41ed5a
SS
787@item
788To have very low audio bitrates, reduce the sampling frequency
c27c66c3 789(down to 22050 Hz for MPEG audio, 22050 or 11025 for AC-3).
9181577c 790
9f41ed5a
SS
791@item
792To have a constant quality (but a variable bitrate), use the option
e99c4e10
FB
793'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
794quality).
9181577c 795
9f41ed5a
SS
796@item
797When converting video files, you can use the '-sameq' option which
4c5f7207
DB
798uses the same quality factor in the encoder as in the decoder.
799It allows almost lossless encoding.
9181577c
FB
800
801@end itemize
9f41ed5a 802@c man end TIPS
9181577c 803
76561924
SS
804@chapter Examples
805@c man begin EXAMPLES
806
807@section Video and Audio grabbing
808
809FFmpeg can grab video and audio from devices given that you specify the input
810format and device.
811
812@example
813ffmpeg -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
814@end example
815
816Note that you must activate the right video source and channel before
817launching FFmpeg with any TV viewer such as xawtv
818(@url{http://linux.bytesex.org/xawtv/}) by Gerd Knorr. You also
819have to set the audio recording levels correctly with a
820standard mixer.
821
822@section X11 grabbing
823
824FFmpeg can grab the X11 display.
825
826@example
827ffmpeg -f x11grab -s cif -i :0.0 /tmp/out.mpg
828@end example
829
8300.0 is display.screen number of your X11 server, same as
831the DISPLAY environment variable.
832
833@example
834ffmpeg -f x11grab -s cif -i :0.0+10,20 /tmp/out.mpg
835@end example
836
8370.0 is display.screen number of your X11 server, same as the DISPLAY environment
838variable. 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
844Examples:
845
846* You can use YUV files as input:
847
848@example
849ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
850@end example
851
852It 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
858The Y files use twice the resolution of the U and V files. They are
859raw files, without header. They can be generated by all decent video
860decoders. You must specify the size of the image with the @option{-s} option
861if FFmpeg cannot guess it.
862
863* You can input from a raw YUV420P file:
864
865@example
866ffmpeg -i /tmp/test.yuv /tmp/out.avi
867@end example
868
869test.yuv is a file containing raw YUV planar data. Each frame is composed
870of the Y plane followed by the U and V planes at half vertical and
871horizontal resolution.
872
873* You can output to a raw YUV420P file:
874
875@example
876ffmpeg -i mydivx.avi hugefile.yuv
877@end example
878
879* You can set several input files and output files:
880
881@example
882ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
883@end example
884
885Converts the audio file a.wav and the raw YUV video file a.yuv
886to MPEG file a.mpg.
887
888* You can also do audio and video conversions at the same time:
889
890@example
891ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
892@end example
893
894Converts 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
897mapping from input stream to output streams:
898
899@example
900ffmpeg -i /tmp/a.wav -ab 64k /tmp/a.mp2 -ab 128k /tmp/b.mp2 -map 0:0 -map 0:0
901@end example
902
903Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
904file:index' specifies which input stream is used for each output
905stream, in the order of the definition of output streams.
906
907* You can transcode decrypted VOBs:
908
909@example
910ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800k -g 300 -bf 2 -acodec libmp3lame -ab 128k snatch.avi
911@end example
912
913This is a typical DVD ripping example; the input is a VOB file, the
914output an AVI file with MPEG-4 video and MP3 audio. Note that in this
915command we use B-frames so the MPEG-4 stream is DivX5 compatible, and
916GOP size is 300 which means one intra frame every 10 seconds for 29.97fps
917input video. Furthermore, the audio stream is MP3-encoded so you need
918to enable LAME support by passing @code{--enable-libmp3lame} to configure.
919The mapping is particularly useful for DVD transcoding
920to get the desired audio language.
921
922NOTE: 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
926For extracting images from a video:
927@example
928ffmpeg -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
929@end example
930
931This will extract one video frame per second from the video and will
932output them in files named @file{foo-001.jpeg}, @file{foo-002.jpeg},
933etc. Images will be rescaled to fit the new WxH values.
934
935If you want to extract just a limited number of frames, you can use the
936above command in combination with the -vframes or -t option, or in
937combination with -ss to start extracting from a certain point in time.
938
939For creating a video from many images:
940@example
941ffmpeg -f image2 -i foo-%03d.jpeg -r 12 -s WxH foo.avi
942@end example
943
944The syntax @code{foo-%03d.jpeg} specifies to use a decimal number
945composed of three digits padded with zeroes to express the sequence
946number. It is the same syntax supported by the C printf function, but
947only formats accepting a normal integer are suitable.
948
949* You can put many streams of the same type in the output:
950
951@example
952ffmpeg -i test1.avi -i test2.avi -vcodec copy -acodec copy -vcodec copy -acodec copy test12.avi -newvideo -newaudio
953@end example
954
955In addition to the first video and audio streams, the resulting
956output file @file{test12.avi} will contain the second video
957and the second audio stream found in the input streams list.
958
959The @code{-newvideo}, @code{-newaudio} and @code{-newsubtitle}
960options have to be specified immediately after the name of the output
961file to which you want to add them.
962@c man end EXAMPLES
963
3275ac6a
SS
964@include filters.texi
965
cadbccb6
SS
966@ignore
967
968@setfilename ffmpeg
969@settitle FFmpeg video converter
970
971@c man begin SEEALSO
b26247ed 972ffplay(1), ffprobe(1), ffserver(1) and the FFmpeg HTML documentation
cadbccb6
SS
973@c man end
974
aeadb328
SS
975@c man begin AUTHORS
976The FFmpeg developers
cadbccb6
SS
977@c man end
978
979@end ignore
980
9181577c 981@bye