@section AMR
-AMR comes in two different flavors, WB and NB. FFmpeg can make use of the
-AMR WB (floating-point mode) and the AMR NB (floating-point mode) reference
-decoders and encoders.
+AMR comes in two different flavors, wideband and narrowband. FFmpeg can make
+use of the AMR wideband (floating-point mode) and the AMR narrowband
+(floating-point mode) reference decoders and encoders.
Go to @url{http://www.penguin.cz/~utx/amr} and follow the instructions for
installing the libraries. Then pass @code{--enable-libamr-nb} and/or
@code{--enable-libamr-wb} to configure to enable the libraries.
+Note that libamr is copyrighted without any sort of license grant. This means
+that you can use it if you legally obtained it but you are not allowed to
+redistribute it in any way. @strong{Any FFmpeg binaries with libamr support
+you create are non-free and unredistributable!}
+
@chapter Supported File Formats and Codecs
@item AVI@tab X @tab X
@item WAV@tab X @tab X
@item Macromedia Flash@tab X @tab X
+@item AVM2 (Flash 9) @tab X @tab X
@tab Only embedded audio is decoded.
@item FLV @tab X @tab X
@tab Macromedia Flash video files
@item Matroska @tab X @tab X
@item Electronic Arts Multimedia @tab @tab X
@tab Used in various EA games; files have extensions like WVE and UV2.
+@item MAXIS EA XA @tab @tab X
+@tab Used in Sim City 3000; file extension .xa.
@item Nullsoft Video (NSV) format @tab @tab X
@item ADTS AAC audio @tab X @tab X
@item Creative VOC @tab X @tab X @tab Created for the Sound Blaster Pro.
@item CRYO APC @tab @tab X
@tab Audio format used in some games by CRYO Interactive Entertainment.
@item Monkey's Audio @tab @tab X
+@item SIFF @tab @tab X
+@tab Audio and video format used in some games by Beam Software
+@item LMLM4 @tab @tab X
+@tab Used by Linux Media Labs MPEG-4 PCI boards
+@item PVA @tab @tab X
+@tab Used by TechnoTrend DVB PCI boards
+@item MSN TCP Webcam @tab @tab X
+@tab Used by MSN Messenger Webcam streams.
+@item RL2 @tab @tab X
+@tab Audio and video format used in some games by Entertainment Software Partners
+@item IFF @tab @tab X
+@tab Interchange File Format
+@item BFI @tab @tab X
+@tab Brute Force & Ignorance, used in Flash Traffic: City of Angels
@end multitable
@code{X} means that encoding (resp. decoding) is supported.
@item TIFF @tab X @tab X @tab YUV, JPEG and some extension is not supported yet.
@item SGI @tab X @tab X @tab SGI RGB image format
@item PTX @tab @tab X @tab V.Flash PTX format
+@item RAS @tab @tab X @tab Sun Rasterfile
+@item PCX @tab @tab X @tab PC Paintbrush
@end multitable
@code{X} means that encoding (resp. decoding) is supported.
@item Cin Video @tab @tab X @tab Codec used in Delphine Software games.
@item Tiertex Seq Video @tab @tab X @tab Codec used in DOS CDROM FlashBack game.
@item DXA Video @tab @tab X @tab Codec originally used in Feeble Files game.
-@item AVID DNxHD @tab @tab X @tab aka SMPTE VC3
+@item AVID DNxHD @tab X @tab X @tab aka SMPTE VC3
@item C93 Video @tab @tab X @tab Codec used in Cyberia game.
@item THP @tab @tab X @tab Used on the Nintendo GameCube.
@item Bethsoft VID @tab @tab X @tab Used in some games from Bethesda Softworks.
@item Renderware TXD @tab @tab X @tab Texture dictionaries used by the Renderware Engine.
+@item AMV @tab @tab X @tab Used in Chinese MP3 players.
+@item Mimic @tab @tab X @tab Used in MSN Messenger Webcam streams.
@end multitable
@code{X} means that encoding (resp. decoding) is supported.
@multitable @columnfractions .4 .1 .1 .1 .7
@item Supported Codec @tab Encoding @tab Decoding @tab Comments
@item MPEG audio layer 2 @tab IX @tab IX
-@item MPEG audio layer 1/3 @tab IX @tab IX
+@item MPEG audio layer 1/3 @tab X @tab IX
@tab MP3 encoding is supported through the external library LAME.
@item AC3 @tab IX @tab IX
@tab liba52 is used internally for decoding.
@item AMV IMA ADPCM @tab @tab X
@tab Used in AMV files
@item MS IMA ADPCM @tab X @tab X
-@item QT IMA ADPCM @tab @tab X
+@item QT IMA ADPCM @tab X @tab X
@item 4X IMA ADPCM @tab @tab X
@item G.726 ADPCM @tab X @tab X
@item Duck DK3 IMA ADPCM @tab @tab X
@tab Used in Sega Dreamcast games.
@item Electronic Arts ADPCM @tab @tab X
@tab Used in various EA titles.
+@item MAXIS EA ADPCM @tab @tab X
+@tab Used in Sim City 3000.
@item Creative ADPCM @tab @tab X
@tab 16 -> 4, 8 -> 4, 8 -> 3, 8 -> 2
@item THP ADPCM @tab @tab X
@tab Codec used in Delphine Software games.
@item Intel Music Coder @tab @tab X
@item Musepack @tab @tab X
-@tab Only SV7 is supported
+@tab SV7 and SV8 are supported
@item DT$ Coherent Audio @tab @tab X
@item ATRAC 3 @tab @tab X
@item Monkey's Audio @tab @tab X @tab Only versions 3.97-3.99 are supported
+@item Nellymoser ASAO @tab @tab X
+@item 8SVX Audio @tab @tab X
@end multitable
@code{X} means that encoding (resp. decoding) is supported.
@section Windows
-To get help and instructions for using FFmpeg under Windows, check out
+To get help and instructions for building FFmpeg under Windows, check out
the FFmpeg Windows Help Forum at
@url{http://arrozcru.no-ip.org/ffmpeg/}.
@subsection Native Windows compilation
-@itemize
-@item Install the current versions of MSYS and MinGW from
-@url{http://www.mingw.org/}. You can find detailed installation
+FFmpeg can be built to run natively on Windows using the MinGW tools. Install
+the current versions of MSYS and MinGW from @url{http://www.mingw.org/}. Also
+install the coreutils package, and update to the latest MSYS make (note: not
+mingw32-make). You can find detailed installation
instructions in the download section and the FAQ.
-NOTE: Use at least bash 3.1. Older versions are known to be failing on the
-configure script.
-
-@item If you want to test the FFplay, also download
-the MinGW development library of SDL 1.2.x
-(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
-@url{http://www.libsdl.org}. Unpack it in a temporary directory, and
-unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
-directory. Edit the @file{sdl-config} script so that it gives the
-correct SDL directory when invoked.
+Within the MSYS shell, configure and make with:
-@item If you want to use vhooks, you must have a POSIX compliant libdl in your
-MinGW system. Get dlfcn-win32 from @url{http://code.google.com/p/dlfcn-win32}.
-
-@item Extract the current version of FFmpeg.
+@example
+./configure --enable-memalign-hack
+make
+make install
+@end example
-@item Start the MSYS shell (file @file{msys.bat}).
+This will install @file{ffmpeg.exe} along with many other development files
+to @file{/usr/local}. You may specify another install path using the
+@code{--prefix} option in @file{configure}.
-@item Change to the FFmpeg directory and follow
- the instructions of how to compile FFmpeg (file
-@file{INSTALL}). Usually, launching @file{./configure} and @file{make}
-suffices. If you have problems using SDL, verify that
-@file{sdl-config} can be launched from the MSYS command line.
+Notes:
-@item You can install FFmpeg in @file{Program Files/FFmpeg} by typing
-@file{make install}. Do not forget to copy @file{SDL.dll} to the place
-you launch @file{ffplay} from.
+@itemize
-@end itemize
+@item Use at least bash 3.1. Older versions are known to fail on the
+configure script.
-Notes:
-@itemize
+@item In order to compile vhooks, you must have a POSIX-compliant libdl in
+your MinGW system. Get dlfcn-win32 from
+@url{http://code.google.com/p/dlfcn-win32}.
-@item The target @file{make wininstaller} can be used to create a
-Nullsoft based Windows installer for FFmpeg and FFplay. @file{SDL.dll}
-must be copied to the FFmpeg directory in order to build the
-installer.
+@item In order to compile FFplay, you must have the MinGW development library
+of SDL. Get it from @url{http://www.libsdl.org}.
+Edit the @file{bin/sdl-config} script so that it points to the correct prefix
+where SDL was installed. Verify that @file{sdl-config} can be launched from
+the MSYS command line.
@item By using @code{./configure --enable-shared} when configuring FFmpeg,
-you can build @file{avcodec.dll} and @file{avformat.dll}. With
-@code{make install} you install the FFmpeg DLLs and the associated
-headers in @file{Program Files/FFmpeg}.
-
-@item Visual C++ compatibility: If you used @code{./configure --enable-shared}
-when configuring FFmpeg, FFmpeg tries to use the Microsoft Visual
-C++ @code{lib} tool to build @code{avcodec.lib} and
-@code{avformat.lib}. With these libraries you can link your Visual C++
-code directly with the FFmpeg DLLs (see below).
+you can build libavutil, libavcodec and libavformat as DLLs.
@end itemize
-@subsection Visual C++ compatibility
+@subsection Microsoft Visual C++ compatibility
-FFmpeg will not compile under Visual C++ -- and it has too many
-dependencies on the GCC compiler to make a port viable. However,
-if you want to use the FFmpeg libraries in your own applications,
-you can still compile those applications using Visual C++. An
-important restriction to this is that you have to use the
-dynamically linked versions of the FFmpeg libraries (i.e. the
-DLLs), and you have to make sure that Visual-C++-compatible
-import libraries are created during the FFmpeg build process.
+As stated in the FAQ, FFmpeg will not compile under MSVC++. However, if you
+want to use the libav* libraries in your own applications, you can still
+compile those applications using MSVC++. But the libav* libraries you link
+to @emph{must} be built with MinGW. However, you will not be able to debug
+inside the libav* libraries, since MSVC++ does not recognize the debug
+symbols generated by GCC.
+We strongly recommend you to move over from MSVC++ to MinGW tools.
-This description of how to use the FFmpeg libraries with Visual C++ is
-based on Visual C++ 2005 Express Edition Beta 2. If you have a different
-version, you might have to modify the procedures slightly.
+This description of how to use the FFmpeg libraries with MSVC++ is based on
+Microsoft Visual C++ 2005 Express Edition. If you have a different version,
+you might have to modify the procedures slightly.
-Here are the step-by-step instructions for building the FFmpeg libraries
-so they can be used with Visual C++:
-
-@enumerate
+@subsubsection Using static libraries
-@item Install Visual C++ (if you have not done so already).
-
-@item Install MinGW and MSYS as described above.
-
-@item Add a call to @file{vcvars32.bat} (which sets up the environment
-variables for the Visual C++ tools) as the first line of
-@file{msys.bat}. The standard location for @file{vcvars32.bat} is
-@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
-and the standard location for @file{msys.bat} is
-@file{C:\msys\1.0\msys.bat}. If this corresponds to your setup, add the
-following line as the first line of @file{msys.bat}:
-
-@code{call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"}
-
-@item Start the MSYS shell (file @file{msys.bat}) and type @code{link.exe}.
-If you get a help message with the command line options of @code{link.exe},
-this means your environment variables are set up correctly, the
-Microsoft linker is on the path and will be used by FFmpeg to
-create Visual-C++-compatible import libraries.
-
-@item Extract the current version of FFmpeg and change to the FFmpeg directory.
-
-@item Type the command
-@code{./configure --enable-shared --disable-static --enable-memalign-hack}
-to configure and, if that did not produce any errors,
-type @code{make} to build FFmpeg.
-
-@item The subdirectories @file{libavformat}, @file{libavcodec}, and
-@file{libavutil} should now contain the files @file{avformat.dll},
-@file{avformat.lib}, @file{avcodec.dll}, @file{avcodec.lib},
-@file{avutil.dll}, and @file{avutil.lib}, respectively. Copy the three
-DLLs to your System32 directory (typically @file{C:\Windows\System32}).
-
-@end enumerate
-
-And here is how to use these libraries with Visual C++:
+Assuming you have just built and installed FFmpeg in @file{/usr/local}.
@enumerate
@item Write the source code for your application, or, for testing, just
copy the code from an existing sample application into the source file
-that Visual C++ has already created for you. (Note that your source
-filehas to have a @code{.cpp} extension; otherwise, Visual C++ will not
-compile the FFmpeg headers correctly because in C mode, it does not
-recognize the @code{inline} keyword.) For example, you can copy
-@file{output_example.c} from the FFmpeg distribution (but you will
-have to make minor modifications so the code will compile under
-C++, see below).
+that MSVC++ has already created for you. For example, you can copy
+@file{output_example.c} from the FFmpeg distribution.
@item Open the "Project / Properties" dialog box. In the "Configuration"
combo box, select "All Configurations" so that the changes you make will
affect both debug and release builds. In the tree view on the left hand
side, select "C/C++ / General", then edit the "Additional Include
-Directories" setting to contain the complete paths to the
-@file{libavformat}, @file{libavcodec}, and @file{libavutil}
-subdirectories of your FFmpeg directory. Note that the directories have
-to be separated using semicolons. Now select "Linker / General" from the
-tree view and edit the "Additional Library Directories" setting to
-contain the same three directories.
-
-@item Still in the "Project / Properties" dialog box, select "Linker / Input"
-from the tree view, then add the files @file{avformat.lib},
-@file{avcodec.lib}, and @file{avutil.lib} to the end of the "Additional
-Dependencies". Note that the names of the libraries have to be separated
-using spaces.
+Directories" setting to contain the path where the FFmpeg includes were
+installed (i.e. @file{c:\msys\1.0\local\include}).
+
+@item Still in the "Project / Properties" dialog box, select
+"Linker / General" from the tree view and edit the
+"Additional Library Directories" setting to contain the @file{lib}
+directory where FFmpeg was installed (i.e. @file{c:\msys\1.0\local\lib}),
+the directory where MinGW libs are installed (i.e. @file{c:\mingw\lib}),
+and the directory where MinGW's GCC libs are installed
+(i.e. @file{C:\mingw\lib\gcc\mingw32\4.2.1-sjlj}). Then select
+"Linker / Input" from the tree view, and add the files @file{libavformat.a},
+@file{libavcodec.a}, @file{libavutil.a}, @file{libmingwex.a},
+@file{libgcc.a}, and any other libraries you used (i.e. @file{libz.a})
+to the end of "Additional Dependencies".
@item Now, select "C/C++ / Code Generation" from the tree view. Select
"Debug" in the "Configuration" combo box. Make sure that "Runtime
the "Configuration" combo box and make sure that "Runtime Library" is
set to "Multi-threaded DLL".
-@item Click "OK" to close the "Project / Properties" dialog box and build
-the application. Hopefully, it should compile and run cleanly. If you
-used @file{output_example.c} as your sample application, you will get a
-few compiler errors, but they are easy to fix. The first type of error
-occurs because Visual C++ does not allow an @code{int} to be converted to
-an @code{enum} without a cast. To solve the problem, insert the required
-casts (this error occurs once for a @code{CodecID} and once for a
-@code{CodecType}). The second type of error occurs because C++ requires
-the return value of @code{malloc} to be cast to the exact type of the
-pointer it is being assigned to. Visual C++ will complain that, for
-example, @code{(void *)} is being assigned to @code{(uint8_t *)} without
-an explicit cast. So insert an explicit cast in these places to silence
-the compiler. The third type of error occurs because the @code{snprintf}
-library function is called @code{_snprintf} under Visual C++. So just
-add an underscore to fix the problem. With these changes,
-@file{output_example.c} should compile under Visual C++, and the
-resulting executable should produce valid video files.
+@item Click "OK" to close the "Project / Properties" dialog box.
+
+@item MSVC++ lacks some C99 header files that are fundamental for FFmpeg.
+Get msinttypes from @url{http://code.google.com/p/msinttypes/downloads/list}
+and install it in MSVC++'s include directory
+(i.e. @file{C:\Program Files\Microsoft Visual Studio 8\VC\include}).
+
+@item MSVC++ also does not understand the @code{inline} keyword used by
+FFmpeg, so you must add this line before @code{#include}ing libav*:
+@example
+#define inline _inline
+@end example
+
+@item If you used @file{output_example.c} as your sample application,
+you will have to edit the @code{#include}s to point to the files which
+are under the @file{ffmpeg} directory (i.e. @code{<ffmpeg/avformat.h>}).
+
+@item Build your application, everything should work.
@end enumerate
+@subsubsection Using shared libraries
+
+This is how to create DLL and LIB files that are compatible with MSVC++:
+
+@enumerate
+
+@item Add a call to @file{vcvars32.bat} (which sets up the environment
+variables for the Visual C++ tools) as the first line of @file{msys.bat}.
+The standard location for @file{vcvars32.bat} is
+@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
+and the standard location for @file{msys.bat} is @file{C:\msys\1.0\msys.bat}.
+If this corresponds to your setup, add the following line as the first line
+of @file{msys.bat}:
+
+@example
+call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"
+@end example
+
+Alternatively, you may start the @file{Visual Studio 2005 Command Prompt},
+and run @file{c:\msys\1.0\msys.bat} from there.
+
+@item Within the MSYS shell, run @code{lib.exe}. If you get a help message
+from @file{Microsoft (R) Library Manager}, this means your environment
+variables are set up correctly, the @file{Microsoft (R) Library Manager}
+is on the path and will be used by FFmpeg to create
+MSVC++-compatible import libraries.
+
+@item Build FFmpeg with
+
+@example
+./configure --enable-shared --enable-memalign-hack
+make
+make install
+@end example
+
+Your install path (@file{/usr/local/} by default) should now have the
+necessary DLL and LIB files under the @file{bin} directory.
+
+@end enumerate
+
+To use those files with MSVC++, do the same as you would do with
+the static libraries, as described above. But in Step 4,
+you should only need to add the directory where the LIB files are installed
+(i.e. @file{c:\msys\usr\local\bin}). This is not a typo, the LIB files are
+installed in the @file{bin} directory. And instead of adding @file{libxx.a}
+files, you should add @file{avcodec.lib}, @file{avformat.lib}, and
+@file{avutil.lib}. There should be no need for @file{libmingwex.a},
+@file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
+statically linked into the DLLs. The @file{bin} directory contains a bunch
+of DLL files, but the ones that are actually used to run your application
+are the ones with a major version number in their filenames
+(i.e. @file{avcodec-51.dll}).
+
@subsection Cross compilation for Windows with Linux
You must use the MinGW cross compilation tools available at
@subsection Compilation under Cygwin
-Cygwin works very much like Unix.
+The main issue with Cygwin is that newlib, its C library, does not
+contain llrint(). However, it is possible to leverage the
+implementation in MinGW.
Just install your Cygwin with all the "Base" packages, plus the
following "Devel" ones:
@example
-binutils, gcc-core, make, subversion
+binutils, gcc-core, make, subversion, mingw-runtime
@end example
Do not install binutils-20060709-1 (they are buggy on shared builds);
use binutils-20050610-1 instead.
+Then create a small library that just contains llrint():
+
+@example
+ar x /usr/lib/mingw/libmingwex.a llrint.o
+ar cq /usr/local/lib/libllrint.a llrint.o
+@end example
+
Then run
@example
-./configure --enable-static --disable-shared
+./configure --enable-static --disable-shared --extra-ldflags='-L /usr/local/lib' --extra-libs='-l llrint'
@end example
to make a static build or
@example
-./configure --enable-shared --disable-static
+./configure --enable-shared --disable-static --extra-ldflags='-L /usr/local/lib' --extra-libs='-l llrint'
@end example
to build shared libraries.
BeOS support is broken in mysterious ways.
+@section OS/2
+
+For information about compiling FFmpeg on OS/2 see
+@url{http://www.edm2.com/index.php/FFmpeg}.
+
@chapter Developers Guide
@section API
If you add a new codec, remember to update the changelog, add it to
the supported codecs table in the documentation and bump the second
component of the @file{libavcodec} version number appropriately. If
- it has a fourcc, add it to @file{libavformat/avienc.c}, even if it
+ it has a fourcc, add it to @file{libavformat/riff.c}, even if it
is only a decoder.
@item
- Do not change code to hide warnings without ensuring that the underlying
- logic is correct and thus the warning was inappropriate.
+ Compiler warnings indicate potential bugs or code with bad style. If a type of
+ warning always points to correct and clean code, that warning should
+ be disabled, not the code changed.
+ Thus the remaining warnings can either be bugs or correct code.
+ If it is a bug, the bug has to be fixed. If it is not, the code should
+ be changed to not generate a warning unless that causes a slowdown
+ or obfuscates the code.
@item
If you add a new file, give it a proper license header. Do not copy and
paste it from a random place, use an existing file as template.
@item
Have you checked that the patch does not introduce buffer overflows or
other security issues?
+@item
+ If you add a new demuxer or decoder, have you checked that it does not
+ crash with damaged input (see tools/trasher)?
@item
Is the patch created from the root of the source tree, so it can be
applied with @code{patch -p0}?
improves readability.
@item
Did you provide a suggestion for a clear commit log message?
+@item
+ Did you test your decoder or demuxer against damaged data? If no, see
+ tools/trasher and the noise bitstream filter. Your decoder or demuxer
+ should not crash or end in a (near) infinite loop when fed damaged data.
@end enumerate
@section Patch review process
projects / ffmpeg / blobdiff