Fix compilation, there is no file vdpauvideo.c, only vdpau.c
[libav.git] / doc / general.texi
CommitLineData
d0e1cd3d
DB
1\input texinfo @c -*- texinfo -*-
2
3@settitle General Documentation
4@titlepage
5@sp 7
6@center @titlefont{General Documentation}
7@sp 3
8@end titlepage
9
10
11@chapter external libraries
12
13FFmpeg can be hooked up with a number of external libraries to add support
14for more formats. None of them are used by default, their use has to be
15explicitly requested by passing the appropriate flags to @file{./configure}.
16
17@section AMR
18
50e4d833
DB
19AMR comes in two different flavors, wideband and narrowband. FFmpeg can make
20use of the AMR wideband (floating-point mode) and the AMR narrowband
21(floating-point mode) reference decoders and encoders.
d0e1cd3d
DB
22
23Go to @url{http://www.penguin.cz/~utx/amr} and follow the instructions for
24installing the libraries. Then pass @code{--enable-libamr-nb} and/or
25@code{--enable-libamr-wb} to configure to enable the libraries.
26
68e7d442
DB
27Note that libamr is copyrighted without any sort of license grant. This means
28that you can use it if you legally obtained it but you are not allowed to
29redistribute it in any way. @strong{Any FFmpeg binaries with libamr support
30you create are non-free and unredistributable!}
31
d0e1cd3d
DB
32
33@chapter Supported File Formats and Codecs
34
35You can use the @code{-formats} option to have an exhaustive list.
36
37@section File Formats
38
39FFmpeg supports the following file formats through the @code{libavformat}
40library:
41
42@multitable @columnfractions .4 .1 .1 .4
b3de4544 43@item Name @tab Encoding @tab Decoding @tab Comments
64c2f20a 44@item 4xm @tab @tab X
c6b2dc34
DB
45 @tab 4X Technologies format, used in some games.
46@item ADTS AAC audio @tab X @tab X
64c2f20a
DB
47@item American Laser Games MM @tab @tab X
48 @tab Multimedia format used in games like Mad Dog McCree.
c6b2dc34
DB
49@item ASF @tab X @tab X
50@item AVI @tab X @tab X
51@item AVM2 (Flash 9) @tab X @tab X
d698c5d3 52 @tab Only embedded audio is decoded.
c6b2dc34 53@item AVS @tab @tab X
d698c5d3 54 @tab Multimedia format used by the Creature Shock game.
c6b2dc34 55@item Bethsoft VID @tab @tab X
d698c5d3 56 @tab Used in some games from Bethesda Softworks.
64c2f20a
DB
57@item BFI @tab @tab X
58 @tab Brute Force & Ignorance, used in Flash Traffic: City of Angels.
c6b2dc34 59@item C93 @tab @tab X
d698c5d3 60 @tab Used in the game Cyberia from Interplay.
c6b2dc34 61@item CIN @tab @tab X
d698c5d3 62 @tab Multimedia format used by Delphine Software games.
c6b2dc34 63@item Creative VOC @tab X @tab X
d698c5d3 64 @tab Created for the Sound Blaster Pro.
64c2f20a
DB
65@item CRYO APC @tab @tab X
66 @tab Audio format used in some games by CRYO Interactive Entertainment.
c6b2dc34
DB
67@item DV @tab X @tab X
68@item DXA @tab @tab X
d698c5d3
DB
69 @tab This format is used in the non-Windows version of the Feeble Files
70 game and different game cutscenes repacked for use with ScummVM.
c6b2dc34 71@item Electronic Arts Multimedia @tab @tab X
d698c5d3 72 @tab Used in various EA games; files have extensions like WVE and UV2.
c6b2dc34 73@item FLIC @tab @tab X
d698c5d3 74 @tab .fli/.flc files
c6b2dc34 75@item FLV @tab X @tab X
d698c5d3 76 @tab Macromedia Flash video files
055dc116
SG
77@item FunCom ISS @tab @tab X
78 @tab Audio format used in various games from FunCom like The Longest Journey.
c6b2dc34 79@item GXF @tab X @tab X
d698c5d3 80 @tab General eXchange Format SMPTE 360M, used by Thomson Grass Valley
64c2f20a 81 playout servers.
76ec3939 82@item id Cinematic @tab @tab X
d698c5d3 83 @tab Used in Quake II.
76ec3939 84@item id RoQ @tab X @tab X
d698c5d3 85 @tab Used in Quake III, Jedi Knight 2, other computer games.
c6b2dc34 86@item IFF @tab @tab X
d698c5d3 87 @tab Interchange File Format
c6b2dc34 88@item Interplay MVE @tab @tab X
d698c5d3 89 @tab Format used in various Interplay computer games.
c6b2dc34 90@item LMLM4 @tab @tab X
d698c5d3 91 @tab Used by Linux Media Labs MPEG-4 PCI boards
64c2f20a 92@item Matroska @tab X @tab X
c6b2dc34 93@item MAXIS EA XA @tab @tab X
d698c5d3 94 @tab Used in Sim City 3000; file extension .xa.
64c2f20a 95@item Monkey's Audio @tab @tab X
822cc8f7 96@item Motion Pixels MVI @tab @tab X
64c2f20a 97@item MOV/QuickTime @tab X @tab X
c6b2dc34
DB
98@item MPEG audio @tab X @tab X
99@item MPEG-1 systems @tab X @tab X
d698c5d3 100 @tab muxed audio and video
c6b2dc34 101@item MPEG-2 PS @tab X @tab X
d698c5d3 102 @tab also known as @code{VOB} file
c6b2dc34 103@item MPEG-2 TS @tab @tab X
d698c5d3 104 @tab also known as DVB Transport Stream
c6b2dc34 105@item MPEG-4 @tab X @tab X
d698c5d3 106 @tab MPEG-4 is a variant of QuickTime.
bac4c85c 107@item MSN TCP webcam @tab @tab X
d698c5d3 108 @tab Used by MSN Messenger webcam streams.
bb68b69d 109@item MXF @tab X @tab X
d698c5d3 110 @tab Material eXchange Format SMPTE 377M, used by D-Cinema, broadcast industry.
eaf5d011
NM
111@item NC @tab @tab X
112 @tab NC (AVIP NC4600) cameras streams.
64c2f20a 113@item Nullsoft Video @tab @tab X
c6b2dc34 114@item NUT @tab X @tab X
d698c5d3 115 @tab NUT Open Container Format
c6b2dc34 116@item OMA @tab @tab X
d698c5d3 117 @tab Audio format used in Sony Sonic Stage and Sony Vegas.
64c2f20a 118@item PlayStation STR @tab @tab X
c6b2dc34 119@item PVA @tab @tab X
d698c5d3 120 @tab Used by TechnoTrend DVB PCI boards.
76ec3939
DB
121@item raw AC-3 @tab X @tab X
122@item raw CRI ADX audio @tab X @tab X
123@item raw MJPEG @tab X @tab X
124@item raw MPEG video @tab X @tab X
125@item raw MPEG-4 video @tab X @tab X
eb6fc557 126@item raw PCM 8/16/32 bits, 32/64-bit floating point, mu-law/A-law @tab X @tab X
76ec3939 127@item raw Shorten audio @tab @tab X
7eb68edb
BC
128@item R3D REDCODE @tab @tab X
129 @tab File format used by RED Digital cameras, contains JPEG 2000 frames and PCM audio.
64c2f20a 130@item RealMedia @tab X @tab X
c6b2dc34 131@item RL2 @tab @tab X
d698c5d3 132 @tab Audio and video format used in some games by Entertainment Software Partners.
c6b2dc34 133@item Sega FILM/CPK @tab @tab X
d698c5d3 134 @tab Used in many Sega Saturn console games.
64c2f20a
DB
135@item SEQ @tab @tab X
136 @tab Tiertex .seq files used in the DOS CD-ROM version of the game Flashback.
c6b2dc34 137@item Sierra Online @tab @tab X
d698c5d3 138 @tab .sol files used in Sierra Online games.
c6b2dc34 139@item Sierra VMD @tab @tab X
d698c5d3 140 @tab Used in Sierra CD-ROM games.
64c2f20a
DB
141@item SIFF @tab @tab X
142 @tab Audio and video format used in some games by Beam Software.
c6b2dc34 143@item Smacker @tab @tab X
d698c5d3 144 @tab Multimedia format used by many games.
64c2f20a 145@item SUN AU format @tab X @tab X
c6b2dc34 146@item THP @tab @tab X
d698c5d3 147 @tab Used on the Nintendo GameCube.
c6b2dc34
DB
148@item WAV @tab X @tab X
149@item WC3 Movie @tab @tab X
d698c5d3 150 @tab Multimedia format used in Origin's Wing Commander III computer game.
c6b2dc34 151@item Westwood Studios VQA/AUD @tab @tab X
d698c5d3 152 @tab Multimedia formats used in Westwood Studios games.
d0e1cd3d
DB
153@end multitable
154
155@code{X} means that encoding (resp. decoding) is supported.
156
157@section Image Formats
158
159FFmpeg can read and write images for each frame of a video sequence. The
160following image formats are supported:
161
162@multitable @columnfractions .4 .1 .1 .4
b3de4544 163@item Name @tab Encoding @tab Decoding @tab Comments
64c2f20a 164@item .Y.U.V @tab X @tab X @tab one raw file per component
3d172fb5
DB
165@item animated GIF @tab X @tab X @tab Only uncompressed GIFs are generated.
166@item JPEG @tab X @tab X @tab Progressive JPEG is not supported.
9a77d59a 167@item JPEG 2000 @tab @tab E @tab decoding supported through external library libopenjpeg
d0e1cd3d 168@item PAM @tab X @tab X @tab PAM is a PNM extension with alpha support.
3d172fb5
DB
169@item PCX @tab @tab X @tab PC Paintbrush
170@item PGM, PPM @tab X @tab X
d0e1cd3d 171@item PGMYUV @tab X @tab X @tab PGM with U and V components in YUV 4:2:0
0a91f4ee 172@item PNG @tab X @tab X @tab 2/4 bpp not supported yet
d0e1cd3d 173@item PTX @tab @tab X @tab V.Flash PTX format
d1928ac1 174@item RAS @tab @tab X @tab Sun Rasterfile
3d172fb5 175@item SGI @tab X @tab X @tab SGI RGB image format
3d172fb5 176@item Targa @tab @tab X @tab Targa (.TGA) image format
64c2f20a 177@item TIFF @tab X @tab X @tab YUV, JPEG and some extension is not supported yet.
d0e1cd3d
DB
178@end multitable
179
180@code{X} means that encoding (resp. decoding) is supported.
181
9a77d59a
JM
182@code{E} means that support is provided through an external library.
183
d0e1cd3d
DB
184@section Video Codecs
185
186@multitable @columnfractions .4 .1 .1 .4
b3de4544 187@item Name @tab Encoding @tab Decoding @tab Comments
d66d8b83 188@item 4X Video @tab @tab X
d698c5d3 189 @tab Used in certain computer games.
d66d8b83 190@item American Laser Games Video @tab @tab X
d698c5d3 191 @tab Used in games like Mad Dog McCree.
d66d8b83 192@item AMV @tab @tab X
d698c5d3 193 @tab Used in Chinese MP3 players.
d66d8b83 194@item Apple Animation @tab X @tab X
d698c5d3 195 @tab fourcc: 'rle '
d66d8b83 196@item Apple Graphics @tab @tab X
d698c5d3 197 @tab fourcc: 'smc '
d66d8b83
DB
198@item Apple MJPEG-B @tab @tab X
199@item Apple QuickDraw @tab @tab X
d698c5d3 200 @tab fourcc: qdrw
d66d8b83 201@item Apple Video @tab @tab X
d698c5d3 202 @tab fourcc: rpza
d66d8b83 203@item Asus v1 @tab X @tab X
d698c5d3 204 @tab fourcc: ASV1
d66d8b83 205@item Asus v2 @tab X @tab X
d698c5d3 206 @tab fourcc: ASV2
d66d8b83 207@item ATI VCR1 @tab @tab X
d698c5d3 208 @tab fourcc: VCR1
d66d8b83 209@item ATI VCR2 @tab @tab X
d698c5d3 210 @tab fourcc: VCR2
d66d8b83 211@item Autodesk RLE @tab @tab X
d698c5d3 212 @tab fourcc: AASC
d66d8b83 213@item AVID DNxHD @tab X @tab X
d698c5d3 214 @tab aka SMPTE VC3
bac4c85c 215@item AVS video @tab @tab X
d698c5d3 216 @tab Video encoding used by the Creature Shock game.
d66d8b83 217@item Bethsoft VID @tab @tab X
d698c5d3 218 @tab Used in some games from Bethesda Softworks.
bac4c85c 219@item C93 video @tab @tab X
d698c5d3 220 @tab Codec used in Cyberia game.
d66d8b83 221@item CamStudio @tab @tab X
d698c5d3 222 @tab fourcc: CSCD
bac4c85c 223@item Cin video @tab @tab X
d698c5d3 224 @tab Codec used in Delphine Software games.
d66d8b83
DB
225@item Cinepak @tab @tab X
226@item Cirrus Logic AccuPak @tab @tab X
d698c5d3 227 @tab fourcc: CLJR
d66d8b83 228@item Creative YUV @tab @tab X
d698c5d3 229 @tab fourcc: CYUV
82ced5a9 230@item Dirac @tab E @tab E
360f980b 231 @tab supported through external libdirac/libschroedinger libraries
d66d8b83 232@item Duck TrueMotion v1 @tab @tab X
d698c5d3 233 @tab fourcc: DUCK
d66d8b83 234@item Duck TrueMotion v2 @tab @tab X
d698c5d3 235 @tab fourcc: TM20
d66d8b83
DB
236@item DV @tab X @tab X
237@item DXA Video @tab @tab X
d698c5d3 238 @tab Codec originally used in Feeble Files game.
d66d8b83 239@item Electronic Arts CMV @tab @tab X
d698c5d3 240 @tab Used in NHL 95 game.
cfc78718 241@item Electronic Arts TGV @tab @tab X
42b30357 242@item Electronic Arts TGQ @tab @tab X
d8964f3a 243@item Electronic Arts TQI @tab @tab X
d66d8b83 244@item FFmpeg Video 1 @tab X @tab X
d698c5d3 245 @tab experimental lossless codec (fourcc: FFV1)
d66d8b83 246@item Flash Screen Video @tab X @tab X
d698c5d3 247 @tab fourcc: FSV1
d66d8b83
DB
248@item FLIC video @tab @tab X
249@item FLV @tab X @tab X
d698c5d3 250 @tab Sorenson H.263 used in Flash
d66d8b83
DB
251@item Fraps FPS1 @tab @tab X
252@item H.261 @tab X @tab X
253@item H.263(+) @tab X @tab X
d698c5d3 254 @tab also known as RealVideo 1.0
82ced5a9 255@item H.264 @tab E @tab X
360f980b 256 @tab encoding supported through external library libx264
d66d8b83
DB
257@item HuffYUV @tab X @tab X
258@item IBM Ultimotion @tab @tab X
d698c5d3 259 @tab fourcc: ULTI
bac4c85c 260@item id Cinematic video @tab @tab X
d698c5d3 261 @tab Used in Quake II.
d66d8b83 262@item id RoQ @tab X @tab X
d698c5d3 263 @tab Used in Quake III, Jedi Knight 2, other computer games.
d66d8b83
DB
264@item Intel Indeo 3 @tab @tab X
265@item Interplay Video @tab @tab X
d698c5d3 266 @tab Used in Interplay .MVE files.
d66d8b83 267@item JPEG-LS @tab X @tab X
d698c5d3 268 @tab fourcc: MJLS, lossless and near-lossless is supported.
d66d8b83 269@item KMVC @tab @tab X
d698c5d3 270 @tab Codec used in Worms games.
d66d8b83
DB
271@item LOCO @tab @tab X
272@item lossless MJPEG @tab X @tab X
273@item Microsoft RLE @tab @tab X
274@item Microsoft Video-1 @tab @tab X
275@item Mimic @tab @tab X
d698c5d3 276 @tab Used in MSN Messenger Webcam streams.
d66d8b83 277@item Miro VideoXL @tab @tab X
d698c5d3 278 @tab fourcc: VIXL
d66d8b83 279@item MJPEG @tab X @tab X
822cc8f7 280@item Motion Pixels Video @tab @tab X
bac4c85c
DB
281@item MPEG-1 @tab X @tab X
282@item MPEG-2 @tab X @tab X
d0e1cd3d
DB
283@item MPEG-4 @tab X @tab X
284@item MSMPEG4 V1 @tab X @tab X
285@item MSMPEG4 V2 @tab X @tab X
286@item MSMPEG4 V3 @tab X @tab X
d66d8b83 287@item MSZH @tab @tab X
d698c5d3 288 @tab Part of LCL
d66d8b83 289@item On2 VP3 @tab @tab X
d698c5d3 290 @tab still experimental
d66d8b83 291@item On2 VP5 @tab @tab X
d698c5d3 292 @tab fourcc: VP50
d66d8b83 293@item On2 VP6 @tab @tab X
d698c5d3 294 @tab fourcc: VP60,VP61,VP62
d66d8b83 295@item planar RGB @tab @tab X
d698c5d3 296 @tab fourcc: 8BPS
d66d8b83 297@item QPEG @tab @tab X
d698c5d3 298 @tab fourccs: QPEG, Q1.0, Q1.1
d0e1cd3d
DB
299@item RealVideo 1.0 @tab X @tab X
300@item RealVideo 2.0 @tab X @tab X
6beb8b26
KS
301@item RealVideo 3.0 @tab @tab X
302 @tab still far from ideal
11c0f9ec 303@item RealVideo 4.0 @tab @tab X
d66d8b83 304@item Renderware TXD @tab @tab X
d698c5d3 305 @tab Texture dictionaries used by the Renderware Engine.
d66d8b83 306@item RTjpeg @tab @tab X
d698c5d3 307 @tab Video encoding used in NuppelVideo files.
bac4c85c 308@item Smacker video @tab @tab X
d698c5d3 309 @tab Video encoding used in Smacker.
d66d8b83 310@item Snow @tab X @tab X
d698c5d3 311 @tab experimental wavelet codec (fourcc: SNOW)
831ec935 312@item Sony PlayStation MDEC @tab @tab X
d66d8b83 313@item Sorenson Video 1 @tab X @tab X
d698c5d3 314 @tab fourcc: SVQ1
d66d8b83 315@item Sorenson Video 3 @tab @tab X
d698c5d3 316 @tab fourcc: SVQ3
d66d8b83 317@item Sunplus MJPEG @tab @tab X
d698c5d3 318 @tab fourcc: SP5X
d66d8b83 319@item TechSmith Camtasia @tab @tab X
d698c5d3 320 @tab fourcc: TSCC
82ced5a9 321@item Theora @tab E @tab X
360f980b 322 @tab encoding supported through external library libtheora
d66d8b83 323@item THP @tab @tab X
d698c5d3 324 @tab Used on the Nintendo GameCube.
bac4c85c 325@item Tiertex Seq video @tab @tab X
d698c5d3 326 @tab Codec used in DOS CD-ROM FlashBack game.
d66d8b83
DB
327@item VC-1 @tab @tab X
328@item VMD Video @tab @tab X
d698c5d3 329 @tab Used in Sierra VMD files.
d66d8b83 330@item VMware Video @tab @tab X
d698c5d3 331 @tab Codec used in videos captured by VMware.
d0e1cd3d 332@item Westwood VQA @tab @tab X
d66d8b83
DB
333@item Winnov WNV1 @tab @tab X
334@item WMV7 @tab X @tab X
335@item WMV8 @tab X @tab X
336@item WMV9 @tab @tab X
d698c5d3 337 @tab not completely working
d66d8b83 338@item Xan/WC3 @tab @tab X
d698c5d3 339 @tab Used in Wing Commander III .MVE files.
d66d8b83 340@item ZLIB @tab X @tab X
d698c5d3 341 @tab part of LCL, encoder experimental
d66d8b83 342@item ZMBV @tab X @tab X
d698c5d3 343 @tab Encoder works only in PAL8.
d0e1cd3d
DB
344@end multitable
345
346@code{X} means that encoding (resp. decoding) is supported.
347
82ced5a9
DB
348@code{E} means that support is provided through an external library.
349
d0e1cd3d
DB
350@section Audio Codecs
351
485ec4f1 352@multitable @columnfractions .4 .1 .1 .4
b3de4544 353@item Name @tab Encoding @tab Decoding @tab Comments
16d81b27
DB
354@item 4X IMA ADPCM @tab @tab X
355@item 8SVX audio @tab @tab X
82ced5a9 356@item AAC @tab E @tab X
360f980b 357 @tab encoding supported through external library libfaac
16d81b27 358@item AC-3 @tab IX @tab IX
82ced5a9 359@item AMR-NB @tab E @tab E
360f980b 360 @tab supported through external library libamrnb
82ced5a9 361@item AMR-WB @tab E @tab E
360f980b 362 @tab supported through external library libamrwb
16d81b27 363@item AMV IMA ADPCM @tab @tab X
d698c5d3 364 @tab Used in AMV files
833e90dd 365@item Apple lossless audio @tab X @tab X
d698c5d3 366 @tab QuickTime fourcc 'alac'
16d81b27
DB
367@item Apple MACE 3 @tab @tab X
368@item Apple MACE 6 @tab @tab X
369@item ATRAC 3 @tab @tab X
370@item CD-ROM XA ADPCM @tab @tab X
bac4c85c 371@item Cin audio @tab @tab X
d698c5d3 372 @tab Codec used in Delphine Software International games.
16d81b27 373@item Creative ADPCM @tab @tab X
d698c5d3 374 @tab 16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
16d81b27 375@item CRI ADX ADPCM @tab X @tab X
d698c5d3 376 @tab Used in Sega Dreamcast games.
16d81b27
DB
377@item DSP Group TrueSpeech @tab @tab X
378@item DTS Coherent Audio @tab @tab X
379@item Duck DK3 IMA ADPCM @tab @tab X
d698c5d3 380 @tab Used in some Sega Saturn console games.
16d81b27 381@item Duck DK4 IMA ADPCM @tab @tab X
d698c5d3 382 @tab Used in some Sega Saturn console games.
16d81b27
DB
383@item DV audio @tab @tab X
384@item Electronic Arts ADPCM @tab @tab X
d698c5d3 385 @tab Used in various EA titles.
44723c84 386@item Enhanced AC-3 @tab @tab X
9a584db4 387@item FLAC lossless audio @tab IX @tab X
16d81b27 388@item G.726 ADPCM @tab X @tab X
82ced5a9 389@item GSM @tab E @tab E
3f33271a 390 @tab supported through external library libgsm
82ced5a9 391@item GSM_MS @tab E @tab E
3f33271a 392 @tab supported through external library libgsm
16d81b27 393@item id RoQ DPCM @tab X @tab X
d698c5d3 394 @tab Used in Quake III, Jedi Knight 2, other computer games.
16d81b27
DB
395@item Intel Music Coder @tab @tab X
396@item Interplay MVE DPCM @tab @tab X
d698c5d3 397 @tab Used in various Interplay computer games.
055dc116
SG
398@item ISS IMA ADPCM @tab @tab X
399 @tab Used in FunCom games.
16d81b27 400@item MAXIS EA ADPCM @tab @tab X
d698c5d3 401 @tab Used in Sim City 3000.
16d81b27
DB
402@item Microsoft ADPCM @tab X @tab X
403@item MLP/TrueHD @tab @tab X
d698c5d3 404 @tab Used in DVD-Audio and Blu-Ray discs.
16d81b27 405@item Monkey's Audio @tab @tab X
d698c5d3 406 @tab Only versions 3.97-3.99 are supported.
9ff0c388
DB
407@item MPEG audio layer 3 @tab E @tab IX
408 @tab encoding supported through external library LAME
16d81b27
DB
409@item MPEG audio layer 2 @tab IX @tab IX
410@item MS IMA ADPCM @tab X @tab X
411@item Musepack @tab @tab X
d698c5d3 412 @tab SV7 and SV8 are supported.
755ba886 413@item Nellymoser ASAO @tab X @tab X
73b458e3 414@item QCELP / PureVoice @tab @tab X
16d81b27 415@item Qdesign QDM2 @tab @tab X
d698c5d3 416 @tab There are still some distortions.
16d81b27
DB
417@item QT IMA ADPCM @tab X @tab X
418@item RA144 @tab @tab X
d698c5d3 419 @tab Real 14400 bit/s codec
16d81b27 420@item RA288 @tab @tab X
d698c5d3 421 @tab Real 28800 bit/s codec
575a5bf2 422@item RADnet @tab IX @tab IX
a692130f 423 @tab Real low bitrate AC-3 codec
16d81b27 424@item Real COOK @tab @tab X
d698c5d3 425 @tab All versions except 5.1 are supported.
bac4c85c 426@item Shorten @tab @tab X
16d81b27 427@item Sierra Online DPCM @tab @tab X
d698c5d3 428 @tab Used in Sierra Online game audio files.
bac4c85c 429@item Smacker audio @tab @tab X
16d81b27 430@item SMJPEG IMA ADPCM @tab @tab X
d698c5d3 431 @tab Used in certain Loki game ports.
e6fa1ca5
JR
432@item Sonic @tab X @tab X
433 @tab experimental codec
434@item Sonic lossless @tab X @tab X
435 @tab experimental codec
82ced5a9 436@item Speex @tab @tab E
360f980b 437 @tab supported through external library libspeex
16d81b27 438@item THP ADPCM @tab @tab X
d698c5d3 439 @tab Used on the Nintendo GameCube.
16d81b27
DB
440@item True Audio (TTA) @tab @tab X
441@item Vorbis @tab X @tab X
bac4c85c 442@item WavPack @tab @tab X
16d81b27 443@item Westwood Studios IMA ADPCM @tab @tab X
d698c5d3 444 @tab Used in Westwood Studios games like Command and Conquer.
bac4c85c 445@item WMA v1/v2 @tab X @tab X
16d81b27 446@item Xan DPCM @tab @tab X
d698c5d3 447 @tab Used in Origin's Wing Commander IV AVI files.
d0e1cd3d
DB
448@end multitable
449
450@code{X} means that encoding (resp. decoding) is supported.
451
82ced5a9
DB
452@code{E} means that support is provided through an external library.
453
d0e1cd3d
DB
454@code{I} means that an integer-only version is available, too (ensures high
455performance on systems without hardware floating point support).
456
bd3151f2
DB
457@section Subtitle Formats
458
485ec4f1 459@multitable @columnfractions .4 .1 .1 .1 .1 .1
9afc2917 460@item Name @tab Muxing @tab Demuxing @tab Encoding @tab Decoding
bd3151f2 461@item ASS/SSA @tab X @tab X
9afc2917
DB
462@item DVB @tab X @tab X @tab X @tab X
463@item DVD @tab X @tab X @tab X @tab X
464@item XSUB @tab @tab @tab @tab X
bd3151f2
DB
465@end multitable
466
467@code{X} means that the feature is supported.
468
d0e1cd3d
DB
469@chapter Platform Specific information
470
471@section BSD
472
473BSD make will not build FFmpeg, you need to install and use GNU Make
474(@file{gmake}).
475
476@section Windows
477
46a845d0 478To get help and instructions for building FFmpeg under Windows, check out
d0e1cd3d 479the FFmpeg Windows Help Forum at
ab5ce4ae 480@url{http://ffmpeg.arrozcru.org/}.
d0e1cd3d
DB
481
482@subsection Native Windows compilation
483
c1989552 484FFmpeg can be built to run natively on Windows using the MinGW tools. Install
126cadc7
RP
485the latest versions of MSYS and MinGW from @url{http://www.mingw.org/}.
486You can find detailed installation
d0e1cd3d
DB
487instructions in the download section and the FAQ.
488
126cadc7
RP
489FFmpeg does not build out-of-the-box with the packages the automated MinGW
490installer provides. It also requires coreutils to be installed and many other
491packages updated to the latest version. The minimum version for some packages
492are listed below:
493
494@itemize
495@item bash 3.1
496@item msys-make 3.81-2 (note: not mingw32-make)
2014b51c 497@item w32api 3.13
126cadc7
RP
498@item mingw-runtime 3.15
499@end itemize
500
0f898714
DB
501You will also need to pass @code{-fno-common} to the compiler to work around
502a GCC bug (see @url{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37216}).
503
c1989552 504Within the MSYS shell, configure and make with:
d0e1cd3d 505
c1989552 506@example
0f898714 507./configure --enable-memalign-hack --extra-cflags=-fno-common
c1989552
RP
508make
509make install
510@end example
d0e1cd3d 511
c1989552
RP
512This will install @file{ffmpeg.exe} along with many other development files
513to @file{/usr/local}. You may specify another install path using the
514@code{--prefix} option in @file{configure}.
d0e1cd3d 515
c1989552 516Notes:
d0e1cd3d 517
c1989552 518@itemize
d0e1cd3d 519
c1989552
RP
520@item In order to compile vhooks, you must have a POSIX-compliant libdl in
521your MinGW system. Get dlfcn-win32 from
522@url{http://code.google.com/p/dlfcn-win32}.
d0e1cd3d 523
c1989552
RP
524@item In order to compile FFplay, you must have the MinGW development library
525of SDL. Get it from @url{http://www.libsdl.org}.
526Edit the @file{bin/sdl-config} script so that it points to the correct prefix
527where SDL was installed. Verify that @file{sdl-config} can be launched from
528the MSYS command line.
d0e1cd3d 529
d0e1cd3d 530@item By using @code{./configure --enable-shared} when configuring FFmpeg,
c1989552 531you can build libavutil, libavcodec and libavformat as DLLs.
d0e1cd3d
DB
532
533@end itemize
534
c1989552 535@subsection Microsoft Visual C++ compatibility
d0e1cd3d 536
c1989552
RP
537As stated in the FAQ, FFmpeg will not compile under MSVC++. However, if you
538want to use the libav* libraries in your own applications, you can still
539compile those applications using MSVC++. But the libav* libraries you link
540to @emph{must} be built with MinGW. However, you will not be able to debug
541inside the libav* libraries, since MSVC++ does not recognize the debug
542symbols generated by GCC.
543We strongly recommend you to move over from MSVC++ to MinGW tools.
d0e1cd3d 544
c1989552
RP
545This description of how to use the FFmpeg libraries with MSVC++ is based on
546Microsoft Visual C++ 2005 Express Edition. If you have a different version,
547you might have to modify the procedures slightly.
d0e1cd3d 548
c1989552 549@subsubsection Using static libraries
d0e1cd3d 550
c1989552 551Assuming you have just built and installed FFmpeg in @file{/usr/local}.
d0e1cd3d
DB
552
553@enumerate
554
555@item Create a new console application ("File / New / Project") and then
556select "Win32 Console Application". On the appropriate page of the
557Application Wizard, uncheck the "Precompiled headers" option.
558
559@item Write the source code for your application, or, for testing, just
560copy the code from an existing sample application into the source file
c1989552
RP
561that MSVC++ has already created for you. For example, you can copy
562@file{output_example.c} from the FFmpeg distribution.
d0e1cd3d
DB
563
564@item Open the "Project / Properties" dialog box. In the "Configuration"
565combo box, select "All Configurations" so that the changes you make will
566affect both debug and release builds. In the tree view on the left hand
567side, select "C/C++ / General", then edit the "Additional Include
c1989552
RP
568Directories" setting to contain the path where the FFmpeg includes were
569installed (i.e. @file{c:\msys\1.0\local\include}).
f010d377
RP
570Do not add MinGW's include directory here, or the include files will
571conflict with MSVC's.
c1989552
RP
572
573@item Still in the "Project / Properties" dialog box, select
574"Linker / General" from the tree view and edit the
575"Additional Library Directories" setting to contain the @file{lib}
576directory where FFmpeg was installed (i.e. @file{c:\msys\1.0\local\lib}),
577the directory where MinGW libs are installed (i.e. @file{c:\mingw\lib}),
578and the directory where MinGW's GCC libs are installed
579(i.e. @file{C:\mingw\lib\gcc\mingw32\4.2.1-sjlj}). Then select
580"Linker / Input" from the tree view, and add the files @file{libavformat.a},
581@file{libavcodec.a}, @file{libavutil.a}, @file{libmingwex.a},
582@file{libgcc.a}, and any other libraries you used (i.e. @file{libz.a})
583to the end of "Additional Dependencies".
d0e1cd3d
DB
584
585@item Now, select "C/C++ / Code Generation" from the tree view. Select
586"Debug" in the "Configuration" combo box. Make sure that "Runtime
587Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
588the "Configuration" combo box and make sure that "Runtime Library" is
589set to "Multi-threaded DLL".
590
c1989552
RP
591@item Click "OK" to close the "Project / Properties" dialog box.
592
593@item MSVC++ lacks some C99 header files that are fundamental for FFmpeg.
594Get msinttypes from @url{http://code.google.com/p/msinttypes/downloads/list}
595and install it in MSVC++'s include directory
596(i.e. @file{C:\Program Files\Microsoft Visual Studio 8\VC\include}).
597
598@item MSVC++ also does not understand the @code{inline} keyword used by
599FFmpeg, so you must add this line before @code{#include}ing libav*:
600@example
601#define inline _inline
602@end example
603
c1989552
RP
604@item Build your application, everything should work.
605
606@end enumerate
607
608@subsubsection Using shared libraries
609
610This is how to create DLL and LIB files that are compatible with MSVC++:
611
612@enumerate
613
614@item Add a call to @file{vcvars32.bat} (which sets up the environment
615variables for the Visual C++ tools) as the first line of @file{msys.bat}.
616The standard location for @file{vcvars32.bat} is
617@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
618and the standard location for @file{msys.bat} is @file{C:\msys\1.0\msys.bat}.
619If this corresponds to your setup, add the following line as the first line
620of @file{msys.bat}:
621
622@example
623call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"
624@end example
625
626Alternatively, you may start the @file{Visual Studio 2005 Command Prompt},
627and run @file{c:\msys\1.0\msys.bat} from there.
628
629@item Within the MSYS shell, run @code{lib.exe}. If you get a help message
630from @file{Microsoft (R) Library Manager}, this means your environment
631variables are set up correctly, the @file{Microsoft (R) Library Manager}
632is on the path and will be used by FFmpeg to create
633MSVC++-compatible import libraries.
634
635@item Build FFmpeg with
636
637@example
638./configure --enable-shared --enable-memalign-hack
639make
640make install
641@end example
642
643Your install path (@file{/usr/local/} by default) should now have the
644necessary DLL and LIB files under the @file{bin} directory.
d0e1cd3d
DB
645
646@end enumerate
647
c1989552
RP
648To use those files with MSVC++, do the same as you would do with
649the static libraries, as described above. But in Step 4,
650you should only need to add the directory where the LIB files are installed
651(i.e. @file{c:\msys\usr\local\bin}). This is not a typo, the LIB files are
652installed in the @file{bin} directory. And instead of adding @file{libxx.a}
653files, you should add @file{avcodec.lib}, @file{avformat.lib}, and
654@file{avutil.lib}. There should be no need for @file{libmingwex.a},
655@file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
656statically linked into the DLLs. The @file{bin} directory contains a bunch
657of DLL files, but the ones that are actually used to run your application
658are the ones with a major version number in their filenames
659(i.e. @file{avcodec-51.dll}).
660
d0e1cd3d
DB
661@subsection Cross compilation for Windows with Linux
662
663You must use the MinGW cross compilation tools available at
664@url{http://www.mingw.org/}.
665
666Then configure FFmpeg with the following options:
667@example
668./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
669@end example
670(you can change the cross-prefix according to the prefix chosen for the
671MinGW tools).
672
673Then you can easily test FFmpeg with Wine
674(@url{http://www.winehq.com/}).
675
676@subsection Compilation under Cygwin
677
8484503e
VP
678The main issue with the 1.5.x Cygwin versions is that newlib, its C library,
679does not contain llrint(). You need to upgrade to the unstable 1.7.x versions,
680or leverage the implementation in MinGW (as explained below).
d0e1cd3d
DB
681
682Just install your Cygwin with all the "Base" packages, plus the
683following "Devel" ones:
684@example
f496ab12 685binutils, gcc-core, make, subversion, mingw-runtime, diffutils
d0e1cd3d
DB
686@end example
687
666a1b34
VP
688The experimental gcc4 package is still buggy, hence please
689use the official gcc 3.4.4 or a 4.2.x compiled from source by yourself.
690
8484503e
VP
691Install the current binutils-20080624-2 as they work fine (the old
692binutils-20060709-1 proved buggy on shared builds).
d0e1cd3d 693
29c3d42b
VP
694Then create a small library that just contains llrint():
695
696@example
697ar x /usr/lib/mingw/libmingwex.a llrint.o
698ar cq /usr/local/lib/libllrint.a llrint.o
699@end example
700
d0e1cd3d
DB
701Then run
702
703@example
29c3d42b 704./configure --enable-static --disable-shared --extra-ldflags='-L /usr/local/lib' --extra-libs='-l llrint'
d0e1cd3d
DB
705@end example
706
707to make a static build or
708
709@example
29c3d42b 710./configure --enable-shared --disable-static --extra-ldflags='-L /usr/local/lib' --extra-libs='-l llrint'
d0e1cd3d
DB
711@end example
712
713to build shared libraries.
714
715If you want to build FFmpeg with additional libraries, download Cygwin
5dd9799d
VP
716"Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
717@example
718libogg-devel, libvorbis-devel
719@end example
720
721These library packages are only available from Cygwin Ports
be8497b0 722(@url{http://sourceware.org/cygwinports/}) :
5dd9799d
VP
723
724@example
725yasm, libSDL-devel, libdirac-devel, libfaac-devel, libfaad-devel, libgsm-devel,
726libmp3lame-devel, libschroedinger1.0-devel, speex-devel, libtheora-devel,
727libxvidcore-devel
728@end example
729
730The recommendation for libnut and x264 is to build them from source by
731yourself, as they evolve too quickly for Cygwin Ports to be up to date.
d0e1cd3d 732
cdf51395
VP
733Cygwin 1.7.x has IPv6 support. You can add IPv6 to Cygwin 1.5.x by means
734of the @code{libgetaddrinfo-devel} package, available at Cygwin Ports.
735
d0e1cd3d
DB
736@subsection Crosscompilation for Windows under Cygwin
737
738With Cygwin you can create Windows binaries that do not need the cygwin1.dll.
739
740Just install your Cygwin as explained before, plus these additional
741"Devel" packages:
742@example
743gcc-mingw-core, mingw-runtime, mingw-zlib
744@end example
745
746and add some special flags to your configure invocation.
747
748For a static build run
749@example
750./configure --target-os=mingw32 --enable-memalign-hack --enable-static --disable-shared --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
751@end example
752
753and for a build with shared libraries
754@example
755./configure --target-os=mingw32 --enable-memalign-hack --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
756@end example
757
758@section BeOS
759
5f757b85 760BeOS support is broken in mysterious ways.
d0e1cd3d 761
25b92a79
DY
762@section OS/2
763
764For information about compiling FFmpeg on OS/2 see
765@url{http://www.edm2.com/index.php/FFmpeg}.
766
d0e1cd3d
DB
767@chapter Developers Guide
768
769@section API
770@itemize @bullet
771@item libavcodec is the library containing the codecs (both encoding and
772decoding). Look at @file{libavcodec/apiexample.c} to see how to use it.
773
774@item libavformat is the library containing the file format handling (mux and
775demux code for several formats). Look at @file{ffplay.c} to use it in a
776player. See @file{output_example.c} to use it to generate audio or video
777streams.
778
779@end itemize
780
781@section Integrating libavcodec or libavformat in your program
782
783You can integrate all the source code of the libraries to link them
784statically to avoid any version problem. All you need is to provide a
785'config.mak' and a 'config.h' in the parent directory. See the defines
786generated by ./configure to understand what is needed.
787
788You can use libavcodec or libavformat in your commercial program, but
789@emph{any patch you make must be published}. The best way to proceed is
790to send your patches to the FFmpeg mailing list.
791
792@node Coding Rules
793@section Coding Rules
794
795FFmpeg is programmed in the ISO C90 language with a few additional
796features from ISO C99, namely:
797@itemize @bullet
798@item
799the @samp{inline} keyword;
800@item
801@samp{//} comments;
802@item
803designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
804@item
805compound literals (@samp{x = (struct s) @{ 17, 23 @};})
806@end itemize
807
808These features are supported by all compilers we care about, so we will not
809accept patches to remove their use unless they absolutely do not impair
810clarity and performance.
811
812All code must compile with GCC 2.95 and GCC 3.3. Currently, FFmpeg also
813compiles with several other compilers, such as the Compaq ccc compiler
814or Sun Studio 9, and we would like to keep it that way unless it would
815be exceedingly involved. To ensure compatibility, please do not use any
816additional C99 features or GCC extensions. Especially watch out for:
817@itemize @bullet
818@item
819mixing statements and declarations;
820@item
821@samp{long long} (use @samp{int64_t} instead);
822@item
823@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
824@item
825GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
826@end itemize
827
828Indent size is 4.
829The presentation is the one specified by 'indent -i4 -kr -nut'.
830The TAB character is forbidden outside of Makefiles as is any
831form of trailing whitespace. Commits containing either will be
832rejected by the Subversion repository.
833
834The main priority in FFmpeg is simplicity and small code size in order to
835minimize the bug count.
836
837Comments: Use the JavaDoc/Doxygen
838format (see examples below) so that code documentation
839can be generated automatically. All nontrivial functions should have a comment
840above them explaining what the function does, even if it is just one sentence.
841All structures and their member variables should be documented, too.
842@example
843/**
844 * @@file mpeg.c
845 * MPEG codec.
846 * @@author ...
847 */
848
849/**
850 * Summary sentence.
851 * more text ...
852 * ...
853 */
854typedef struct Foobar@{
855 int var1; /**< var1 description */
856 int var2; ///< var2 description
857 /** var3 description */
858 int var3;
859@} Foobar;
860
861/**
862 * Summary sentence.
863 * more text ...
864 * ...
865 * @@param my_parameter description of my_parameter
866 * @@return return value description
867 */
868int myfunc(int my_parameter)
869...
870@end example
871
872fprintf and printf are forbidden in libavformat and libavcodec,
873please use av_log() instead.
874
875Casts should be used only when necessary. Unneeded parentheses
876should also be avoided if they don't make the code easier to understand.
877
878@section Development Policy
879
880@enumerate
881@item
882 Contributions should be licensed under the LGPL 2.1, including an
883 "or any later version" clause, or the MIT license. GPL 2 including
884 an "or any later version" clause is also acceptable, but LGPL is
885 preferred.
886@item
887 You must not commit code which breaks FFmpeg! (Meaning unfinished but
888 enabled code which breaks compilation or compiles but does not work or
889 breaks the regression tests)
890 You can commit unfinished stuff (for testing etc), but it must be disabled
891 (#ifdef etc) by default so it does not interfere with other developers'
892 work.
893@item
894 You do not have to over-test things. If it works for you, and you think it
895 should work for others, then commit. If your code has problems
896 (portability, triggers compiler bugs, unusual environment etc) they will be
897 reported and eventually fixed.
898@item
899 Do not commit unrelated changes together, split them into self-contained
900 pieces. Also do not forget that if part B depends on part A, but A does not
901 depend on B, then A can and should be committed first and separate from B.
902 Keeping changes well split into self-contained parts makes reviewing and
903 understanding them on the commit log mailing list easier. This also helps
904 in case of debugging later on.
905 Also if you have doubts about splitting or not splitting, do not hesitate to
906 ask/discuss it on the developer mailing list.
907@item
908 Do not change behavior of the program (renaming options etc) without
909 first discussing it on the ffmpeg-devel mailing list. Do not remove
910 functionality from the code. Just improve!
911
912 Note: Redundant code can be removed.
913@item
914 Do not commit changes to the build system (Makefiles, configure script)
915 which change behavior, defaults etc, without asking first. The same
916 applies to compiler warning fixes, trivial looking fixes and to code
917 maintained by other developers. We usually have a reason for doing things
918 the way we do. Send your changes as patches to the ffmpeg-devel mailing
919 list, and if the code maintainers say OK, you may commit. This does not
920 apply to files you wrote and/or maintain.
921@item
922 We refuse source indentation and other cosmetic changes if they are mixed
923 with functional changes, such commits will be rejected and removed. Every
924 developer has his own indentation style, you should not change it. Of course
925 if you (re)write something, you can use your own style, even though we would
926 prefer if the indentation throughout FFmpeg was consistent (Many projects
927 force a given indentation style - we do not.). If you really need to make
928 indentation changes (try to avoid this), separate them strictly from real
929 changes.
930
931 NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code,
932 then either do NOT change the indentation of the inner part within (do not
933 move it to the right)! or do so in a separate commit
934@item
935 Always fill out the commit log message. Describe in a few lines what you
936 changed and why. You can refer to mailing list postings if you fix a
937 particular bug. Comments such as "fixed!" or "Changed it." are unacceptable.
938@item
939 If you apply a patch by someone else, include the name and email address in
940 the log message. Since the ffmpeg-cvslog mailing list is publicly
941 archived you should add some SPAM protection to the email address. Send an
942 answer to ffmpeg-devel (or wherever you got the patch from) saying that
943 you applied the patch.
944@item
945 When applying patches that have been discussed (at length) on the mailing
946 list, reference the thread in the log message.
947@item
948 Do NOT commit to code actively maintained by others without permission.
949 Send a patch to ffmpeg-devel instead. If no one answers within a reasonable
950 timeframe (12h for build failures and security fixes, 3 days small changes,
951 1 week for big patches) then commit your patch if you think it is OK.
952 Also note, the maintainer can simply ask for more time to review!
953@item
954 Subscribe to the ffmpeg-cvslog mailing list. The diffs of all commits
955 are sent there and reviewed by all the other developers. Bugs and possible
956 improvements or general questions regarding commits are discussed there. We
957 expect you to react if problems with your code are uncovered.
958@item
959 Update the documentation if you change behavior or add features. If you are
960 unsure how best to do this, send a patch to ffmpeg-devel, the documentation
961 maintainer(s) will review and commit your stuff.
962@item
963 Try to keep important discussions and requests (also) on the public
964 developer mailing list, so that all developers can benefit from them.
965@item
966 Never write to unallocated memory, never write over the end of arrays,
967 always check values read from some untrusted source before using them
968 as array index or other risky things.
969@item
970 Remember to check if you need to bump versions for the specific libav
971 parts (libavutil, libavcodec, libavformat) you are changing. You need
b98052d5 972 to change the version integer.
d0e1cd3d
DB
973 Incrementing the first component means no backward compatibility to
974 previous versions (e.g. removal of a function from the public API).
975 Incrementing the second component means backward compatible change
b98052d5
PR
976 (e.g. addition of a function to the public API or extension of an
977 existing data structure).
d0e1cd3d
DB
978 Incrementing the third component means a noteworthy binary compatible
979 change (e.g. encoder bug fix that matters for the decoder).
980@item
53407b64 981 Compiler warnings indicate potential bugs or code with bad style. If a type of
9908c1a8
DB
982 warning always points to correct and clean code, that warning should
983 be disabled, not the code changed.
984 Thus the remaining warnings can either be bugs or correct code.
beaa4a91 985 If it is a bug, the bug has to be fixed. If it is not, the code should
9908c1a8
DB
986 be changed to not generate a warning unless that causes a slowdown
987 or obfuscates the code.
d0e1cd3d
DB
988@item
989 If you add a new file, give it a proper license header. Do not copy and
990 paste it from a random place, use an existing file as template.
991@end enumerate
992
993We think our rules are not too hard. If you have comments, contact us.
994
995Note, these rules are mostly borrowed from the MPlayer project.
996
997@section Submitting patches
998
999First, (@pxref{Coding Rules}) above if you did not yet.
1000
1001When you submit your patch, try to send a unified diff (diff '-up'
1002option). We cannot read other diffs :-)
1003
1004Also please do not submit a patch which contains several unrelated changes.
1005Split it into separate, self-contained pieces. This does not mean splitting
1006file by file. Instead, make the patch as small as possible while still
1007keeping it as a logical unit that contains an individual change, even
1008if it spans multiple files. This makes reviewing your patches much easier
1009for us and greatly increases your chances of getting your patch applied.
1010
1011Run the regression tests before submitting a patch so that you can
1012verify that there are no big problems.
1013
1014Patches should be posted as base64 encoded attachments (or any other
1015encoding which ensures that the patch will not be trashed during
1016transmission) to the ffmpeg-devel mailing list, see
1017@url{http://lists.mplayerhq.hu/mailman/listinfo/ffmpeg-devel}
1018
1019It also helps quite a bit if you tell us what the patch does (for example
1020'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant
1021and has no lrint()')
1022
1023Also please if you send several patches, send each patch as a separate mail,
1024do not attach several unrelated patches to the same mail.
1025
28ce1839
RP
1026@section New codecs or formats checklist
1027
1028@enumerate
1029@item
1030 Did you use av_cold for codec initialization and close functions?
1031@item
1032 Did you add a long_name under NULL_IF_CONFIG_SMALL to the AVCodec or
1033 AVInputFormat/AVOutputFormat struct?
1034@item
1035 Did you bump the minor version number in @file{avcodec.h} or
1036 @file{avformat.h}?
1037@item
1038 Did you register it in @file{allcodecs.c} or @file{allformats.c}?
1039@item
1040 Did you add the CodecID to @file{avcodec.h}?
1041@item
1042 If it has a fourcc, did you add it to @file{libavformat/riff.c},
1043 even if it is only a decoder?
1044@item
1045 Did you add a rule to compile the appropriate files in the Makefile?
1046 Remember to do this even if you're just adding a format to a file that is
1047 already being compiled by some other rule, like a raw demuxer.
1048@item
1049 Did you add an entry to the table of supported formats or codecs in the
1050 documentation?
1051@item
1052 Did you add an entry in the Changelog?
1053@item
1054 If it depends on a parser or a library, did you add that dependency in
1055 configure?
1056@item
1057 Did you "svn add" the appropriate files before commiting?
1058@end enumerate
1059
d0e1cd3d
DB
1060@section patch submission checklist
1061
1062@enumerate
1063@item
1064 Do the regression tests pass with the patch applied?
1065@item
2cdba8bf
DB
1066 Does @code{make checkheaders} pass with the patch applied?
1067@item
d0e1cd3d
DB
1068 Is the patch a unified diff?
1069@item
1070 Is the patch against latest FFmpeg SVN?
1071@item
1072 Are you subscribed to ffmpeg-dev?
1073 (the list is subscribers only due to spam)
1074@item
1075 Have you checked that the changes are minimal, so that the same cannot be
1076 achieved with a smaller patch and/or simpler final code?
1077@item
1078 If the change is to speed critical code, did you benchmark it?
1079@item
1080 If you did any benchmarks, did you provide them in the mail?
1081@item
1082 Have you checked that the patch does not introduce buffer overflows or
1083 other security issues?
1084@item
63d247ea
DB
1085 Did you test your decoder or demuxer against damaged data? If no, see
1086 tools/trasher and the noise bitstream filter. Your decoder or demuxer
1087 should not crash or end in a (near) infinite loop when fed damaged data.
b885e0db 1088@item
d0e1cd3d
DB
1089 Is the patch created from the root of the source tree, so it can be
1090 applied with @code{patch -p0}?
1091@item
1092 Does the patch not mix functional and cosmetic changes?
1093@item
1094 Did you add tabs or trailing whitespace to the code? Both are forbidden.
1095@item
1096 Is the patch attached to the email you send?
1097@item
1098 Is the mime type of the patch correct? It should be text/x-diff or
1099 text/x-patch or at least text/plain and not application/octet-stream.
1100@item
1101 If the patch fixes a bug, did you provide a verbose analysis of the bug?
1102@item
1103 If the patch fixes a bug, did you provide enough information, including
1104 a sample, so the bug can be reproduced and the fix can be verified?
1105 Note please do not attach samples >100k to mails but rather provide a
0fa5f24c 1106 URL, you can upload to ftp://upload.ffmpeg.org
d0e1cd3d
DB
1107@item
1108 Did you provide a verbose summary about what the patch does change?
1109@item
1110 Did you provide a verbose explanation why it changes things like it does?
1111@item
1112 Did you provide a verbose summary of the user visible advantages and
1113 disadvantages if the patch is applied?
1114@item
1115 Did you provide an example so we can verify the new feature added by the
1116 patch easily?
1117@item
1118 If you added a new file, did you insert a license header? It should be
1119 taken from FFmpeg, not randomly copied and pasted from somewhere else.
1120@item
1121 You should maintain alphabetical order in alphabetically ordered lists as
1122 long as doing so does not break API/ABI compatibility.
1123@item
1124 Lines with similar content should be aligned vertically when doing so
1125 improves readability.
1126@item
1127 Did you provide a suggestion for a clear commit log message?
1128@end enumerate
1129
1130@section Patch review process
1131
1132All patches posted to ffmpeg-devel will be reviewed, unless they contain a
1133clear note that the patch is not for SVN.
1134Reviews and comments will be posted as replies to the patch on the
1135mailing list. The patch submitter then has to take care of every comment,
1136that can be by resubmitting a changed patch or by discussion. Resubmitted
1137patches will themselves be reviewed like any other patch. If at some point
1138a patch passes review with no comments then it is approved, that can for
1139simple and small patches happen immediately while large patches will generally
1140have to be changed and reviewed many times before they are approved.
1141After a patch is approved it will be committed to the repository.
1142
1143We will review all submitted patches, but sometimes we are quite busy so
1144especially for large patches this can take several weeks.
1145
1146When resubmitting patches, please do not make any significant changes
1147not related to the comments received during review. Such patches will
1148be rejected. Instead, submit significant changes or new features as
1149separate patches.
1150
1151@section Regression tests
1152
1153Before submitting a patch (or committing to the repository), you should at least
1154test that you did not break anything.
1155
1156The regression tests build a synthetic video stream and a synthetic
1157audio stream. These are then encoded and decoded with all codecs or
1158formats. The CRC (or MD5) of each generated file is recorded in a
1159result file. A 'diff' is launched to compare the reference results and
1160the result file.
1161
1162The regression tests then go on to test the FFserver code with a
1163limited set of streams. It is important that this step runs correctly
1164as well.
1165
1166Run 'make test' to test all the codecs and formats.
1167
1168Run 'make fulltest' to test all the codecs, formats and FFserver.
1169
1170[Of course, some patches may change the results of the regression tests. In
1171this case, the reference results of the regression tests shall be modified
1172accordingly].
1173
1174@bye