ffmpeg-doc.texi 54.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
\input texinfo @c -*- texinfo -*-

@settitle FFmpeg Documentation
@titlepage
@sp 7
@center @titlefont{FFmpeg Documentation}
@sp 3
@end titlepage


@chapter Introduction

FFmpeg is a very fast video and audio converter. It can also grab from
a live audio/video source.
15

16
The command line interface is designed to be intuitive, in the sense
diego's avatar
diego committed
17 18 19
that FFmpeg tries to figure out all parameters that can possibly be
derived automatically. You usually only have to specify the target
bitrate you want.
20 21 22 23 24 25

FFmpeg can also convert from any sample rate to any other, and resize
video on the fly with a high quality polyphase filter.

@chapter Quick Start

26
@c man begin EXAMPLES
27 28
@section Video and Audio grabbing

29 30 31
FFmpeg can use a video4linux compatible video source and any Open Sound
System audio source:

32
@example
33
ffmpeg /tmp/out.mpg
34 35
@end example

36
Note that you must activate the right video source and channel before
diego's avatar
diego committed
37 38 39
launching FFmpeg with any TV viewer such as xawtv
(@url{http://bytesex.org/xawtv/}) by Gerd Knorr. You also
have to set the audio recording levels correctly with a
40
standard mixer.
41

bcoudurier's avatar
bcoudurier committed
42 43
@section X11 grabbing

diego's avatar
diego committed
44
FFmpeg can grab the X11 display.
bcoudurier's avatar
bcoudurier committed
45 46 47 48 49

@example
ffmpeg -f x11grab -vd x11:0.0 /tmp/out.mpg
@end example

diego's avatar
diego committed
50 51
0.0 is display.screen number of your X11 server, same as
the DISPLAY environment variable.
bcoudurier's avatar
bcoudurier committed
52

53 54 55 56 57 58 59
@example
ffmpeg -f x11grab -vd x11:0.0+10,20 /tmp/out.mpg
@end example

0.0 is display.screen number of your X11 server, same as the DISPLAY environment
variable. 10 is the x-offset and 20 the y-offset for the grabbing.

60
@section Video and Audio file format conversion
61

diego's avatar
diego committed
62
* FFmpeg can use any supported file format and protocol as input:
63 64 65

Examples:

diego's avatar
diego committed
66
* You can use YUV files as input:
67 68

@example
69
ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
70 71
@end example

72
It will use the files:
73
@example
74 75
/tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
/tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
76 77
@end example

78 79 80
The Y files use twice the resolution of the U and V files. They are
raw files, without header. They can be generated by all decent video
decoders. You must specify the size of the image with the @option{-s} option
diego's avatar
diego committed
81
if FFmpeg cannot guess it.
82

diego's avatar
diego committed
83
* You can input from a raw YUV420P file:
84 85

@example
86
ffmpeg -i /tmp/test.yuv /tmp/out.avi
87 88
@end example

diego's avatar
diego committed
89 90
test.yuv is a file containing raw YUV planar data. Each frame is composed
of the Y plane followed by the U and V planes at half vertical and
91
horizontal resolution.
92

diego's avatar
diego committed
93
* You can output to a raw YUV420P file:
94 95

@example
96
ffmpeg -i mydivx.avi hugefile.yuv
97 98 99 100 101
@end example

* You can set several input files and output files:

@example
102
ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
103 104
@end example

diego's avatar
diego committed
105 106
Converts the audio file a.wav and the raw YUV video file a.yuv
to MPEG file a.mpg.
107

108
* You can also do audio and video conversions at the same time:
109 110

@example
111
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
112 113
@end example

diego's avatar
diego committed
114
Converts a.wav to MPEG audio at 22050Hz sample rate.
115 116

* You can encode to several formats at the same time and define a
117
mapping from input stream to output streams:
118 119

@example
120
ffmpeg -i /tmp/a.wav -ab 64 /tmp/a.mp2 -ab 128 /tmp/b.mp2 -map 0:0 -map 0:0
121 122
@end example

diego's avatar
diego committed
123 124
Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
file:index' specifies which input stream is used for each output
125
stream, in the order of the definition of output streams.
126 127 128 129

* You can transcode decrypted VOBs

@example
130
ffmpeg -i snatch_1.vob -f avi -vcodec mpeg4 -b 800k -g 300 -bf 2 -acodec mp3 -ab 128 snatch.avi
131 132
@end example

diego's avatar
diego committed
133 134 135 136 137 138 139
This is a typical DVD ripping example; the input is a VOB file, the
output an AVI file with MPEG-4 video and MP3 audio. Note that in this
command we use B-frames so the MPEG-4 stream is DivX5 compatible, and
GOP size is 300 which means one intra frame every 10 seconds for 29.97fps
input video. Furthermore, the audio stream is MP3-encoded so you need
to enable LAME support by passing @code{--enable-mp3lame} to configure.
The mapping is particularly useful for DVD transcoding
140
to get the desired audio language.
141

diego's avatar
diego committed
142
NOTE: To see the supported input formats, use @code{ffmpeg -formats}.
143
@c man end
144 145 146 147 148

@chapter Invocation

@section Syntax

149
The generic syntax is:
150

151
@example
152
@c man begin SYNOPSIS
michael's avatar
michael committed
153
ffmpeg [[infile options][@option{-i} @var{infile}]]... @{[outfile options] @var{outfile}@}...
154
@c man end
155
@end example
156 157
@c man begin DESCRIPTION
If no input file is given, audio/video grabbing is done.
158

159
As a general rule, options are applied to the next specified
160
file. Therefore, order is important, and you can have the same
diego's avatar
typo  
diego committed
161
option on the command line multiple times. Each occurrence is
162 163
then applied to the next input or output file.

diego's avatar
diego committed
164
* To set the video bitrate of the output file to 64kbit/s:
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
@example
ffmpeg -i input.avi -b 64k output.avi
@end example

* To force the frame rate of the input and output file to 24 fps:
@example
ffmpeg -r 24 -i input.avi output.avi
@end example

* To force the frame rate of the output file to 24 fps:
@example
ffmpeg -i input.avi -r 24 output.avi
@end example

* To force the frame rate of input file to 1 fps and the output file to 24 fps:
@example
ffmpeg -r 1 -i input.avi -r 24 output.avi
@end example

The format option may be needed for raw input files.
185

diego's avatar
diego committed
186 187
By default, FFmpeg tries to convert as losslessly as possible: It
uses the same audio and video parameters for the outputs as the one
188 189
specified for the inputs.
@c man end
190

191
@c man begin OPTIONS
192 193
@section Main options

194
@table @option
195
@item -L
diego's avatar
diego committed
196
Show license.
bellard's avatar
bellard committed
197

198
@item -h
diego's avatar
diego committed
199
Show help.
bellard's avatar
bellard committed
200

201 202 203
@item -version
Show version.

204
@item -formats
diego's avatar
diego committed
205
Show available formats, codecs, protocols, ...
bellard's avatar
bellard committed
206

207
@item -f fmt
diego's avatar
diego committed
208
Force format.
bellard's avatar
bellard committed
209

210
@item -i filename
diego's avatar
diego committed
211
input filename
212

213
@item -y
diego's avatar
diego committed
214
Overwrite output files.
215

216
@item -t duration
diego's avatar
diego committed
217 218
Set the recording time in seconds.
@code{hh:mm:ss[.xxx]} syntax is also supported.
219

220 221 222
@item -fs limit_size
Set the file size limit.

223
@item -ss position
diego's avatar
diego committed
224 225
Seek to given time position in seconds.
@code{hh:mm:ss[.xxx]} syntax is also supported.
226

227 228 229 230 231 232 233 234
@item -itsoffset offset
Set the input time offset in seconds.
@code{[-]hh:mm:ss[.xxx]} syntax is also supported.
This option affects all the input files that follow it.
The offset is added to the timestamps of the input files.
Specifying a positive offset means that the corresponding
streams are delayed by 'offset' seconds.

235
@item -title string
diego's avatar
diego committed
236
Set the title.
237

238 239 240
@item -timestamp time
Set the timestamp.

241
@item -author string
diego's avatar
diego committed
242
Set the author.
243

244
@item -copyright string
diego's avatar
diego committed
245
Set the copyright.
246

247
@item -comment string
diego's avatar
diego committed
248
Set the comment.
249

250 251 252
@item -album string
Set the album.

253 254 255 256 257 258
@item -track number
Set the track.

@item -year number
Set the year.

259 260 261
@item -v verbose
Control amount of logging.

bellard's avatar
bellard committed
262
@item -target type
263
Specify target file type ("vcd", "svcd", "dvd", "dv", "dv50", "pal-vcd",
diego's avatar
diego committed
264 265
"ntsc-svcd", ... ). All the format options (bitrate, codecs,
buffer sizes) are then set automatically. You can just type:
bellard's avatar
bellard committed
266 267 268 269 270

@example
ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
@end example

diego's avatar
diego committed
271 272
Nevertheless you can specify additional options as long as you know
they do not conflict with the standard, as in:
273 274 275 276 277

@example
ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
@end example

278 279 280 281 282 283 284 285 286 287 288
@item -dframes number
Set the number of data frames to record.

@item -scodec codec
Force subtitle codec ('copy' to copy stream).

@item -newsubtitle
Add a new subtitle stream to the current output stream.

@item -slang code
Set the ISO 639 language code (3 letters) of the current subtitle stream.
289

290 291 292 293
@end table

@section Video Options

294
@table @option
295
@item -b bitrate
296
Set the video bitrate in bit/s (default = 200 kb/s).
297 298
@item -vframes number
Set the number of video frames to record.
299
@item -r fps
300
Set frame rate (Hz value, fraction or abbreviation), (default = 25).
301
@item -s size
diego's avatar
diego committed
302 303
Set frame size. The format is @samp{wxh} (default = 160x128).
The following abbreviations are recognized:
bellard's avatar
bellard committed
304
@table @samp
bellard's avatar
bellard committed
305 306 307 308 309 310 311 312 313 314 315
@item sqcif
128x96
@item qcif
176x144
@item cif
352x288
@item 4cif
704x576
@end table

@item -aspect aspect
diego's avatar
diego committed
316
Set aspect ratio (4:3, 16:9 or 1.3333, 1.7777).
bellard's avatar
bellard committed
317
@item -croptop size
diego's avatar
diego committed
318
Set top crop band size (in pixels).
bellard's avatar
bellard committed
319
@item -cropbottom size
diego's avatar
diego committed
320
Set bottom crop band size (in pixels).
bellard's avatar
bellard committed
321
@item -cropleft size
diego's avatar
diego committed
322
Set left crop band size (in pixels).
bellard's avatar
bellard committed
323
@item -cropright size
diego's avatar
diego committed
324
Set right crop band size (in pixels).
325
@item -padtop size
diego's avatar
diego committed
326
Set top pad band size (in pixels).
327
@item -padbottom size
diego's avatar
diego committed
328
Set bottom pad band size (in pixels).
329
@item -padleft size
diego's avatar
diego committed
330
Set left pad band size (in pixels).
331
@item -padright size
diego's avatar
diego committed
332
Set right pad band size (in pixels).
333
@item -padcolor (hex color)
diego's avatar
diego committed
334 335 336 337
Set color of padded bands. The value for padcolor is expressed
as a six digit hexadecimal number where the first two digits
represent red, the middle two digits green and last two digits
blue (default = 000000 (black)).
338
@item -vn
diego's avatar
diego committed
339
Disable video recording.
340
@item -bt tolerance
341
Set video bitrate tolerance (in bit/s).
bellard's avatar
bellard committed
342
@item -maxrate bitrate
343
Set max video bitrate tolerance (in bit/s).
bellard's avatar
bellard committed
344
@item -minrate bitrate
345
Set min video bitrate tolerance (in bit/s).
bellard's avatar
bellard committed
346
@item -bufsize size
347
Set rate control buffer size (in bits).
348
@item -vcodec codec
diego's avatar
diego committed
349
Force video codec to @var{codec}. Use the @code{copy} special value to
bellard's avatar
bellard committed
350
tell that the raw codec data must be copied as is.
bellard's avatar
bellard committed
351
@item -sameq
diego's avatar
diego committed
352
Use same video quality as source (implies VBR).
353

354
@item -pass n
diego's avatar
diego committed
355 356 357 358
Select the pass number (1 or 2). It is useful to do two pass
encoding. The statistics of the video are recorded in the first
pass and the video is generated at the exact requested bitrate
in the second pass.
359

360
@item -passlogfile file
diego's avatar
diego committed
361
Set two pass logfile name to @var{file}.
362

363 364 365
@item -newvideo
Add a new video stream to the current output stream.

366 367
@end table

bellard's avatar
bellard committed
368
@section Advanced Video Options
369

370
@table @option
371 372
@item -pix_fmt format
Set pixel format.
373
@item -g gop_size
diego's avatar
diego committed
374
Set the group of pictures size.
375
@item -intra
diego's avatar
diego committed
376
Use only intra frames.
377 378
@item -vdt n
Discard threshold.
379
@item -qscale q
diego's avatar
diego committed
380
Use fixed video quantizer scale (VBR).
381
@item -qmin q
diego's avatar
diego committed
382
minimum video quantizer scale (VBR)
383
@item -qmax q
diego's avatar
diego committed
384
maximum video quantizer scale (VBR)
385
@item -qdiff q
diego's avatar
diego committed
386
maximum difference between the quantizer scales (VBR)
387
@item -qblur blur
diego's avatar
diego committed
388
video quantizer scale blur (VBR)
389
@item -qcomp compression
diego's avatar
diego committed
390
video quantizer scale compression (VBR)
bellard's avatar
bellard committed
391

392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
@item -lmin lambda
minimum video lagrange factor (VBR)
@item -lmax lambda
max video lagrange factor (VBR)
@item -mblmin lambda
minimum macroblock quantizer scale (VBR)
@item -mblmax lambda
maximum macroblock quantizer scale (VBR)

These four options (lmin, lmax, mblmin, mblmax) use 'lambda' units,
but you may use the QP2LAMBDA constant to easily convert from 'q' units:
@example
ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
@end example

bellard's avatar
bellard committed
407
@item -rc_init_cplx complexity
diego's avatar
diego committed
408
initial complexity for single pass encoding
bellard's avatar
bellard committed
409
@item -b_qfactor factor
diego's avatar
diego committed
410
qp factor between P- and B-frames
bellard's avatar
bellard committed
411
@item -i_qfactor factor
diego's avatar
diego committed
412
qp factor between P- and I-frames
bellard's avatar
bellard committed
413
@item -b_qoffset offset
diego's avatar
diego committed
414
qp offset between P- and B-frames
bellard's avatar
bellard committed
415
@item -i_qoffset offset
diego's avatar
diego committed
416
qp offset between P- and I-frames
bellard's avatar
bellard committed
417
@item -rc_eq equation
diego's avatar
diego committed
418 419
Set rate control equation (@pxref{FFmpeg formula
evaluator}) (default = @code{tex^qComp}).
bellard's avatar
bellard committed
420 421
@item -rc_override override
rate control override for specific intervals
bellard's avatar
bellard committed
422
@item -me method
diego's avatar
diego committed
423 424
Set motion estimation method to @var{method}.
Available methods are (from lowest to best quality):
bellard's avatar
bellard committed
425 426
@table @samp
@item zero
bellard's avatar
bellard committed
427
Try just the (0, 0) vector.
bellard's avatar
bellard committed
428 429 430 431 432 433 434 435 436 437
@item phods
@item log
@item x1
@item epzs
(default method)
@item full
exhaustive search (slow and marginally better than epzs)
@end table

@item -dct_algo algo
diego's avatar
diego committed
438
Set DCT algorithm to @var{algo}. Available values are:
bellard's avatar
bellard committed
439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454
@table @samp
@item 0
FF_DCT_AUTO (default)
@item 1
FF_DCT_FASTINT
@item 2
FF_DCT_INT
@item 3
FF_DCT_MMX
@item 4
FF_DCT_MLIB
@item 5
FF_DCT_ALTIVEC
@end table

@item -idct_algo algo
diego's avatar
diego committed
455
Set IDCT algorithm to @var{algo}. Available values are:
bellard's avatar
bellard committed
456 457 458 459
@table @samp
@item 0
FF_IDCT_AUTO (default)
@item 1
460
FF_IDCT_INT
bellard's avatar
bellard committed
461
@item 2
462
FF_IDCT_SIMPLE
bellard's avatar
bellard committed
463
@item 3
464
FF_IDCT_SIMPLEMMX
bellard's avatar
bellard committed
465
@item 4
466
FF_IDCT_LIBMPEG2MMX
bellard's avatar
bellard committed
467
@item 5
468
FF_IDCT_PS2
bellard's avatar
bellard committed
469
@item 6
470
FF_IDCT_MLIB
bellard's avatar
bellard committed
471
@item 7
472
FF_IDCT_ARM
bellard's avatar
bellard committed
473
@item 8
474
FF_IDCT_ALTIVEC
bellard's avatar
bellard committed
475
@item 9
476
FF_IDCT_SH4
bellard's avatar
bellard committed
477
@item 10
478
FF_IDCT_SIMPLEARM
bellard's avatar
bellard committed
479 480 481
@end table

@item -er n
diego's avatar
diego committed
482
Set error resilience to @var{n}.
bellard's avatar
bellard committed
483
@table @samp
484
@item 1
diego's avatar
diego committed
485
FF_ER_CAREFUL (default)
bellard's avatar
bellard committed
486
@item 2
bellard's avatar
bellard committed
487
FF_ER_COMPLIANT
bellard's avatar
bellard committed
488 489 490 491 492 493
@item 3
FF_ER_AGGRESSIVE
@item 4
FF_ER_VERY_AGGRESSIVE
@end table

bellard's avatar
bellard committed
494
@item -ec bit_mask
diego's avatar
diego committed
495
Set error concealment to @var{bit_mask}. @var{bit_mask} is a bit mask of
bellard's avatar
bellard committed
496
the following values:
bellard's avatar
bellard committed
497 498
@table @samp
@item 1
diego's avatar
diego committed
499
FF_EC_GUESS_MVS (default = enabled)
bellard's avatar
bellard committed
500
@item 2
diego's avatar
diego committed
501
FF_EC_DEBLOCK (default = enabled)
bellard's avatar
bellard committed
502 503 504
@end table

@item -bf frames
diego's avatar
diego committed
505
Use 'frames' B-frames (supported for MPEG-1, MPEG-2 and MPEG-4).
bellard's avatar
bellard committed
506 507 508 509
@item -mbd mode
macroblock decision
@table @samp
@item 0
diego's avatar
diego committed
510
FF_MB_DECISION_SIMPLE: Use mb_cmp (cannot change it yet in FFmpeg).
bellard's avatar
bellard committed
511
@item 1
diego's avatar
diego committed
512
FF_MB_DECISION_BITS: Choose the one which needs the fewest bits.
bellard's avatar
bellard committed
513
@item 2
diego's avatar
diego committed
514
FF_MB_DECISION_RD: rate distortion
bellard's avatar
bellard committed
515 516 517
@end table

@item -4mv
diego's avatar
diego committed
518
Use four motion vector by macroblock (MPEG-4 only).
bellard's avatar
bellard committed
519
@item -part
diego's avatar
diego committed
520
Use data partitioning (MPEG-4 only).
bellard's avatar
bellard committed
521
@item -bug param
diego's avatar
diego committed
522
Work around encoder bugs that are not auto-detected.
bellard's avatar
bellard committed
523
@item -strict strictness
diego's avatar
diego committed
524
How strictly to follow the standards.
bellard's avatar
bellard committed
525
@item -aic
diego's avatar
diego committed
526
Enable Advanced intra coding (h263+).
bellard's avatar
bellard committed
527
@item -umv
diego's avatar
diego committed
528
Enable Unlimited Motion Vector (h263+)
bellard's avatar
bellard committed
529 530

@item -deinterlace
diego's avatar
diego committed
531
Deinterlace pictures.
532
@item -ilme
diego's avatar
diego committed
533 534 535 536 537
Force interlacing support in encoder (MPEG-2 and MPEG-4 only).
Use this option if your input file is interlaced and you want
to keep the interlaced format for minimum losses.
The alternative is to deinterlace the input stream with
@option{-deinterlace}, but deinterlacing introduces losses.
bellard's avatar
bellard committed
538
@item -psnr
diego's avatar
diego committed
539
Calculate PSNR of compressed frames.
bellard's avatar
bellard committed
540
@item -vstats
diego's avatar
diego committed
541
Dump video coding statistics to @file{vstats_HHMMSS.log}.
bellard's avatar
bellard committed
542
@item -vhook module
diego's avatar
diego committed
543
Insert video processing @var{module}. @var{module} contains the module
bellard's avatar
bellard committed
544
name and its parameters separated by spaces.
545 546 547 548 549 550 551 552 553 554
@item -top n
top=1/bottom=0/auto=-1 field first
@item -dc precision
Intra_dc_precision.
@item -vtag fourcc/tag
Force video tag/fourcc.
@item -qphist
Show QP histogram.
@item -vbsf bitstream filter
Bitstream filters available are "dump_extra", "remove_extra", "noise".
bellard's avatar
bellard committed
555 556 557 558 559
@end table

@section Audio Options

@table @option
560 561
@item -aframes number
Set the number of audio frames to record.
562
@item -ar freq
diego's avatar
diego committed
563
Set the audio sampling frequency (default = 44100 Hz).
564
@item -ab bitrate
diego's avatar
diego committed
565
Set the audio bitrate in kbit/s (default = 64).
bellard's avatar
bellard committed
566
@item -ac channels
diego's avatar
diego committed
567
Set the number of audio channels (default = 1).
bellard's avatar
bellard committed
568
@item -an
diego's avatar
diego committed
569
Disable audio recording.
bellard's avatar
bellard committed
570
@item -acodec codec
diego's avatar
diego committed
571 572
Force audio codec to @var{codec}. Use the @code{copy} special value to
specify that the raw codec data must be copied as is.
573
@item -newaudio
diego's avatar
diego committed
574 575
Add a new audio track to the output file. If you want to specify parameters,
do so before @code{-newaudio} (@code{-acodec}, @code{-ab}, etc..).
576

diego's avatar
diego committed
577 578
Mapping will be done automatically, if the number of output streams is equal to
the number of input streams, else it will pick the first one that matches. You
579 580 581 582 583 584
can override the mapping using @code{-map} as usual.

Example:
@example
ffmpeg -i file.mpg -vcodec copy -acodec ac3 -ab 384 test.mpg -acodec mp2 -ab 192 -newaudio
@end example
585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606
@item -alang code
Set the ISO 639 language code (3 letters) of the current audio stream.
@end table

@section Advanced Audio options:

@table @option
@item -atag fourcc/tag
Force audio tag/fourcc.
@item -absf bitstream filter
Bitstream filters available are "dump_extra", "remove_extra", "noise", "mp3comp", "mp3decomp".
@end table

@section Subtitle options:

@table @option
@item -scodec codec
Force subtitle codec ('copy' to copy stream).
@item -newsubtitle
Add a new subtitle stream to the current output stream.
@item -slang code
Set the ISO 639 language code (3 letters) of the current subtitle stream.
bellard's avatar
bellard committed
607 608 609 610 611 612
@end table

@section Audio/Video grab options

@table @option
@item -vd device
diego's avatar
diego committed
613
sEt video grab device (e.g. @file{/dev/video0}).
bellard's avatar
bellard committed
614
@item -vc channel
diego's avatar
diego committed
615
Set video grab channel (DV1394 only).
bellard's avatar
bellard committed
616
@item -tvstd standard
diego's avatar
diego committed
617
Set television standard (NTSC, PAL (SECAM)).
bellard's avatar
bellard committed
618
@item -dv1394
diego's avatar
diego committed
619
Set DV1394 grab.
bellard's avatar
bellard committed
620
@item -ad device
diego's avatar
diego committed
621
Set audio device (e.g. @file{/dev/dsp}).
622 623 624 625
@item -grab format
Request grabbing using.
@item -gd device
Set grab device.
bellard's avatar
bellard committed
626 627 628 629 630
@end table

@section Advanced options

@table @option
banan's avatar
banan committed
631 632 633 634
@item -map input stream id[:input stream id]
Set stream mapping from input streams to output streams.
Just enumerate the input streams in the order you want them in the output.
[input stream id] sets the (input) stream to sync against.
635 636
@item -map_meta_data outfile:infile
Set meta data information of outfile from infile.
bellard's avatar
bellard committed
637
@item -debug
diego's avatar
diego committed
638
Print specific debug info.
639
@item -benchmark
diego's avatar
diego committed
640
Add timings for benchmarking.
641
@item -dump
diego's avatar
diego committed
642
Dump each input packet.
643 644
@item -hex
When dumping packets, also dump the payload.
bellard's avatar
bellard committed
645
@item -bitexact
diego's avatar
diego committed
646
Only use bit exact algorithms (for codec testing).
bellard's avatar
bellard committed
647
@item -ps size
diego's avatar
diego committed
648
Set packet size in bits.
bellard's avatar
bellard committed
649
@item -re
diego's avatar
diego committed
650
Read input at native frame rate. Mainly used to simulate a grab device.
651
@item -loop_input
diego's avatar
diego committed
652 653
Loop over the input stream. Currently it works only for image
streams. This option is used for automatic FFserver testing.
654
@item -loop_output number_of_times
diego's avatar
diego committed
655
Repeatedly loop output for formats that support looping such as animated GIF
diego's avatar
diego committed
656
(0 will loop the output infinitely).
657 658
@item -threads count
Thread count.
659
@item -vsync parameter
diego's avatar
diego committed
660 661 662
Video sync method. Video will be stretched/squeezed to match the timestamps,
it is done by duplicating and dropping frames. With -map you can select from
which stream the timestamps should be taken. You can leave either video or
663 664
audio unchanged and sync the remaining stream(s) to the unchanged one.
@item -async samples_per_second
diego's avatar
diego committed
665
Audio sync method. "Stretches/squeezes" the audio stream to match the timestamps,
666 667 668
the parameter is the maximum samples per second by which the audio is changed.
-async 1 is a special case where only the start of the audio stream is corrected
without any later correction.
669
@end table
bellard's avatar
bellard committed
670 671 672 673 674

@node FFmpeg formula evaluator
@section FFmpeg formula evaluator

When evaluating a rate control string, FFmpeg uses an internal formula
675
evaluator.
bellard's avatar
bellard committed
676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728

The following binary operators are available: @code{+}, @code{-},
@code{*}, @code{/}, @code{^}.

The following unary operators are available: @code{+}, @code{-},
@code{(...)}.

The following functions are available:
@table @var
@item sinh(x)
@item cosh(x)
@item tanh(x)
@item sin(x)
@item cos(x)
@item tan(x)
@item exp(x)
@item log(x)
@item squish(x)
@item gauss(x)
@item abs(x)
@item max(x, y)
@item min(x, y)
@item gt(x, y)
@item lt(x, y)
@item eq(x, y)
@item bits2qp(bits)
@item qp2bits(qp)
@end table

The following constants are available:
@table @var
@item PI
@item E
@item iTex
@item pTex
@item tex
@item mv
@item fCode
@item iCount
@item mcVar
@item var
@item isI
@item isP
@item isB
@item avgQP
@item qComp
@item avgIITex
@item avgPITex
@item avgPPTex
@item avgBPTex
@item avgTex
@end table

729 730 731 732 733 734 735 736
@c man end

@ignore

@setfilename ffmpeg
@settitle FFmpeg video converter

@c man begin SEEALSO
diego's avatar
diego committed
737
ffserver(1), ffplay(1) and the HTML documentation of @file{ffmpeg}.
738 739 740 741 742 743 744
@c man end

@c man begin AUTHOR
Fabrice Bellard
@c man end

@end ignore
745 746 747

@section Protocols

diego's avatar
diego committed
748 749
The filename can be @file{-} to read from standard input or to write
to standard output.
750

diego's avatar
diego committed
751
FFmpeg also handles many protocols specified with an URL syntax.
752

diego's avatar
diego committed
753
Use 'ffmpeg -formats' to see a list of the supported protocols.
754

755
The protocol @code{http:} is currently used only to communicate with
diego's avatar
diego committed
756
FFserver (see the FFserver documentation). When FFmpeg will be a
757
video player it will also be used for streaming :-)
758 759 760 761

@chapter Tips

@itemize
diego's avatar
diego committed
762 763
@item For streaming at very low bitrate application, use a low frame rate
and a small GOP size. This is especially true for RealVideo where
764 765
the Linux player does not seem to be very fast, so it can miss
frames. An example is:
766 767

@example
768
ffmpeg -g 3 -r 3 -t 10 -b 50k -s qcif -f rv10 /tmp/b.rm
769 770 771
@end example

@item  The parameter 'q' which is displayed while encoding is the current
diego's avatar
diego committed
772 773
quantizer. The value 1 indicates that a very good quality could
be achieved. The value 31 indicates the worst quality. If q=31 appears
774
too often, it means that the encoder cannot compress enough to meet
diego's avatar
diego committed
775
your bitrate. You must either increase the bitrate, decrease the
776
frame rate or decrease the frame size.
777 778

@item If your computer is not fast enough, you can speed up the
779 780
compression at the expense of the compression ratio. You can use
'-me zero' to speed up motion estimation, and '-intra' to disable
diego's avatar
diego committed
781
motion estimation completely (you have only I-frames, which means it
782
is about as good as JPEG compression).
783

diego's avatar
diego committed
784
@item To have very low audio bitrates, reduce the sampling frequency
diego's avatar
diego committed
785
(down to 22050 kHz for MPEG audio, 22050 or 11025 for AC3).
786 787

@item To have a constant quality (but a variable bitrate), use the option
788 789
'-qscale n' when 'n' is between 1 (excellent quality) and 31 (worst
quality).
790 791

@item When converting video files, you can use the '-sameq' option which
diego's avatar
diego committed
792 793
uses the same quality factor in the encoder as in the decoder.
It allows almost lossless encoding.
794 795 796

@end itemize

797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830

@chapter external libraries

FFmpeg can be hooked up with a number of external libraries to add support
for more formats.

@section AMR

AMR comes in two different flavors, WB and NB. FFmpeg can make use of the
AMR WB (floating-point mode) and the AMR NB (both floating-point and
fixed-point mode) reference decoders and encoders.

@itemize

@item For AMR WB floating-point download TS26.204 V5.1.0 from
@url{http://www.3gpp.org/ftp/Specs/archive/26_series/26.204/26204-510.zip}
and extract the source to @file{libavcodec/amrwb_float/}.

@item For AMR NB floating-point download TS26.104 REL-5 V5.1.0 from
@url{http://www.3gpp.org/ftp/Specs/archive/26_series/26.104/26104-510.zip}
and extract the source to @file{libavcodec/amr_float/}.
If you try this on Alpha, you may need to change @code{Word32} to
@code{int} in @file{amr/typedef.h}.

@item For AMR NB fixed-point download TS26.073 REL-5 V5.1.0 from
@url{http://www.3gpp.org/ftp/Specs/archive/26_series/26.073/26073-510.zip}
and extract the source to @file{libavcodec/amr}.
You must also add @code{-DMMS_IO} and remove @code{-pedantic-errors}
to/from @code{CFLAGS} in @file{libavcodec/amr/makefile}, i.e.
``@code{CFLAGS = -Wall -I. \$(CFLAGS_\$(MODE)) -D\$(VAD) -DMMS_IO}''.

@end itemize


831 832 833 834 835 836
@chapter Supported File Formats and Codecs

You can use the @code{-formats} option to have an exhaustive list.

@section File Formats

837
FFmpeg supports the following file formats through the @code{libavformat}
bellard's avatar
bellard committed
838
library:
839

840
@multitable @columnfractions .4 .1 .1 .4
841 842
@item Supported File Format @tab Encoding @tab Decoding @tab Comments
@item MPEG audio @tab X @tab X
diego's avatar
diego committed
843
@item MPEG-1 systems @tab X  @tab  X
844
@tab muxed audio and video
diego's avatar
diego committed
845
@item MPEG-2 PS @tab X  @tab  X
846
@tab also known as @code{VOB} file
diego's avatar
diego committed
847
@item MPEG-2 TS @tab    @tab  X
848
@tab also known as DVB Transport Stream
849 850 851
@item ASF@tab X @tab X
@item AVI@tab X @tab X
@item WAV@tab X @tab X
852
@item Macromedia Flash@tab X @tab X
diego's avatar
diego committed
853
@tab Only embedded audio is decoded.
bellard's avatar
bellard committed
854 855
@item FLV              @tab  X @tab X
@tab Macromedia Flash video files
856 857 858 859 860 861 862 863
@item Real Audio and Video @tab X @tab X
@item Raw AC3 @tab X  @tab  X
@item Raw MJPEG @tab X  @tab  X
@item Raw MPEG video @tab X  @tab  X
@item Raw PCM8/16 bits, mulaw/Alaw@tab X  @tab  X
@item Raw CRI ADX audio @tab X  @tab  X
@item Raw Shorten audio @tab    @tab  X
@item SUN AU format @tab X  @tab  X
al3x's avatar
al3x committed
864
@item NUT @tab X @tab X @tab NUT Open Container Format
865
@item QuickTime        @tab X @tab  X
diego's avatar
diego committed
866 867
@item MPEG-4           @tab X @tab  X
@tab MPEG-4 is a variant of QuickTime.
868
@item Raw MPEG4 video  @tab  X @tab  X
romansh's avatar
 
romansh committed
869
@item DV               @tab  X @tab  X
tmmm's avatar
tmmm committed
870
@item 4xm              @tab    @tab X
diego's avatar
diego committed
871
@tab 4X Technologies format, used in some games.
tmmm's avatar
tmmm committed
872 873
@item Playstation STR  @tab    @tab X
@item Id RoQ           @tab    @tab X
diego's avatar
diego committed
874
@tab Used in Quake III, Jedi Knight 2, other computer games.
tmmm's avatar
tmmm committed
875
@item Interplay MVE    @tab    @tab X
diego's avatar
diego committed
876
@tab Format used in various Interplay computer games.
tmmm's avatar
tmmm committed
877
@item WC3 Movie        @tab    @tab X
diego's avatar
diego committed
878
@tab Multimedia format used in Origin's Wing Commander III computer game.
879
@item Sega FILM/CPK    @tab    @tab X
diego's avatar
diego committed
880
@tab Used in many Sega Saturn console games.
881
@item Westwood Studios VQA/AUD  @tab    @tab X
diego's avatar
diego committed
882
@tab Multimedia formats used in Westwood Studios games.
tmmm's avatar
tmmm committed
883
@item Id Cinematic (.cin) @tab    @tab X
diego's avatar
diego committed
884
@tab Used in Quake II.
melanson's avatar
melanson committed
885 886
@item FLIC format      @tab    @tab X
@tab .fli/.flc files
melanson's avatar
melanson committed
887
@item Sierra VMD       @tab    @tab X
diego's avatar
diego committed
888
@tab Used in Sierra CD-ROM games.
889
@item Sierra Online    @tab    @tab X
diego's avatar
diego committed
890
@tab .sol files used in Sierra Online games.
melanson's avatar
melanson committed
891
@item Matroska         @tab    @tab X
892
@item Electronic Arts Multimedia    @tab    @tab X
diego's avatar
diego committed
893
@tab Used in various EA games; files have extensions like WVE and UV2.
melanson's avatar
melanson committed
894
@item Nullsoft Video (NSV) format @tab    @tab X
895
@item ADTS AAC audio @tab X @tab X
aurel's avatar
aurel committed
896
@item Creative VOC @tab X @tab X @tab Created for the Sound Blaster Pro.
897 898
@item American Laser Games MM  @tab    @tab X
@tab Multimedia format used in games like Mad Dog McCree
899 900
@item AVS @tab    @tab X
@tab Multimedia format used by the Creature Shock game.
kostya's avatar
kostya committed
901 902
@item Smacker @tab    @tab X
@tab Multimedia format used by many games.
903 904
@item GXF @tab  X @tab X
@tab General eXchange Format SMPTE 360M, used by Thomson Grass Valley playout servers.
905 906
@item CIN @tab    @tab X
@tab Multimedia format used by Delphine Software games.
bcoudurier's avatar
bcoudurier committed
907 908
@item MXF @tab    @tab X
@tab Material eXchange Format SMPTE 377M, used by D-Cinema, broadcast industry.
909 910
@item SEQ @tab    @tab X
@tab Tiertex .seq files used in the DOS CDROM version of the game Flashback.
melanson's avatar
melanson committed
911
@end multitable
912

diego's avatar
diego committed
913
@code{X} means that encoding (resp. decoding) is supported.
914

bellard's avatar
bellard committed
915 916 917 918 919
@section Image Formats

FFmpeg can read and write images for each frame of a video sequence. The
following image formats are supported:

920
@multitable @columnfractions .4 .1 .1 .4
bellard's avatar
bellard committed
921
@item Supported Image Format @tab Encoding @tab Decoding @tab Comments
922
@item PGM, PPM     @tab X @tab X
diego's avatar
diego committed
923
@item PAM          @tab X @tab X @tab PAM is a PNM extension with alpha support.
bellard's avatar
bellard committed
924
@item PGMYUV       @tab X @tab X @tab PGM with U and V components in YUV 4:2:0
diego's avatar
diego committed
925 926 927 928
@item JPEG         @tab X @tab X @tab Progressive JPEG is not supported.
@item .Y.U.V       @tab X @tab X @tab one raw file per component
@item animated GIF @tab X @tab X @tab Only uncompressed GIFs are generated.
@item PNG          @tab X @tab X @tab 2 bit and 4 bit/pixel not supported yet.
kostya's avatar
kostya committed
929
@item Targa        @tab   @tab X @tab Targa (.TGA) image format.
kostya's avatar
kostya committed
930
@item TIFF         @tab   @tab X @tab Only 24 bit/pixel images are supported.
931
@item SGI          @tab X @tab X @tab SGI RGB image format
bellard's avatar
bellard committed
932 933
@end multitable

diego's avatar
diego committed
934
@code{X} means that encoding (resp. decoding) is supported.
bellard's avatar
bellard committed
935

936 937
@section Video Codecs

938
@multitable @columnfractions .4 .1 .1 .4
939
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
diego's avatar
diego committed
940 941
@item MPEG-1 video           @tab  X  @tab  X
@item MPEG-2 video           @tab  X  @tab  X
michael's avatar
michael committed
942
@item MPEG-4                 @tab  X  @tab  X
943 944
@item MSMPEG4 V1             @tab  X  @tab  X
@item MSMPEG4 V2             @tab  X  @tab  X
michael's avatar
michael committed
945
@item MSMPEG4 V3             @tab  X  @tab  X
946
@item WMV7                   @tab  X  @tab  X
diego's avatar
diego committed
947
@item WMV8                   @tab  X  @tab  X @tab not completely working
diego's avatar
diego committed
948 949
@item WMV9                   @tab     @tab  X @tab not completely working
@item VC1                    @tab     @tab  X
melanson's avatar
melanson committed
950
@item H.261                  @tab  X  @tab  X
diego's avatar
diego committed
951
@item H.263(+)               @tab  X  @tab  X @tab also known as RealVideo 1.0
melanson's avatar
melanson committed
952
@item H.264                  @tab     @tab  X
953 954
@item RealVideo 1.0          @tab  X  @tab  X
@item RealVideo 2.0          @tab  X  @tab  X
955
@item MJPEG                  @tab  X  @tab  X
diego's avatar
diego committed
956
@item lossless MJPEG         @tab  X  @tab  X
957
@item JPEG-LS                @tab  X  @tab  X @tab fourcc: MJLS, lossless and near-lossless is supported
alex's avatar
alex committed
958 959
@item Apple MJPEG-B          @tab     @tab  X
@item Sunplus MJPEG          @tab     @tab  X @tab fourcc: SP5X
960
@item DV                     @tab  X  @tab  X
diego's avatar
diego committed
961 962 963
@item HuffYUV                @tab  X  @tab  X
@item FFmpeg Video 1         @tab  X  @tab  X @tab experimental lossless codec (fourcc: FFV1)
@item FFmpeg Snow            @tab  X  @tab  X @tab experimental wavelet codec (fourcc: SNOW)
tmmm's avatar
tmmm committed
964
@item Asus v1                @tab  X  @tab  X @tab fourcc: ASV1
tmmm's avatar
tmmm committed
965
@item Asus v2                @tab  X  @tab  X @tab fourcc: ASV2
tmmm's avatar
tmmm committed
966
@item Creative YUV           @tab     @tab  X @tab fourcc: CYUV
melanson's avatar
melanson committed
967
@item Sorenson Video 1       @tab  X  @tab  X @tab fourcc: SVQ1
tmmm's avatar
tmmm committed
968 969
@item Sorenson Video 3       @tab     @tab  X @tab fourcc: SVQ3
@item On2 VP3                @tab     @tab  X @tab still experimental
aurel's avatar
aurel committed
970
@item On2 VP5                @tab     @tab  X @tab fourcc: VP50
aurel's avatar
aurel committed
971
@item On2 VP6                @tab     @tab  X @tab fourcc: VP60,VP61,VP62
diego's avatar
diego committed
972
@item Theora                 @tab  X  @tab  X @tab still experimental
973
@item Intel Indeo 3          @tab     @tab  X
alex's avatar
alex committed
974
@item FLV                    @tab  X  @tab  X @tab Sorenson H.263 used in Flash
banan's avatar
banan committed
975
@item Flash Screen Video     @tab  X  @tab  X @tab fourcc: FSV1
tmmm's avatar
tmmm committed
976
@item ATI VCR1               @tab     @tab  X @tab fourcc: VCR1
al3x's avatar
al3x committed
977
@item ATI VCR2               @tab     @tab  X @tab fourcc: VCR2
tmmm's avatar
tmmm committed
978
@item Cirrus Logic AccuPak   @tab     @tab  X @tab fourcc: CLJR
diego's avatar
diego committed
979
@item 4X Video               @tab     @tab  X @tab Used in certain computer games.
980
@item Sony Playstation MDEC  @tab     @tab  X
diego's avatar
diego committed
981 982 983
@item Id RoQ                 @tab     @tab  X @tab Used in Quake III, Jedi Knight 2, other computer games.
@item Xan/WC3                @tab     @tab  X @tab Used in Wing Commander III .MVE files.
@item Interplay Video        @tab     @tab  X @tab Used in Interplay .MVE files.
984
@item Apple Animation        @tab     @tab  X @tab fourcc: 'rle '
melanson's avatar
melanson committed
985
@item Apple Graphics         @tab     @tab  X @tab fourcc: 'smc '
986
@item Apple Video            @tab     @tab  X @tab fourcc: rpza
987
@item Apple QuickDraw        @tab     @tab  X @tab fourcc: qdrw
988 989 990
@item Cinepak                @tab     @tab  X
@item Microsoft RLE          @tab     @tab  X
@item Microsoft Video-1      @tab     @tab  X
tmmm's avatar
tmmm committed
991
@item Westwood VQA           @tab     @tab  X
diego's avatar
diego committed
992
@item Id Cinematic Video     @tab     @tab  X @tab Used in Quake II.
rtognimp's avatar
rtognimp committed
993
@item Planar RGB             @tab     @tab  X @tab fourcc: 8BPS
melanson's avatar
melanson committed
994
@item FLIC video             @tab     @tab  X
995
@item Duck TrueMotion v1     @tab     @tab  X @tab fourcc: DUCK
melanson's avatar
melanson committed
996
@item Duck TrueMotion v2     @tab     @tab  X @tab fourcc: TM20
diego's avatar
diego committed
997
@item VMD Video              @tab     @tab  X @tab Used in Sierra VMD files.
rtognimp's avatar
rtognimp committed
998 999
@item MSZH                   @tab     @tab  X @tab Part of LCL
@item ZLIB                   @tab  X  @tab  X @tab Part of LCL, encoder experimental
1000
@item TechSmith Camtasia     @tab     @tab  X @tab fourcc: TSCC
1001
@item IBM Ultimotion         @tab     @tab  X @tab fourcc: ULTI
1002
@item Miro VideoXL           @tab     @tab  X @tab fourcc: VIXL
1003
@item QPEG                   @tab     @tab  X @tab fourccs: QPEG, Q1.0, Q1.1
1004 1005
@item LOCO                   @tab     @tab  X @tab
@item Winnov WNV1            @tab     @tab  X @tab
1006
@item Autodesk Animator Studio Codec  @tab     @tab  X @tab fourcc: AASC
1007
@item Fraps FPS1             @tab     @tab  X @tab
diego's avatar
diego committed
1008
@item CamStudio              @tab     @tab  X @tab fourcc: CSCD
1009
@item American Laser Games Video  @tab    @tab X @tab Used in games like Mad Dog McCree
kostya's avatar
kostya committed
1010
@item ZMBV                   @tab   X @tab  X @tab Encoder works only on PAL8
1011
@item AVS Video              @tab     @tab  X @tab Video encoding used by the Creature Shock game.
kostya's avatar
kostya committed
1012
@item Smacker Video          @tab     @tab  X @tab Video encoding used in Smacker.
1013
@item RTjpeg                 @tab     @tab  X @tab Video encoding used in NuppelVideo files.
1014
@item KMVC                   @tab     @tab  X @tab Codec used in Worms games.
kostya's avatar
kostya committed
1015
@item VMware Video           @tab     @tab  X @tab Codec used in videos captured by VMware.
1016
@item Cin Video              @tab     @tab  X @tab Codec used in Delphine Software games.
1017
@item Tiertex Seq Video      @tab     @tab  X @tab Codec used in DOS CDROM FlashBack game.
1018 1019
@end multitable

diego's avatar
diego committed
1020
@code{X} means that encoding (resp. decoding) is supported.
1021 1022 1023 1024 1025

@section Audio Codecs

@multitable @columnfractions .4 .1 .1 .1 .7
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
1026
@item MPEG audio layer 2     @tab  IX  @tab  IX
1027
@item MPEG audio layer 1/3   @tab IX   @tab  IX
diego's avatar
diego committed
1028
@tab MP3 encoding is supported through the external library LAME.
1029
@item AC3                    @tab  IX  @tab  IX
diego's avatar
diego committed
1030
@tab liba52 is used internally for decoding.
philipjsg's avatar
philipjsg committed
1031
@item Vorbis                 @tab  X   @tab  X
diego's avatar
diego committed
1032
@item WMA V1/V2              @tab X    @tab X
1033
@item AAC                    @tab X    @tab X
diego's avatar
diego committed
1034
@tab Supported through the external library libfaac/libfaad.
michael's avatar
michael committed
1035
@item Microsoft ADPCM        @tab X    @tab X
tmmm's avatar
tmmm committed
1036 1037 1038
@item MS IMA ADPCM           @tab X    @tab X
@item QT IMA ADPCM           @tab      @tab X
@item 4X IMA ADPCM           @tab      @tab X
romansh's avatar
 
romansh committed
1039
@item G.726  ADPCM           @tab X    @tab X
tmmm's avatar
tmmm committed
1040
@item Duck DK3 IMA ADPCM     @tab      @tab X
diego's avatar
diego committed
1041
@tab Used in some Sega Saturn console games.
tmmm's avatar
tmmm committed
1042
@item Duck DK4 IMA ADPCM     @tab      @tab X
diego's avatar
diego committed
1043
@tab Used in some Sega Saturn console games.
1044
@item Westwood Studios IMA ADPCM @tab      @tab X
diego's avatar
diego committed
1045
@tab Used in Westwood Studios games like Command and Conquer.
1046
@item SMJPEG IMA ADPCM       @tab      @tab X
diego's avatar
diego committed
1047
@tab Used in certain Loki game ports.
melanson's avatar
melanson committed
1048 1049
@item CD-ROM XA ADPCM        @tab      @tab X
@item CRI ADX ADPCM          @tab X    @tab X
diego's avatar
diego committed
1050
@tab Used in Sega Dreamcast games.
1051
@item Electronic Arts ADPCM  @tab      @tab X
diego's avatar
diego committed
1052
@tab Used in various EA titles.
1053
@item Creative ADPCM         @tab      @tab X
1054
@tab 16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
bellard's avatar
bellard committed
1055 1056 1057 1058
@item RA144                  @tab      @tab X
@tab Real 14400 bit/s codec
@item RA288                  @tab      @tab X
@tab Real 28800 bit/s codec
1059
@item RADnet                 @tab X    @tab IX
diego's avatar
diego committed
1060
@tab Real low bitrate AC3 codec, liba52 is used for decoding.
bellard's avatar
bellard committed
1061
@item AMR-NB                 @tab X    @tab X
diego's avatar
diego committed
1062
@tab Supported through an external library.
1063
@item AMR-WB                 @tab X    @tab X
diego's avatar
diego committed
1064
@tab Supported through an external library.
bellard's avatar
bellard committed
1065
@item DV audio               @tab      @tab X
tmmm's avatar
tmmm committed
1066
@item Id RoQ DPCM            @tab      @tab X
diego's avatar
diego committed
1067
@tab Used in Quake III, Jedi Knight 2, other computer games.
tmmm's avatar
tmmm committed
1068
@item Interplay MVE DPCM     @tab      @tab X
diego's avatar
diego committed
1069
@tab Used in various Interplay computer games.
tmmm's avatar
tmmm committed
1070
@item Xan DPCM               @tab      @tab X
diego's avatar
diego committed
1071
@tab Used in Origin's Wing Commander IV AVI files.
1072
@item Sierra Online DPCM     @tab      @tab X
diego's avatar
diego committed
1073
@tab Used in Sierra Online game audio files.
alex's avatar
alex committed
1074 1075
@item Apple MACE 3           @tab      @tab X
@item Apple MACE 6           @tab      @tab X
melanson's avatar
melanson committed
1076 1077
@item FLAC lossless audio    @tab      @tab X
@item Shorten lossless audio @tab      @tab X
1078 1079
@item Apple lossless audio   @tab      @tab X
@tab QuickTime fourcc 'alac'
alex's avatar
alex committed
1080
@item FFmpeg Sonic           @tab X    @tab X
diego's avatar
diego committed
1081
@tab experimental lossy/lossless codec
rtognimp's avatar
rtognimp committed
1082 1083
@item Qdesign QDM2           @tab      @tab X
@tab there are still some distortions
rtognimp's avatar
rtognimp committed
1084 1085
@item Real COOK              @tab      @tab X
@tab All versions except 5.1 are supported
1086
@item DSP Group TrueSpeech   @tab      @tab X
alex's avatar
alex committed
1087
@item True Audio (TTA)       @tab      @tab X
kostya's avatar
kostya committed
1088
@item Smacker Audio          @tab      @tab X
kostya's avatar
kostya committed
1089
@item WavPack Audio          @tab      @tab X
1090 1091
@item Cin Audio              @tab      @tab X
@tab Codec used in Delphine Software games.
kostya's avatar
kostya committed
1092
@item Intel Music Coder      @tab      @tab X
kostya's avatar
kostya committed
1093 1094
@item Musepack               @tab      @tab X
@tab Only SV7 is supported
1095 1096
@end multitable

diego's avatar
diego committed
1097
@code{X} means that encoding (resp. decoding) is supported.
1098

diego's avatar
diego committed
1099 1100
@code{I} means that an integer-only version is available, too (ensures high
performance on systems without hardware floating point support).
1101

bellard's avatar
bellard committed
1102 1103 1104 1105
@chapter Platform Specific information

@section BSD

diego's avatar
diego committed
1106 1107 1108
BSD make will not build FFmpeg, you need to install and use GNU Make
(@file{gmake}).

bellard's avatar
bellard committed
1109 1110
@section Windows

1111 1112 1113 1114
To get help and instructions for using FFmpeg under Windows, check out
the FFmpeg Windows Help Forum at
@url{http://arrozcru.no-ip.org/ffmpeg/}.

1115 1116 1117 1118 1119 1120 1121
@subsection Native Windows compilation

@itemize
@item Install the current versions of MSYS and MinGW from
@url{http://www.mingw.org/}. You can find detailed installation
instructions in the download section and the FAQ.

diego's avatar
diego committed
1122
@item If you want to test the FFplay, also download
bellard's avatar
bellard committed
1123 1124
the MinGW development library of SDL 1.2.x
(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
diego's avatar
diego committed
1125
@url{http://www.libsdl.org}. Unpack it in a temporary directory, and
bellard's avatar
bellard committed
1126
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
bellard's avatar
bellard committed
1127 1128
directory. Edit the @file{sdl-config} script so that it gives the
correct SDL directory when invoked.
bellard's avatar
bellard committed
1129

1130
@item Extract the current version of FFmpeg.
1131

1132 1133
@item Start the MSYS shell (file @file{msys.bat}).

diego's avatar
diego committed
1134 1135
@item Change to the FFmpeg directory and follow
 the instructions of how to compile FFmpeg (file
bellard's avatar
bellard committed
1136 1137 1138 1139
@file{INSTALL}). Usually, launching @file{./configure} and @file{make}
suffices. If you have problems using SDL, verify that
@file{sdl-config} can be launched from the MSYS command line.

diego's avatar
diego committed
1140 1141 1142
@item You can install FFmpeg in @file{Program Files/FFmpeg} by typing
@file{make install}. Don't forget to copy @file{SDL.dll} to the place
you launch @file{ffplay} from.
bellard's avatar
bellard committed
1143

1144 1145
@end itemize

1146
Notes:
bellard's avatar
bellard committed
1147
@itemize
bellard's avatar
bellard committed
1148

bellard's avatar
bellard committed
1149 1150
@item The target @file{make wininstaller} can be used to create a
Nullsoft based Windows installer for FFmpeg and FFplay. @file{SDL.dll}
diego's avatar
diego committed
1151
must be copied to the FFmpeg directory in order to build the
bellard's avatar
bellard committed
1152 1153
installer.

diego's avatar
diego committed
1154
@item By using @code{./configure --enable-shared} when configuring FFmpeg,
bellard's avatar
bellard committed
1155 1156
you can build @file{avcodec.dll} and @file{avformat.dll}. With
@code{make install} you install the FFmpeg DLLs and the associated
1157
headers in @file{Program Files/FFmpeg}.
bellard's avatar
bellard committed
1158

diego's avatar
diego committed
1159 1160
@item Visual C++ compatibility: If you used @code{./configure --enable-shared}
when configuring FFmpeg, FFmpeg tries to use the Microsoft Visual
bellard's avatar
bellard committed
1161
C++ @code{lib} tool to build @code{avcodec.lib} and
diego's avatar
diego committed
1162
@code{avformat.lib}. With these libraries you can link your Visual C++
1163
code directly with the FFmpeg DLLs (see below).
bellard's avatar
bellard committed
1164 1165

@end itemize
1166

1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206
@subsection Visual C++ compatibility

FFmpeg will not compile under Visual C++ -- and it has too many
dependencies on the GCC compiler to make a port viable. However,
if you want to use the FFmpeg libraries in your own applications,
you can still compile those applications using Visual C++. An
important restriction to this is that you have to use the
dynamically linked versions of the FFmpeg libraries (i.e. the
DLLs), and you have to make sure that Visual-C++-compatible
import libraries are created during the FFmpeg build process.

This description of how to use the FFmpeg libraries with Visual C++ is
based on Visual C++ 2005 Express Edition Beta 2. If you have a different
version, you might have to modify the procedures slightly.

Here are the step-by-step instructions for building the FFmpeg libraries
so they can be used with Visual C++:

@enumerate

@item Install Visual C++ (if you haven't done so already).

@item Install MinGW and MSYS as described above.

@item Add a call to @file{vcvars32.bat} (which sets up the environment
variables for the Visual C++ tools) as the first line of
@file{msys.bat}. The standard location for @file{vcvars32.bat} is
@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
and the standard location for @file{msys.bat} is
@file{C:\msys\1.0\msys.bat}. If this corresponds to your setup, add the
following line as the first line of @file{msys.bat}:

@code{call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"}

@item Start the MSYS shell (file @file{msys.bat}) and type @code{link.exe}.
If you get a help message with the command line options of @code{link.exe},
this means your environment variables are set up correctly, the
Microsoft linker is on the path and will be used by FFmpeg to
create Visual-C++-compatible import libraries.

1207
@item Extract the current version of FFmpeg and change to the FFmpeg directory.
1208 1209

@item Type the command
1210 1211 1212
@code{./configure --enable-shared --disable-static --enable-memalign-hack}
to configure and, if that didn't produce any errors,
type @code{make} to build FFmpeg.
1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256

@item The subdirectories @file{libavformat}, @file{libavcodec}, and
@file{libavutil} should now contain the files @file{avformat.dll},
@file{avformat.lib}, @file{avcodec.dll}, @file{avcodec.lib},
@file{avutil.dll}, and @file{avutil.lib}, respectively. Copy the three
DLLs to your System32 directory (typically @file{C:\Windows\System32}).

@end enumerate

And here is how to use these libraries with Visual C++:

@enumerate

@item Create a new console application ("File / New / Project") and then
select "Win32 Console Application". On the appropriate page of the
Application Wizard, uncheck the "Precompiled headers" option.

@item Write the source code for your application, or, for testing, just
copy the code from an existing sample application into the source file
that Visual C++ has already created for you. (Note that your source
filehas to have a @code{.cpp} extension; otherwise, Visual C++ won't
compile the FFmpeg headers correctly because in C mode, it doesn't
recognize the @code{inline} keyword.)  For example, you can copy
@file{output_example.c} from the FFmpeg distribution (but you will
have to make minor modifications so the code will compile under
C++, see below).

@item Open the "Project / Properties" dialog box. In the "Configuration"
combo box, select "All Configurations" so that the changes you make will
affect both debug and release builds. In the tree view on the left hand
side, select "C/C++ / General", then edit the "Additional Include
Directories" setting to contain the complete paths to the
@file{libavformat}, @file{libavcodec}, and @file{libavutil}
subdirectories of your FFmpeg directory. Note that the directories have
to be separated using semicolons. Now select "Linker / General" from the
tree view and edit the "Additional Library Directories" setting to
contain the same three directories.

@item Still in the "Project / Properties" dialog box, select "Linker / Input"
from the tree view, then add the files @file{avformat.lib},
@file{avcodec.lib}, and @file{avutil.lib} to the end of the "Additional
Dependencies". Note that the names of the libraries have to be separated
using spaces.

1257
@item Now, select "C/C++ / Code Generation" from the tree view. Select
1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282
"Debug" in the "Configuration" combo box. Make sure that "Runtime
Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
the "Configuration" combo box and make sure that "Runtime Library" is
set to "Multi-threaded DLL".

@item Click "OK" to close the "Project / Properties" dialog box and build
the application. Hopefully, it should compile and run cleanly. If you
used @file{output_example.c} as your sample application, you will get a
few compiler errors, but they are easy to fix. The first type of error
occurs because Visual C++ doesn't allow an @code{int} to be converted to
an @code{enum} without a cast. To solve the problem, insert the required
casts (this error occurs once for a @code{CodecID} and once for a
@code{CodecType}).  The second type of error occurs because C++ requires
the return value of @code{malloc} to be cast to the exact type of the
pointer it is being assigned to. Visual C++ will complain that, for
example, @code{(void *)} is being assigned to @code{(uint8_t *)} without
an explicit cast. So insert an explicit cast in these places to silence
the compiler. The third type of error occurs because the @code{snprintf}
library function is called @code{_snprintf} under Visual C++.  So just
add an underscore to fix the problem. With these changes,
@file{output_example.c} should compile under Visual C++, and the
resulting executable should produce valid video files.

@end enumerate

1283 1284 1285 1286 1287
@subsection Cross compilation for Windows with Linux

You must use the MinGW cross compilation tools available at
@url{http://www.mingw.org/}.

diego's avatar
diego committed
1288
Then configure FFmpeg with the following options:
1289 1290 1291
@example
./configure --enable-mingw32 --cross-prefix=i386-mingw32msvc-
@end example
diego's avatar
diego committed
1292
(you can change the cross-prefix according to the prefix chosen for the
1293 1294
MinGW tools).

diego's avatar
diego committed
1295
Then you can easily test FFmpeg with Wine
1296 1297
(@url{http://www.winehq.com/}).

1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351
@subsection Compilation under Cygwin

Cygwin works very much like Unix.

Just install your Cygwin with all the "Base" packages, plus the
following "Devel" ones:
@example
binutils, gcc-core, make, subversion
@end example

Do not install binutils-20060709-1 (they are buggy on shared builds);
use binutils-20050610-1 instead.

Then run

@example
./configure --enable-static --disable-shared
@end example

to make a static build or

@example
./configure --enable-shared --disable-static
@end example

to build shared libraries.

If you want to build FFmpeg with additional libraries, download Cygwin
"Devel" packages for Ogg and Vorbis from any Cygwin packages repository
and/or SDL, xvid, faac, faad2 packages from Cygwin Ports,
(@url{http://cygwinports.dotsrc.org/}).

@subsection Crosscompilation for Windows under Cygwin

With Cygwin you can create Windows binaries that don't need the cygwin1.dll.

Just install your Cygwin as explained before, plus these additional
"Devel" packages:
@example
gcc-mingw-core, mingw-runtime, mingw-zlib
@end example

and add some special flags to your configure invocation.

For a static build run
@example
./configure --enable-mingw32 --enable-memalign-hack --enable-static --disable-shared --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
@end example

and for a build with shared libraries
@example
./configure --enable-mingw32 --enable-memalign-hack --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
@end example

bellard's avatar
bellard committed
1352 1353 1354 1355 1356 1357 1358 1359
@section BeOS

The configure script should guess the configuration itself.
Networking support is currently not finished.
errno issues fixed by Andrew Bachmann.

Old stuff:

1360
François Revol - revol at free dot fr - April 2002
bellard's avatar
bellard committed
1361

1362
The configure script should guess the configuration itself,
diego's avatar
diego committed
1363
however I still didn't test building on the net_server version of BeOS.
bellard's avatar
bellard committed
1364

diego's avatar
diego committed
1365
FFserver is broken (needs poll() implementation).
bellard's avatar
bellard committed
1366

diego's avatar
diego committed
1367
There are still issues with errno codes, which are negative in BeOS, and
1368
that FFmpeg negates when returning. This ends up turning errors into
bellard's avatar
bellard committed
1369 1370 1371
valid results, then crashes.
(To be fixed)

philipjsg's avatar
philipjsg committed
1372
@chapter Developers Guide
1373 1374

@section API
1375
@itemize @bullet
1376
@item libavcodec is the library containing the codecs (both encoding and
diego's avatar
diego committed
1377
decoding). Look at @file{libavcodec/apiexample.c} to see how to use it.
1378

diego's avatar
diego committed
1379 1380
@item libavformat is the library containing the file format handling (mux and
demux code for several formats). Look at @file{ffplay.c} to use it in a
bellard's avatar
bellard committed
1381 1382 1383
player. See @file{output_example.c} to use it to generate audio or video
streams.

1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394
@end itemize

@section Integrating libavcodec or libavformat in your program

You can integrate all the source code of the libraries to link them
statically to avoid any version problem. All you need is to provide a
'config.mak' and a 'config.h' in the parent directory. See the defines
generated by ./configure to understand what is needed.

You can use libavcodec or libavformat in your commercial program, but
@emph{any patch you make must be published}. The best way to proceed is
diego's avatar
diego committed
1395
to send your patches to the FFmpeg mailing list.
1396

1397
@node Coding Rules
1398 1399
@section Coding Rules

diego's avatar
diego committed
1400
FFmpeg is programmed in the ISO C90 language with a few additional
mellum's avatar
mellum committed
1401 1402 1403 1404 1405 1406 1407 1408 1409
features from ISO C99, namely:
@itemize @bullet
@item
the @samp{inline} keyword;
@item
@samp{//} comments;
@item
designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
@item
diego's avatar
diego committed
1410
compound literals (@samp{x = (struct s) @{ 17, 23 @};})
mellum's avatar
mellum committed
1411 1412 1413 1414 1415 1416
@end itemize

These features are supported by all compilers we care about, so we won't
accept patches to remove their use unless they absolutely don't impair
clarity and performance.

diego's avatar
diego committed
1417
All code must compile with GCC 2.95 and GCC 3.3. Currently, FFmpeg also
mellum's avatar
mellum committed
1418 1419 1420
compiles with several other compilers, such as the Compaq ccc compiler
or Sun Studio 9, and we would like to keep it that way unless it would
be exceedingly involved. To ensure compatibility, please don't use any
diego's avatar
diego committed
1421
additional C99 features or GCC extensions. Especially watch out for:
mellum's avatar
mellum committed
1422 1423 1424 1425 1426 1427 1428 1429
@itemize @bullet
@item
mixing statements and declarations;
@item
@samp{long long} (use @samp{int64_t} instead);
@item
@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
@item
diego's avatar
diego committed
1430
GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
mellum's avatar
mellum committed
1431
@end itemize
1432

1433
Indent size is 4.
1434
The presentation is the one specified by 'indent -i4 -kr -nut'.
1435 1436
The TAB character is forbidden outside of Makefiles as is any
form of trailing whitespace. Commits containing either will be
diego's avatar
diego committed
1437
rejected by the Subversion repository.
1438

diego's avatar
diego committed
1439
Main priority in FFmpeg is simplicity and small code size (=less
1440 1441
bugs).

diego's avatar
diego committed
1442 1443 1444 1445 1446
Comments: Use the JavaDoc/Doxygen
format (see examples below) so that code documentation
can be generated automatically. All nontrivial functions should have a comment
above them explaining what the function does, even if it's just one sentence.
All structures and their member variables should be documented, too.
michael's avatar
michael committed
1447 1448
@example
/**
mru's avatar
mru committed
1449 1450 1451 1452
 * @@file mpeg.c
 * MPEG codec.
 * @@author ...
 */
michael's avatar
michael committed
1453 1454

/**
mru's avatar
mru committed
1455 1456 1457 1458
 * Summary sentence.
 * more text ...
 * ...
 */
diego's avatar
diego committed
1459
typedef struct Foobar@{
mru's avatar
mru committed
1460 1461 1462 1463
    int var1; /**< var1 description */
    int var2; ///< var2 description
    /** var3 description */
    int var3;
diego's avatar
diego committed
1464
@} Foobar;
michael's avatar
michael committed
1465 1466

/**
mru's avatar
mru committed
1467 1468 1469 1470 1471 1472
 * Summary sentence.
 * more text ...
 * ...
 * @@param my_parameter description of my_parameter
 * @@return return value description
 */
michael's avatar
michael committed
1473 1474 1475
int myfunc(int my_parameter)
...
@end example
1476

1477
fprintf and printf are forbidden in libavformat and libavcodec,
1478 1479
please use av_log() instead.

diego's avatar
diego committed
1480
@section Development Policy
michael's avatar
michael committed
1481 1482

@enumerate
1483
@item
michael's avatar
michael committed
1484
   You must not commit code which breaks FFmpeg! (Meaning unfinished but
diego's avatar
diego committed
1485
   enabled code which breaks compilation or compiles but does not work or
michael's avatar
michael committed
1486 1487 1488 1489
   breaks the regression tests)
   You can commit unfinished stuff (for testing etc), but it must be disabled
   (#ifdef etc) by default so it does not interfere with other developers'
   work.
1490
@item
michael's avatar
michael committed
1491
   You don't have to over-test things. If it works for you, and you think it
diego's avatar
diego committed
1492 1493
   should work for others, then commit. If your code has problems
   (portability, triggers compiler bugs, unusual environment etc) they will be
michael's avatar
michael committed
1494
   reported and eventually fixed.
1495
@item
michael's avatar
michael committed
1496 1497 1498 1499
   Do not commit unrelated changes together, split them into self-contained
   pieces.
@item
   Do not change behavior of the program (renaming options etc) without
diego's avatar
diego committed
1500
   first discussing it on the ffmpeg-devel mailing list. Do not remove
michael's avatar
michael committed
1501
   functionality from the code. Just improve!
1502

diego's avatar
diego committed
1503
   Note: Redundant code can be removed.
michael's avatar
michael committed
1504 1505
@item
   Do not commit changes to the build system (Makefiles, configure script)
diego's avatar
diego committed
1506
   which change behavior, defaults etc, without asking first. The same
michael's avatar
michael committed
1507 1508
   applies to compiler warning fixes, trivial looking fixes and to code
   maintained by other developers. We usually have a reason for doing things
diego's avatar
diego committed
1509
   the way we do. Send your changes as patches to the ffmpeg-devel mailing
michael's avatar
michael committed
1510 1511 1512 1513 1514 1515 1516
   list, and if the code maintainers say OK, you may commit. This does not
   apply to files you wrote and/or maintain.
@item
   We refuse source indentation and other cosmetic changes if they are mixed
   with functional changes, such commits will be rejected and removed. Every
   developer has his own indentation style, you should not change it. Of course
   if you (re)write something, you can use your own style, even though we would
diego's avatar
diego committed
1517 1518
   prefer if the indentation throughout FFmpeg was consistent (Many projects
   force a given indentation style - we don't.). If you really need to make
michael's avatar
michael committed
1519 1520 1521
   indentation changes (try to avoid this), separate them strictly from real
   changes.

diego's avatar
diego committed
1522
   NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code,
1523
   then either do NOT change the indentation of the inner part within (don't
diego's avatar
diego committed
1524
   move it to the right)! or do so in a separate commit
michael's avatar
michael committed
1525 1526 1527 1528 1529 1530
@item
   Always fill out the commit log message. Describe in a few lines what you
   changed and why. You can refer to mailing list postings if you fix a
   particular bug. Comments such as "fixed!" or "Changed it." are unacceptable.
@item
   If you apply a patch by someone else, include the name and email address in
diego's avatar
diego committed
1531
   the log message. Since the ffmpeg-cvslog mailing list is publicly
diego's avatar
diego committed
1532 1533
   archived you should add some SPAM protection to the email address. Send an
   answer to ffmpeg-devel (or wherever you got the patch from) saying that
michael's avatar
michael committed
1534 1535
   you applied the patch.
@item
diego's avatar
diego committed
1536 1537 1538 1539 1540
    Do NOT commit to code actively maintained by others without permission.
    Send a patch to ffmpeg-devel instead. If noone answers within a reasonable
    timeframe (12h for build failures and security fixes, 3 days small changes,
    1 week for big patches) then commit your patch if you think it's OK.
    Also note, the maintainer can simply ask for more time to review!
michael's avatar
michael committed
1541
@item
diego's avatar
diego committed
1542
    Subscribe to the ffmpeg-cvslog mailing list. The diffs of all commits
michael's avatar
michael committed
1543 1544 1545 1546 1547
    are sent there and reviewed by all the other developers. Bugs and possible
    improvements or general questions regarding commits are discussed there. We
    expect you to react if problems with your code are uncovered.
@item
    Update the documentation if you change behavior or add features. If you are
diego's avatar
diego committed
1548
    unsure how best to do this, send a patch to ffmpeg-devel, the documentation
michael's avatar
michael committed
1549
    maintainer(s) will review and commit your stuff.
michael's avatar
michael committed
1550
@item
diego's avatar
diego committed
1551 1552 1553
    Never write to unallocated memory, never write over the end of arrays,
    always check values read from some untrusted source before using them
    as array index or other risky things.
1554 1555
@item
    Remember to check if you need to bump versions for the specific libav
diego's avatar
diego committed
1556
    parts (libavutil, libavcodec, libavformat) you are changing. You need
1557 1558
    to change the version integer and the version string.
    Incrementing the first component means no backward compatibility to
michael's avatar
michael committed
1559
    previous versions (e.g. removal of a function from the public API).
1560
    Incrementing the second component means backward compatible change
michael's avatar
michael committed
1561
    (e.g. addition of a function to the public API).
1562 1563
    Incrementing the third component means a noteworthy binary compatible
    change (e.g. encoder bug fix that matters for the decoder).
1564
@item
diego's avatar
diego committed
1565 1566 1567 1568 1569
    If you add a new codec, remember to update the changelog, add it to
    the supported codecs table in the documentation and bump the second
    component of the @file{libavcodec} version number appropriately. If
    it has a fourcc, add it to @file{libavformat/avienc.c}, even if it
    is only a decoder.
diego's avatar
diego committed
1570
@end enumerate
michael's avatar
michael committed
1571 1572 1573 1574 1575

We think our rules are not too hard. If you have comments, contact us.

Note, these rules are mostly borrowed from the MPlayer project.

1576 1577
@section Submitting patches

1578 1579
First, (@pxref{Coding Rules}) above if you didn't yet.

michael's avatar
michael committed
1580
When you submit your patch, try to send a unified diff (diff '-up'
1581 1582
option). I cannot read other diffs :-)

1583
Also please do not submit patches which contain several unrelated changes.
1584
Split them into individual self-contained patches; this makes reviewing
1585 1586
them much easier.

1587
Run the regression tests before submitting a patch so that you can
1588
verify that there are no big problems.
1589 1590

Patches should be posted as base64 encoded attachments (or any other
diego's avatar
diego committed
1591
encoding which ensures that the patch won't be trashed during
1592
transmission) to the ffmpeg-devel mailing list, see
1593
@url{http://lists.mplayerhq.hu/mailman/listinfo/ffmpeg-devel}
1594

1595
It also helps quite a bit if you tell us what the patch does (for example
diego's avatar
diego committed
1596
'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant
1597 1598
and has no lrint()')

diego's avatar
diego committed
1599 1600
We reply to all submitted patches and either apply or reject with some
explanation why, but sometimes we are quite busy so it can take a week or two.
1601

1602 1603
@section Regression tests

diego's avatar
diego committed
1604
Before submitting a patch (or committing to the repository), you should at least
1605 1606
test that you did not break anything.

diego's avatar
diego committed
1607 1608
The regression tests build a synthetic video stream and a synthetic
audio stream. These are then encoded and decoded with all codecs or
1609
formats. The CRC (or MD5) of each generated file is recorded in a
diego's avatar
diego committed
1610
result file. A 'diff' is launched to compare the reference results and
1611 1612
the result file.

diego's avatar
diego committed
1613
The regression tests then go on to test the FFserver code with a
1614 1615 1616
limited set of streams. It is important that this step runs correctly
as well.

1617
Run 'make test' to test all the codecs and formats.
1618

diego's avatar
diego committed
1619
Run 'make fulltest' to test all the codecs, formats and FFserver.
1620

diego's avatar
diego committed
1621 1622
[Of course, some patches may change the results of the regression tests. In
this case, the reference results of the regression tests shall be modified
1623 1624 1625
accordingly].

@bye