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