This text is concerned with the development of FFmpeg itself. Information +on using the FFmpeg libraries in other programs can be found elsewhere, e.g. in: +
If you modify FFmpeg code for your own use case, you are highly encouraged to +submit your changes back to us, using this document as a guide. There are +both pragmatic and ideological reasons to do so: +
For more detailed legal information about the use of FFmpeg in +external programs read the LICENSE file in the source tree and +consult https://ffmpeg.org/legal.html. +
+ +All proposed code changes should be submitted for review to +the development mailing list, as +described in more detail in the Submitting patches chapter. The code +should comply with the Development Policy and follow the Coding Rules. +The developer making the commit and the author are responsible for their changes +and should try to fix issues their commit causes. +
+ +There are the following guidelines regarding the indentation in files: +
+The presentation is one inspired by ’indent -i4 -kr -nut’. +
+The main priority in FFmpeg is simplicity and small code size in order to +minimize the bug count. +
+ +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 is just one sentence. +All structures and their member variables should be documented, too. +
+Avoid Qt-style and similar Doxygen syntax with ! in it, i.e. replace
+//! with /// and similar. Also @ syntax should be employed
+for markup commands, i.e. use @param and not \param.
+
/**
+ * @file
+ * 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)
+...
+FFmpeg is programmed in the ISO C90 language with a few additional +features from ISO C99, namely: +
+These features are supported by all compilers we care about, so we will not +accept patches to remove their use unless they absolutely do not impair +clarity and performance. +
+All code must compile with recent versions of GCC and a number of other +currently supported compilers. To ensure compatibility, please do not use +additional C99 features or GCC extensions. Especially watch out for: +
+All names should be composed with underscores (_), not CamelCase. For example, +‘avfilter_get_video_buffer’ is an acceptable function name and +‘AVFilterGetVideo’ is not. The exception from this are type names, like +for example structs and enums; they should always be in CamelCase. +
+There are the following conventions for naming variables and functions: +
+static, no prefix
+is required.
+
+ff_ prefix should be used,
+e.g. ‘ff_w64_demuxer’.
+
+avpriv_ as prefix, for example,
+‘avpriv_report_missing_feature’.
+
+av_ (avformat_ for libavformat,
+avcodec_ for libavcodec, swr_ for libswresample, etc).
+Check the existing code and choose names accordingly.
+Note that some symbols without these prefixes are also exported for
+retro-compatibility reasons. These exceptions are declared in the
+lib<name>/lib<name>.v files.
+Furthermore, name space reserved for the system should not be invaded.
+Identifiers ending in _t are reserved by
+POSIX.
+Also avoid names starting with __ or _ followed by an uppercase
+letter as they are reserved by the C standard. Names starting with _
+are reserved at the file level and may not be used for externally visible
+symbols. If in doubt, just avoid names starting with _ altogether.
+
In order to configure Vim to follow FFmpeg formatting conventions, paste +the following snippet into your .vimrc: +
" indentation rules for FFmpeg: 4 spaces, no tabs +set expandtab +set shiftwidth=4 +set softtabstop=4 +set cindent +set cinoptions=(0 +" Allow tabs in Makefiles. +autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8 +" Trailing whitespace and tabs are forbidden, so highlight them. +highlight ForbiddenWhitespace ctermbg=red guibg=red +match ForbiddenWhitespace /\s\+$\|\t/ +" Do not highlight spaces at the end of line while typing on that line. +autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@<!$/ +
For Emacs, add these roughly equivalent lines to your .emacs.d/init.el: +
(c-add-style "ffmpeg"
+ '("k&r"
+ (c-basic-offset . 4)
+ (indent-tabs-mode . nil)
+ (show-trailing-whitespace . t)
+ (c-offsets-alist
+ (statement-cont . (c-lineup-assignments +)))
+ )
+ )
+(setq c-default-style "ffmpeg")
+Contributions should be licensed under the +LGPL 2.1, +including an "or any later version" clause, or, if you prefer +a gift-style license, the +ISC or +MIT license. +GPL 2 including +an "or any later version" clause is also acceptable, but LGPL is +preferred. +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. +
+ +This means unfinished code which is enabled and breaks compilation, +or compiles but does not work/breaks the regression tests. Code which +is unfinished but disabled may be permitted under-circumstances, like +missing samples or an implementation with a small subset of features. +Always check the mailing list for any reviewers with issues and test +FATE before you push. +
+ +The commit message should have a short first line in the form of +a ‘topic: short description’ as a header, separated by a newline +from the body consisting of an explanation of why the change is necessary. +If the commit fixes a known bug on the bug tracker, the commit message +should include its bug ID. Referring to the issue on the bug tracker does +not exempt you from writing an excerpt of the bug in the commit message. +
+ +If it works for you, others, and passes FATE then it should be OK to commit +it, provided it fits the other committing criteria. You should not worry about +over-testing things. If your code has problems (portability, triggers +compiler bugs, unusual environment etc) they will be reported and eventually +fixed. +
+ +They should be split them into self-contained pieces. Also do not forget +that if part B depends on part A, but A does not depend on B, then A can +and should be committed first and separate from B. Keeping changes well +split into self-contained parts makes reviewing and understanding them on +the commit log mailing list easier. This also helps in case of debugging +later on. +Also if you have doubts about splitting or not splitting, do not hesitate to +ask/discuss it on the developer mailing list. +
+ +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. +
+ +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 do not.). 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 (do not +move it to the right)! or do so in a separate commit +
+ +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. +Recommended format: +
+area changed: Short 1 line description + +details describing what and why and giving references. +
Make sure the author of the commit is set correctly. (see git commit –author) +If you apply a patch, send an +answer to ffmpeg-devel (or wherever you got the patch from) saying that +you applied the patch. +
+ +When applying patches that have been discussed (at length) on the mailing +list, reference the thread in the log message. +
+ +Do NOT commit to code actively maintained by others without permission. +Send a patch to ffmpeg-devel. If no one answers within a reasonable +time-frame (12h for build failures and security fixes, 3 days small changes, +1 week for big patches) then commit your patch if you think it is OK. +Also note, the maintainer can simply ask for more time to review! +
+ +Do not change behavior of the programs (renaming options etc) or public +API or ABI without first discussing it on the ffmpeg-devel mailing list. +Do not remove widely used functionality or features (redundant code can be removed). +
+ +Depending on the change, you may need to change the version integer. +Incrementing the first component means no backward compatibility to +previous versions (e.g. removal of a function from the public API). +Incrementing the second component means backward compatible change +(e.g. addition of a function to the public API or extension of an +existing data structure). +Incrementing the third component means a noteworthy binary compatible +change (e.g. encoder bug fix that matters for the decoder). The third +component always starts at 100 to distinguish FFmpeg from Libav. +
+ +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. +
+ +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. +
+ +It is important to be subscribed to the +ffmpeg-devel +mailing list. Almost any non-trivial patch is to be sent there for review. +Other developers may have comments about your contribution. We expect you see +those comments, and to improve it if requested. (N.B. Experienced committers +have other channels, and may sometimes skip review for trivial fixes.) Also, +discussion here about bug fixes and FFmpeg improvements by other developers may +be helpful information for you. Finally, by being a list subscriber, your +contribution will be posted immediately to the list, without the moderation +hold which messages from non-subscribers experience. +
+However, it is more important to the project that we receive your patch than +that you be subscribed to the ffmpeg-devel list. If you have a patch, and don’t +want to subscribe and discuss the patch, then please do send it to the list +anyway. +
+ +Diffs of all commits are sent to the +ffmpeg-cvslog +mailing list. Some developers read this list to review all code base changes +from all sources. Subscribing to this list is not mandatory. +
+ +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. +
+ +Try to keep important discussions and requests (also) on the public +developer mailing list, so that all developers can benefit from them. +
+ +Make sure that no parts of the codebase that you maintain are missing from the +MAINTAINERS file. If something that you want to maintain is missing add it with +your name after it. +If at some point you no longer want to maintain some code, then please help in +finding a new maintainer and also don’t forget to update the MAINTAINERS file. +
+We think our rules are not too hard. If you have comments, contact us. +
+ +Be friendly and respectful towards others and third parties. +Treat others the way you yourself want to be treated. +
+Be considerate. Not everyone shares the same viewpoint and priorities as you do. +Different opinions and interpretations help the project. +Looking at issues from a different perspective assists development. +
+Do not assume malice for things that can be attributed to incompetence. Even if +it is malice, it’s rarely good to start with that as initial assumption. +
+Stay friendly even if someone acts contrarily. Everyone has a bad day +once in a while. +If you yourself have a bad day or are angry then try to take a break and reply +once you are calm and without anger if you have to. +
+Try to help other team members and cooperate if you can. +
+The goal of software development is to create technical excellence, not for any +individual to be better and "win" against the others. Large software projects +are only possible and successful through teamwork. +
+If someone struggles do not put them down. Give them a helping hand +instead and point them in the right direction. +
+Finally, keep in mind the immortal words of Bill and Ted, +"Be excellent to each other." +
+ +First, read the Coding Rules above if you did not yet, in particular +the rules regarding patch submission. +
+When you submit your patch, please use git format-patch or
+git send-email. We cannot read other diffs :-).
+
Also please do not submit a patch which contains several unrelated changes. +Split it into separate, self-contained pieces. This does not mean splitting +file by file. Instead, make the patch as small as possible while still +keeping it as a logical unit that contains an individual change, even +if it spans multiple files. This makes reviewing your patches much easier +for us and greatly increases your chances of getting your patch applied. +
+Use the patcheck tool of FFmpeg to check your patch. +The tool is located in the tools directory. +
+Run the Regression tests before submitting a patch in order to verify +it does not cause unexpected problems. +
+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()’) +
+Also please if you send several patches, send each patch as a separate mail, +do not attach several unrelated patches to the same mail. +
+Patches should be posted to the
+ffmpeg-devel
+mailing list. Use git send-email when possible since it will properly
+send patches without requiring extra care. If you cannot, then send patches
+as base64-encoded attachments, so your patch is not trashed during
+transmission. Also ensure the correct mime type is used
+(text/x-diff or text/x-patch or at least text/plain) and that only one
+patch is inline or attached per mail.
+You can check https://patchwork.ffmpeg.org, if your patch does not show up, its mime type
+likely was wrong.
+
Using git send-email might not be desirable for everyone. The
+following trick allows to send patches via email clients in a safe
+way. It has been tested with Outlook and Thunderbird (with X-Unsent
+extension) and might work with other applications.
+
Create your patch like this: +
+git format-patch -s -o "outputfolder" --add-header "X-Unsent: 1" --suffix .eml --to ffmpeg-devel@ffmpeg.org -1 1a2b3c4d ++
Now you’ll just need to open the eml file with the email application +and execute ’Send’. +
+ +Your patch will be reviewed on the mailing list. You will likely be asked +to make some changes and are expected to send in an improved version that +incorporates the requests from the review. This process may go through +several iterations. Once your patch is deemed good enough, some developer +will pick it up and commit it to the official FFmpeg tree. +
+Give us a few days to react. But if some time passes without reaction, +send a reminder by email. Your patch should eventually be dealt with. +
+ + +git add the appropriate files before committing?
+
+configure --disable-everything --enable-decoder=foo
+(or --enable-demuxer or whatever your component is)?
+make fate pass with the patch applied?
+
+git commit -s)
+See Sign your work for the meaning
+of sign-off.
+
+av_malloc()
+are notoriously left unchecked, which is a serious problem.
+
+All patches posted to ffmpeg-devel will be reviewed, unless they contain a +clear note that the patch is not for the git master branch. +Reviews and comments will be posted as replies to the patch on the +mailing list. The patch submitter then has to take care of every comment, +that can be by resubmitting a changed patch or by discussion. Resubmitted +patches will themselves be reviewed like any other patch. If at some point +a patch passes review with no comments then it is approved, that can for +simple and small patches happen immediately while large patches will generally +have to be changed and reviewed many times before they are approved. +After a patch is approved it will be committed to the repository. +
+We will review all submitted patches, but sometimes we are quite busy so +especially for large patches this can take several weeks. +
+If you feel that the review process is too slow and you are willing to try to +take over maintainership of the area of code you change then just clone +git master and maintain the area of code there. We will merge each area from +where its best maintained. +
+When resubmitting patches, please do not make any significant changes +not related to the comments received during review. Such patches will +be rejected. Instead, submit significant changes or new features as +separate patches. +
+Everyone is welcome to review patches. Also if you are waiting for your patch +to be reviewed, please consider helping to review other patches, that is a great +way to get everyone’s patches reviewed sooner. +
+ +Before submitting a patch (or committing to the repository), you should at least +test that you did not break anything. +
+Running ’make fate’ accomplishes this, please see fate.html for details. +
+[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]. +
+ +When there is no muxer or encoder available to generate test media for a +specific test then the media has to be included in the fate-suite. +First please make sure that the sample file is as small as possible to test the +respective decoder or demuxer sufficiently. Large files increase network +bandwidth and disk space requirements. +Once you have a working fate test and fate sample, provide in the commit +message or introductory message for the patch series that you post to +the ffmpeg-devel mailing list, a direct link to download the sample media. +
+ +The FFmpeg build system allows visualizing the test coverage in an easy
+manner with the coverage tools gcov/lcov. This involves
+the following steps:
+
configure --toolchain=gcov.
+
+make lcov to generate coverage data in HTML format.
+
+lcov/index.html in your preferred HTML viewer.
+You can use the command make lcov-reset to reset the coverage
+measurements. You will need to rerun make lcov after running a
+new test.
+
The configure script provides a shortcut for using valgrind to spot bugs
+related to memory handling. Just add the option
+--toolchain=valgrind-memcheck or --toolchain=valgrind-massif
+to your configure line, and reasonable defaults will be set for running
+FATE under the supervision of either the memcheck or the
+massif tool of the valgrind suite.
+
In case you need finer control over how valgrind is invoked, use the
+--target-exec='valgrind <your_custom_valgrind_options> option in
+your configure line instead.
+
FFmpeg maintains a set of release branches, which are the +recommended deliverable for system integrators and distributors (such as +Linux distributions, etc.). At regular times, a release +manager prepares, tests and publishes tarballs on the +https://ffmpeg.org website. +
+There are two kinds of releases: +
+release/X, with X being the release
+version number.
+Note that we promise to our users that shared libraries from any FFmpeg +release never break programs that have been compiled against +previous versions of the same release series in any case! +
+However, from time to time, we do make API changes that require adaptations +in applications. Such changes are only allowed in (new) major releases and +require further steps such as bumping library version numbers and/or +adjustments to the symbol versioning file. Please discuss such changes +on the ffmpeg-devel mailing list in time to allow forward planning. +
+ +Changes that match the following criteria are valid candidates for +inclusion into a point release: +
+The order for checking the rules is (1 OR 2 OR 3) AND 4. +
+ + +The release process involves the following steps: +
+bz2 and gz formats, and
+supplementing files that contain gpg signatures
+
+nX, with X
+containing the version number.
+
++ This document was generated using makeinfo. +
+