\input texinfo @c -*- texinfo -*-@documentencoding UTF-8 @settitle Developer Documentation@titlepage@center @titlefont{Developer Documentation}@end titlepage @top @contents @chapter Introduction This text is concerned with the development @emph{of} FFmpeg itself. Informationon using the FFmpeg libraries in other programs can be found elsewhere, e.g. in:@itemize @bullet@itemthe installed header files@item@url{http://ffmpeg.org/doxygen/trunk/index.html, the Doxygen documentation}generated from the headers@itemthe examples under @file{doc/examples}@end itemize If you modify FFmpeg code for your own use case, you are highly encouraged to@emph{submit your changes back to us}, using this document as a guide. There areboth pragmatic and ideological reasons to do so:@itemize @bullet@itemMaintaining external changes to keep up with upstream development istime-consuming and error-prone. With your code in the main tree, it will bemaintained by FFmpeg developers.@itemFFmpeg developers include leading experts in the field who can find bugs ordesign flaws in your code.@itemBy supporting the project you find useful you ensure it continues to bemaintained and developed.@end itemize For more detailed legal information about the use of FFmpeg inexternal programs read the @file{LICENSE} file in the source tree andconsult @url{https://ffmpeg.org/legal.html}. @section Contributing code All proposed code changes should be submitted for review to@url{mailto:ffmpeg-devel@@ffmpeg.org, the development mailing list}, asdescribed in more detail in the @ref{Submitting patches} chapter. The codeshould comply with the @ref{Development Policy} and follow the @ref{Coding Rules}.The developer making the commit and the author are responsible for their changesand should try to fix issues their commit causes. @anchor{Coding Rules}@chapter Coding Rules @section C language features FFmpeg is programmed in the ISO C99 language, extended with:@itemize @bullet@itemAtomic operations from C11 @file{stdatomic.h}. They are emulated onarchitectures/compilers that do not support them, so all FFmpeg-internal codemay use atomics without any extra checks. However, @file{stdatomic.h} must notbe included in public headers, so they stay C99-compatible.@end itemize Compiler-specific extensions may be used with good reason, but must not bedepended on, i.e. the code must still compile and work with compilers lackingthe extension. The following C99 features must not be used anywhere in the codebase:@itemize @bullet@itemvariable-length arrays; @itemcomplex numbers; @itemmixed statements and declarations.@end itemize @section Code formatting conventions There are the following guidelines regarding the indentation in files: @itemize @bullet@itemIndent size is 4. @itemThe TAB character is forbidden outside of Makefiles as is anyform of trailing whitespace. Commits containing either will berejected by the git repository. @itemYou should try to limit your code lines to 80 characters; however, do so ifand only if this improves readability. @itemK&R coding style is used.@end itemizeThe presentation is one inspired by 'indent -i4 -kr -nut'. @subsection Vim configurationIn order to configure Vim to follow FFmpeg formatting conventions, pastethe following snippet into your @file{.vimrc}:@example" indentation rules for FFmpeg: 4 spaces, no tabsset expandtabset shiftwidth=4set softtabstop=4set cindentset 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=redmatch ForbiddenWhitespace /\s\+$\|\t/" Do not highlight spaces at the end of line while typing on that line.autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/@end example @subsection Emacs configurationFor Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:@lisp(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")@end lisp @section CommentsUse the JavaDoc/Doxygen  format (see examples below) so that code documentationcan be generated automatically. All nontrivial functions should have a commentabove 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 @code{!} in it, i.e. replace@code{//!} with @code{///} and similar.  Also @@ syntax should be employedfor markup commands, i.e. use @code{@@param} and not @code{\param}. @example/** * @@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)...@end example @section Naming conventions Names of functions, variables, and struct members must be lowercase, usingunderscores (_) to separate words. For example, @samp{avfilter_get_video_buffer}is an acceptable function name and @samp{AVFilterGetVideo} is not. Struct, union, enum, and typedeffed type names must use CamelCase. All structsand unions should be typedeffed to the same name as the struct/union tag, e.g.@code{typedef struct AVFoo @{ ... @} AVFoo;}. Enums are typically nottypedeffed. Enumeration constants and macros must be UPPERCASE, except for macrosmasquerading as functions, which should use the function naming convention. All identifiers in the libraries should be namespaced as follows:@itemize @bullet@itemNo namespacing for identifiers with file and lower scope (e.g. local variables,static functions), and struct and union members, @itemThe @code{ff_} prefix must be used for variables and functions visible outsideof file scope, but only used internally within a single library, e.g.@samp{ff_w64_demuxer}. This prevents name collisions when FFmpeg is staticallylinked. @itemFor variables and functions visible outside of file scope, used internallyacross multiple libraries, use @code{avpriv_} as prefix, for example,@samp{avpriv_report_missing_feature}. @itemAll other internal identifiers, like private type or macro names, should benamespaced only to avoid possible internal conflicts. E.g. @code{H264_NAL_SPS}vs. @code{HEVC_NAL_SPS}. @itemEach library has its own prefix for public symbols, in addition to thecommonly used @code{av_} (@code{avformat_} for libavformat,@code{avcodec_} for libavcodec, @code{swr_} for libswresample, etc).Check the existing code and choose names accordingly. @itemOther public identifiers (struct, union, enum, macro, type names) must use theirlibrary's public prefix (@code{AV}, @code{Sws}, or @code{Swr}).@end itemize Furthermore, name space reserved for the system should not be invaded.Identifiers ending in @code{_t} are reserved by@url{http://pubs.opengroup.org/onlinepubs/007904975/functions/xsh_chap02_02.html#tag_02_02_02, POSIX}.Also avoid names starting with @code{__} or @code{_} followed by an uppercaseletter as they are reserved by the C standard. Names starting with @code{_}are reserved at the file level and may not be used for externally visiblesymbols. If in doubt, just avoid names starting with @code{_} altogether. @section Miscellaneous conventions @itemize @bullet@itemfprintf and printf are forbidden in libavformat and libavcodec,please use av_log() instead. @itemCasts should be used only when necessary. Unneeded parenthesesshould also be avoided if they don't make the code easier to understand.@end itemize @anchor{Development Policy}@chapter Development Policy @section Patches/Committing@subheading Licenses for patches must be compatible with FFmpeg.Contributions should be licensed under the@uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},including an "or any later version" clause, or, if you prefera gift-style license, the@uref{http://opensource.org/licenses/isc-license.txt, ISC} or@uref{http://mit-license.org/, MIT} license.@uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} includingan "or any later version" clause is also acceptable, but LGPL ispreferred.If you add a new file, give it a proper license header. Do not copy andpaste it from a random place, use an existing file as template. @subheading You must not commit code which breaks FFmpeg!This means unfinished code which is enabled and breaks compilation,or compiles but does not work/breaks the regression tests. Code whichis unfinished but disabled may be permitted under-circumstances, likemissing samples or an implementation with a small subset of features.Always check the mailing list for any reviewers with issues and testFATE before you push. @subheading Keep the main commit message short with an extended description below.The commit message should have a short first line in the form ofa @samp{topic: short description} as a header, separated by a newlinefrom 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 messageshould include its bug ID. Referring to the issue on the bug tracker doesnot exempt you from writing an excerpt of the bug in the commit message. @subheading Testing must be adequate but not excessive.If it works for you, others, and passes FATE then it should be OK to commitit, provided it fits the other committing criteria. You should not worry aboutover-testing things. If your code has problems (portability, triggerscompiler bugs, unusual environment etc) they will be reported and eventuallyfixed. @subheading Do not commit unrelated changes together.They should be split them into self-contained pieces. Also do not forgetthat if part B depends on part A, but A does not depend on B, then A canand should be committed first and separate from B. Keeping changes wellsplit into self-contained parts makes reviewing and understanding them onthe commit log mailing list easier. This also helps in case of debugginglater on.Also if you have doubts about splitting or not splitting, do not hesitate toask/discuss it on the developer mailing list. @subheading Ask before you change the build system (configure, etc).Do not commit changes to the build system (Makefiles, configure script)which change behavior, defaults etc, without asking first. The sameapplies to compiler warning fixes, trivial looking fixes and to codemaintained by other developers. We usually have a reason for doing thingsthe way we do. Send your changes as patches to the ffmpeg-devel mailinglist, and if the code maintainers say OK, you may commit. This does notapply to files you wrote and/or maintain. @subheading Cosmetic changes should be kept in separate patches.We refuse source indentation and other cosmetic changes if they are mixedwith functional changes, such commits will be rejected and removed. Everydeveloper has his own indentation style, you should not change it. Of courseif you (re)write something, you can use your own style, even though we wouldprefer if the indentation throughout FFmpeg was consistent (Many projectsforce a given indentation style - we do not.). If you really need to makeindentation changes (try to avoid this), separate them strictly from realchanges. 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 notmove it to the right)! or do so in a separate commit @subheading Commit messages should always be filled out properly.Always fill out the commit log message. Describe in a few lines what youchanged and why. You can refer to mailing list postings if you fix aparticular bug. Comments such as "fixed!" or "Changed it." are unacceptable.Recommended format: @examplearea changed: Short 1 line description details describing what and why and giving references.@end example @subheading Credit the author of the patch.Make sure the author of the commit is set correctly. (see git commit --author)If you apply a patch, send ananswer to ffmpeg-devel (or wherever you got the patch from) saying thatyou applied the patch. @subheading Complex patches should refer to discussion surrounding them.When applying patches that have been discussed (at length) on the mailinglist, reference the thread in the log message. @subheading Always wait long enough before pushing changesDo NOT commit to code actively maintained by others without permission.Send a patch to ffmpeg-devel. If no one answers within a reasonabletime-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! @section Code@subheading API/ABI changes should be discussed before they are made.Do not change behavior of the programs (renaming options etc) or publicAPI 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). @subheading Remember to check if you need to bump versions for libav*.Depending on the change, you may need to change the version integer.Incrementing the first component means no backward compatibility toprevious 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 anexisting data structure).Incrementing the third component means a noteworthy binary compatiblechange (e.g. encoder bug fix that matters for the decoder). The thirdcomponent always starts at 100 to distinguish FFmpeg from Libav. @subheading Warnings for correct code may be disabled if there is no other option.Compiler warnings indicate potential bugs or code with bad style. If a type ofwarning always points to correct and clean code, that warning shouldbe 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 shouldbe changed to not generate a warning unless that causes a slowdownor obfuscates the code. @subheading Check untrusted input properly.Never write to unallocated memory, never write over the end of arrays,always check values read from some untrusted source before using themas array index or other risky things. @section Documentation/Other@subheading Subscribe to the ffmpeg-devel mailing list.It is important to be subscribed to the@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, 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 seethose comments, and to improve it if requested. (N.B. Experienced committershave other channels, and may sometimes skip review for trivial fixes.) Also,discussion here about bug fixes and FFmpeg improvements by other developers maybe helpful information for you. Finally, by being a list subscriber, yourcontribution will be posted immediately to the list, without the moderationhold which messages from non-subscribers experience. However, it is more important to the project that we receive your patch thanthat you be subscribed to the ffmpeg-devel list. If you have a patch, and don'twant to subscribe and discuss the patch, then please do send it to the listanyway. @subheading Subscribe to the ffmpeg-cvslog mailing list.Diffs of all commits are sent to the@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-cvslog, ffmpeg-cvslog}mailing list. Some developers read this list to review all code base changesfrom all sources. Subscribing to this list is not mandatory. @subheading Keep the documentation up to date.Update the documentation if you change behavior or add features. If you areunsure how best to do this, send a patch to ffmpeg-devel, the documentationmaintainer(s) will review and commit your stuff. @subheading Important discussions should be accessible to all.Try to keep important discussions and requests (also) on the publicdeveloper mailing list, so that all developers can benefit from them. @subheading Check your entries in MAINTAINERS.Make sure that no parts of the codebase that you maintain are missing from the@file{MAINTAINERS} file. If something that you want to maintain is missing add it withyour name after it.If at some point you no longer want to maintain some code, then please help infinding a new maintainer and also don't forget to update the @file{MAINTAINERS} file. We think our rules are not too hard. If you have comments, contact us. @chapter Code of conduct 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 ifit is malice, it's rarely good to start with that as initial assumption. Stay friendly even if someone acts contrarily. Everyone has a bad dayonce in a while.If you yourself have a bad day or are angry then try to take a break and replyonce 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 anyindividual to be better and "win" against the others. Large software projectsare only possible and successful through teamwork. If someone struggles do not put them down. Give them a helping handinstead and point them in the right direction. Finally, keep in mind the immortal words of Bill and Ted,"Be excellent to each other." @anchor{Submitting patches}@chapter Submitting patches First, read the @ref{Coding Rules} above if you did not yet, in particularthe rules regarding patch submission. When you submit your patch, please use @code{git format-patch} or@code{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 splittingfile by file. Instead, make the patch as small as possible while stillkeeping it as a logical unit that contains an individual change, evenif it spans multiple files. This makes reviewing your patches much easierfor 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 @ref{Regression tests} before submitting a patch in order to verifyit 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 compliantand 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@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}mailing list. Use @code{git send-email} when possible since it will properlysend patches without requiring extra care. If you cannot, then send patchesas base64-encoded attachments, so your patch is not trashed duringtransmission. Also ensure the correct mime type is used(text/x-diff or text/x-patch or at least text/plain) and that only onepatch is inline or attached per mail.You can check @url{https://patchwork.ffmpeg.org}, if your patch does not show up, its mime typelikely was wrong. @subheading Sending patches from email clientsUsing @code{git send-email} might not be desirable for everyone. Thefollowing trick allows to send patches via email clients in a safeway. It has been tested with Outlook and Thunderbird (with X-Unsentextension) and might work with other applications. Create your patch like this: 

Lines 1–500 of 878. Load more