ffmpeg-doc.texi

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++:

@enumerate

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

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

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

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

@item Now, select "C/C++ / Code Generation" from the tree view. Select
"Debug" in the "Configuration" combo box. Make sure that "Runtime
Library" is set to "Multi-threaded Debug DLL". Then, select "Release" in
the "Configuration" combo box and make sure that "Runtime Library" is
set to "Multi-threaded DLL".

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

@end enumerate

@subsection Cross compilation for Windows with Linux

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

Then configure FFmpeg with the following options:
@example
./configure --enable-mingw32 --cross-prefix=i386-mingw32msvc-
@end example
(you can change the cross-prefix according to the prefix chosen for the
MinGW tools).

Then you can easily test FFmpeg with Wine
(@url{http://www.winehq.com/}).

@subsection Compilation under Cygwin

Cygwin works very much like Unix.

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

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

Then run

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

to make a static build or

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

to build shared libraries.

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

@subsection Crosscompilation for Windows under Cygwin

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

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

and add some special flags to your configure invocation.

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

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

@section Mac OS X

@section BeOS

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

Old stuff:

François Revol - revol at free dot fr - April 2002

The configure script should guess the configuration itself,
however I still didn't test building on the net_server version of BeOS.

FFserver is broken (needs poll() implementation).

There are still issues with errno codes, which are negative in BeOS, and
that FFmpeg negates when returning. This ends up turning errors into
valid results, then crashes.
(To be fixed)

@chapter Developers Guide

@section API
@itemize @bullet
@item libavcodec is the library containing the codecs (both encoding and
decoding). Look at @file{libavcodec/apiexample.c} to see how to use it.

@item libavformat is the library containing the file format handling (mux and
demux code for several formats). Look at @file{ffplay.c} to use it in a
player. See @file{output_example.c} to use it to generate audio or video
streams.

@end itemize

@section Integrating libavcodec or libavformat in your program

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

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

@node Coding Rules
@section Coding Rules

FFmpeg is programmed in the ISO C90 language with a few additional
features from ISO C99, namely:
@itemize @bullet
@item
the @samp{inline} keyword;
@item
@samp{//} comments;
@item
designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
@item
compound literals (@samp{x = (struct s) @{ 17, 23 @};})
@end itemize

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

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

Indent size is 4.
The presentation is the one specified by 'indent -i4 -kr -nut'.
The TAB character is forbidden outside of Makefiles as is any
form of trailing whitespace. Commits containing either will be
rejected by the Subversion repository.

Main priority in FFmpeg is simplicity and small code size (=less
bugs).

Comments: Use the JavaDoc/Doxygen
format (see examples below) so that code documentation
can be generated automatically. All nontrivial functions should have a comment
above them explaining what the function does, even if it's just one sentence.
All structures and their member variables should be documented, too.
@example
/**
 * @@file mpeg.c
 * MPEG codec.
 * @@author ...
 */

/**
 * Summary sentence.
 * more text ...
 * ...
 */
typedef struct Foobar@{
    int var1; /**< var1 description */
    int var2; ///< var2 description
    /** var3 description */
    int var3;
@} Foobar;

/**
 * Summary sentence.
 * more text ...
 * ...
 * @@param my_parameter description of my_parameter
 * @@return return value description
 */
int myfunc(int my_parameter)
...
@end example

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

@section Development Policy

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

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

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

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

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

@section Submitting patches

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

When you submit your patch, try to send a unified diff (diff '-up'
option). I cannot read other diffs :-)

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

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

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

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

We reply to all submitted patches and either apply or reject with some
explanation why, but sometimes we are quite busy so it can take a week or two.

@section Regression tests

Before submitting a patch (or committing to the repository), you should at least
test that you did not break anything.

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

The regression tests then go on to test the FFserver code with a
limited set of streams. It is important that this step runs correctly
as well.

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

Run 'make fulltest' to test all the codecs, formats and FFserver.

[Of course, some patches may change the results of the regression tests. In
this case, the reference results of the regression tests shall be modified
accordingly].

@bye