12
@chapter external libraries
12
@chapter External libraries
14
14
Libav can be hooked up with a number of external libraries to add support
15
15
for more formats. None of them are used by default, their use has to be
16
16
explicitly requested by passing the appropriate flags to @file{./configure}.
20
Libav can make use of the OpenCORE libraries for AMR-NB
21
decoding/encoding and AMR-WB decoding.
23
Go to @url{http://sourceforge.net/projects/opencore-amr/} and follow the instructions for
24
installing the libraries. Then pass @code{--enable-libopencore-amrnb} and/or
25
@code{--enable-libopencore-amrwb} to configure to enable the libraries.
27
Note that OpenCORE is under the Apache License 2.0 (see
28
@url{http://www.apache.org/licenses/LICENSE-2.0} for details), which is
18
@section OpenCORE and VisualOn libraries
20
Spun off Google Android sources, OpenCore and VisualOn libraries provide
21
encoders for a number of audio codecs.
24
OpenCORE and VisualOn libraries are under the Apache License 2.0
25
(see @url{http://www.apache.org/licenses/LICENSE-2.0} for details), which is
29
26
incompatible with the LGPL version 2.1 and GPL version 2. You have to
30
27
upgrade Libav's license to LGPL version 3 (or if you have enabled
31
28
GPL components, GPL version 3) to use it.
31
@subsection OpenCORE AMR
33
Libav can make use of the OpenCORE libraries for AMR-NB
34
decoding/encoding and AMR-WB decoding.
36
Go to @url{http://sourceforge.net/projects/opencore-amr/} and follow the
37
instructions for installing the libraries.
38
Then pass @code{--enable-libopencore-amrnb} and/or
39
@code{--enable-libopencore-amrwb} to configure to enable them.
41
@subsection VisualOn AAC encoder library
43
Libav can make use of the VisualOn AACenc library for AAC encoding.
45
Go to @url{http://sourceforge.net/projects/opencore-amr/} and follow the
46
instructions for installing the library.
47
Then pass @code{--enable-libvo-aacenc} to configure to enable it.
49
@subsection VisualOn AMR-WB encoder library
51
Libav can make use of the VisualOn AMR-WBenc library for AMR-WB encoding.
53
Go to @url{http://sourceforge.net/projects/opencore-amr/} and follow the
54
instructions for installing the library.
55
Then pass @code{--enable-libvo-amrwbenc} to configure to enable it.
59
Libav can make use of the LAME library for MP3 encoding.
61
Go to @url{http://lame.sourceforge.net/} and follow the
62
instructions for installing the library.
63
Then pass @code{--enable-libmp3lame} to configure to enable it.
67
Libav can make use of the libvpx library for VP8 encoding.
69
Go to @url{http://www.webmproject.org/} and follow the instructions for
70
installing the library. Then pass @code{--enable-libvpx} to configure to
75
Libav can make use of the x264 library for H.264 encoding.
77
Go to @url{http://www.videolan.org/developers/x264.html} and follow the
78
instructions for installing the library. Then pass @code{--enable-libx264} to
79
configure to enable it.
82
x264 is under the GNU Public License Version 2 or later
83
(see @url{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html} for
84
details), you must upgrade Libav's license to GPL in order to use it.
34
89
@chapter Supported File Formats and Codecs
748
824
@code{X} means that input/output is supported.
751
@chapter Platform Specific information
755
Using a cross-compiler is preferred for various reasons.
759
For information about compiling Libav on OS/2 see
760
@url{http://www.edm2.com/index.php/FFmpeg}.
764
Some parts of Libav cannot be built with version 2.15 of the GNU
765
assembler which is still provided by a few AMD64 distributions. To
766
make sure your compiler really uses the required version of gas
767
after a binutils upgrade, run:
770
$(gcc -print-prog-name=as) --version
773
If not, then you should install a different compiler that has no
774
hard-coded path to gas. In the worst case pass @code{--disable-asm}
779
BSD make will not build Libav, you need to install and use GNU Make
782
@subsection (Open)Solaris
784
GNU Make is required to build Libav, so you have to invoke (@file{gmake}),
785
standard Solaris Make will not work. When building with a non-c99 front-end
786
(gcc, generic suncc) add either @code{--extra-libs=/usr/lib/values-xpg6.o}
787
or @code{--extra-libs=/usr/lib/64/values-xpg6.o} to the configure options
788
since the libc is not c99-compliant by default. The probes performed by
789
configure may raise an exception leading to the death of configure itself
790
due to a bug in the system shell. Simply invoke a different shell such as
791
bash directly to work around this:
797
@subsection Darwin (MacOS X, iPhone)
799
MacOS X on PowerPC or ARM (iPhone) requires a preprocessor from
800
@url{http://github.com/yuvi/gas-preprocessor} to build the optimized
801
assembler functions. Just download the Perl script and put it somewhere
802
in your PATH, Libav's configure will pick it up automatically.
806
@subsection Native Windows compilation
808
Libav can be built to run natively on Windows using the MinGW tools. Install
809
the latest versions of MSYS and MinGW from @url{http://www.mingw.org/}.
810
You can find detailed installation
811
instructions in the download section and the FAQ.
813
Libav does not build out-of-the-box with the packages the automated MinGW
814
installer provides. It also requires coreutils to be installed and many other
815
packages updated to the latest version. The minimum version for some packages
820
@item msys-make 3.81-2 (note: not mingw32-make)
822
@item mingw-runtime 3.15
825
Libav automatically passes @code{-fno-common} to the compiler to work around
826
a GCC bug (see @url{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37216}).
832
@item Building natively using MSYS can be sped up by disabling implicit rules
833
in the Makefile by calling @code{make -r} instead of plain @code{make}. This
834
speed up is close to non-existent for normal one-off builds and is only
835
noticeable when running make for a second time (for example in
836
@code{make install}).
838
@item In order to compile FFplay, you must have the MinGW development library
839
of SDL. Get it from @url{http://www.libsdl.org}.
840
Edit the @file{bin/sdl-config} script so that it points to the correct prefix
841
where SDL was installed. Verify that @file{sdl-config} can be launched from
842
the MSYS command line.
844
@item By using @code{./configure --enable-shared} when configuring Libav,
845
you can build libavutil, libavcodec and libavformat as DLLs.
849
@subsection Microsoft Visual C++ compatibility
851
As stated in the FAQ, Libav will not compile under MSVC++. However, if you
852
want to use the libav* libraries in your own applications, you can still
853
compile those applications using MSVC++. But the libav* libraries you link
854
to @emph{must} be built with MinGW. However, you will not be able to debug
855
inside the libav* libraries, since MSVC++ does not recognize the debug
856
symbols generated by GCC.
857
We strongly recommend you to move over from MSVC++ to MinGW tools.
859
This description of how to use the Libav libraries with MSVC++ is based on
860
Microsoft Visual C++ 2005 Express Edition. If you have a different version,
861
you might have to modify the procedures slightly.
863
@subsubsection Using static libraries
865
Assuming you have just built and installed Libav in @file{/usr/local}.
869
@item Create a new console application ("File / New / Project") and then
870
select "Win32 Console Application". On the appropriate page of the
871
Application Wizard, uncheck the "Precompiled headers" option.
873
@item Write the source code for your application, or, for testing, just
874
copy the code from an existing sample application into the source file
875
that MSVC++ has already created for you. For example, you can copy
876
@file{libavformat/output-example.c} from the Libav distribution.
878
@item Open the "Project / Properties" dialog box. In the "Configuration"
879
combo box, select "All Configurations" so that the changes you make will
880
affect both debug and release builds. In the tree view on the left hand
881
side, select "C/C++ / General", then edit the "Additional Include
882
Directories" setting to contain the path where the Libav includes were
883
installed (i.e. @file{c:\msys\1.0\local\include}).
884
Do not add MinGW's include directory here, or the include files will
885
conflict with MSVC's.
887
@item Still in the "Project / Properties" dialog box, select
888
"Linker / General" from the tree view and edit the
889
"Additional Library Directories" setting to contain the @file{lib}
890
directory where Libav was installed (i.e. @file{c:\msys\1.0\local\lib}),
891
the directory where MinGW libs are installed (i.e. @file{c:\mingw\lib}),
892
and the directory where MinGW's GCC libs are installed
893
(i.e. @file{C:\mingw\lib\gcc\mingw32\4.2.1-sjlj}). Then select
894
"Linker / Input" from the tree view, and add the files @file{libavformat.a},
895
@file{libavcodec.a}, @file{libavutil.a}, @file{libmingwex.a},
896
@file{libgcc.a}, and any other libraries you used (i.e. @file{libz.a})
897
to the end of "Additional Dependencies".
899
@item Now, select "C/C++ / Code Generation" from the tree view. Select
900
"Debug" in the "Configuration" combo box. Make sure that "Runtime
901
Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
902
the "Configuration" combo box and make sure that "Runtime Library" is
903
set to "Multi-threaded DLL".
905
@item Click "OK" to close the "Project / Properties" dialog box.
907
@item MSVC++ lacks some C99 header files that are fundamental for Libav.
908
Get msinttypes from @url{http://code.google.com/p/msinttypes/downloads/list}
909
and install it in MSVC++'s include directory
910
(i.e. @file{C:\Program Files\Microsoft Visual Studio 8\VC\include}).
912
@item MSVC++ also does not understand the @code{inline} keyword used by
913
Libav, so you must add this line before @code{#include}ing libav*:
915
#define inline _inline
918
@item Build your application, everything should work.
922
@subsubsection Using shared libraries
924
This is how to create DLL and LIB files that are compatible with MSVC++:
928
@item Add a call to @file{vcvars32.bat} (which sets up the environment
929
variables for the Visual C++ tools) as the first line of @file{msys.bat}.
930
The standard location for @file{vcvars32.bat} is
931
@file{C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat},
932
and the standard location for @file{msys.bat} is @file{C:\msys\1.0\msys.bat}.
933
If this corresponds to your setup, add the following line as the first line
937
call "C:\Program Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat"
940
Alternatively, you may start the @file{Visual Studio 2005 Command Prompt},
941
and run @file{c:\msys\1.0\msys.bat} from there.
943
@item Within the MSYS shell, run @code{lib.exe}. If you get a help message
944
from @file{Microsoft (R) Library Manager}, this means your environment
945
variables are set up correctly, the @file{Microsoft (R) Library Manager}
946
is on the path and will be used by Libav to create
947
MSVC++-compatible import libraries.
949
@item Build Libav with
952
./configure --enable-shared --enable-memalign-hack
957
Your install path (@file{/usr/local/} by default) should now have the
958
necessary DLL and LIB files under the @file{bin} directory.
962
To use those files with MSVC++, do the same as you would do with
963
the static libraries, as described above. But in Step 4,
964
you should only need to add the directory where the LIB files are installed
965
(i.e. @file{c:\msys\usr\local\bin}). This is not a typo, the LIB files are
966
installed in the @file{bin} directory. And instead of adding the static
967
libraries (@file{libxxx.a} files) you should add the MSVC import libraries
968
(@file{avcodec.lib}, @file{avformat.lib}, and
969
@file{avutil.lib}). Note that you should not use the GCC import
970
libraries (@file{libxxx.dll.a} files), as these will give you undefined
971
reference errors. There should be no need for @file{libmingwex.a},
972
@file{libgcc.a}, and @file{wsock32.lib}, nor any other external library
973
statically linked into the DLLs. The @file{bin} directory contains a bunch
974
of DLL files, but the ones that are actually used to run your application
975
are the ones with a major version number in their filenames
976
(i.e. @file{avcodec-51.dll}).
978
Libav headers do not declare global data for Windows DLLs through the usual
979
dllexport/dllimport interface. Such data will be exported properly while
980
building, but to use them in your MSVC++ code you will have to edit the
981
appropriate headers and mark the data as dllimport. For example, in
982
libavutil/pixdesc.h you should have:
984
extern __declspec(dllimport) const AVPixFmtDescriptor av_pix_fmt_descriptors[];
987
Note that using import libraries created by dlltool requires
988
the linker optimization option to be set to
989
"References: Keep Unreferenced Data (/OPT:NOREF)", otherwise
990
the resulting binaries will fail during runtime. This isn't
991
required when using import libraries generated by lib.exe.
993
@subsection Cross compilation for Windows with Linux
995
You must use the MinGW cross compilation tools available at
996
@url{http://www.mingw.org/}.
998
Then configure Libav with the following options:
1000
./configure --target-os=mingw32 --cross-prefix=i386-mingw32msvc-
1002
(you can change the cross-prefix according to the prefix chosen for the
1005
Then you can easily test Libav with Wine
1006
(@url{http://www.winehq.com/}).
1008
@subsection Compilation under Cygwin
1010
Please use Cygwin 1.7.x as the obsolete 1.5.x Cygwin versions lack
1011
llrint() in its C library.
1013
Install your Cygwin with all the "Base" packages, plus the
1014
following "Devel" ones:
1016
binutils, gcc4-core, make, git, mingw-runtime, texi2html
1019
And the following "Utils" one:
1027
./configure --enable-static --disable-shared
1030
to make a static build.
1032
The current @code{gcc4-core} package is buggy and needs this flag to build
1036
./configure --enable-shared --disable-static --extra-cflags=-fno-reorder-functions
1039
If you want to build Libav with additional libraries, download Cygwin
1040
"Devel" packages for Ogg and Vorbis from any Cygwin packages repository:
1042
libogg-devel, libvorbis-devel
1045
These library packages are only available from Cygwin Ports
1046
(@url{http://sourceware.org/cygwinports/}) :
1049
yasm, libSDL-devel, libdirac-devel, libfaac-devel, libgsm-devel,
1050
libmp3lame-devel, libschroedinger1.0-devel, speex-devel, libtheora-devel,
1054
The recommendation for libnut and x264 is to build them from source by
1055
yourself, as they evolve too quickly for Cygwin Ports to be up to date.
1057
Cygwin 1.7.x has IPv6 support. You can add IPv6 to Cygwin 1.5.x by means
1058
of the @code{libgetaddrinfo-devel} package, available at Cygwin Ports.
1060
@subsection Crosscompilation for Windows under Cygwin
1062
With Cygwin you can create Windows binaries that do not need the cygwin1.dll.
1064
Just install your Cygwin as explained before, plus these additional
1067
gcc-mingw-core, mingw-runtime, mingw-zlib
1070
and add some special flags to your configure invocation.
1072
For a static build run
1074
./configure --target-os=mingw32 --enable-memalign-hack --enable-static --disable-shared --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin
1077
and for a build with shared libraries
1079
./configure --target-os=mingw32 --enable-memalign-hack --enable-shared --disable-static --extra-cflags=-mno-cygwin --extra-libs=-mno-cygwin