Detailed instructions for coders

The Cinelerra-CV Community is looking for new developers!

  • Anyone who wants to take responsibility can become a developer/maintainer of Cinelerra-CV.
  • Anyone can send a patch to the Cinelerra-CV Mailing List for Cinelerra-CV as well for Cinelerra-CVE.
  • A new developer is free to port any changes, fixes, new features from any branch, fork of Cinelerra to Cinelerra-CV
    and create new fixes/features to Cinelerra-CV. Einar Rünkaru is ready to help.
  • Patches for Cinelerra-CVE should be sent directly to Einar Rünkaru. He can answer then privately.
  • Patches for Cinelerra-CV should be sent to the CV-Mailing List for review.
  • Patches will be accepted and applied when during review and test we find no bugs in it.
  • Anyone sending fixes must be ready for bad public feedback and complete rejection of their fixes.
    As a rule the first fixes are wrong because of poor understanding of the whole program.
    Sending patches and receiving feedback is one method of learning Cinelerra.

Quick overview Cinelerra CV repositories

The source code of Cinelerra-CV is available from stable and experimental git repositories.

To find out more, go to the repository page.

A short introduction to Cinelerra's source layout

For a very quick start:


  • guicast - low level gui - direct interaction with X
  • cinelerra - the core parts of cinelerra
  • plugins - plugins (mostly audio and video effects)
  • quicktime, libmpeg3, mpeg2enc - encoders/decoders

The rest can be classified as supporting stuff.

Some files to start out with:

  • guicast/{bcwindowbase, bcwindowdraw}.C - base class of all windows
  • guicast/thread.C - base class of threads
  • guicast/bcsignals.C - signals, debugging helpers
  • cinelerra/mwindow{,gui}.C - main (program) window
  • cinelerra/cwindow{,gui}.C - composer window
  • cinelerra/awindow{,gui}.C - resources window
  • cinelerra/vwindow{,gui}.C - viewer
  • cnelerra/plugin{,a,v}client.C - base classes for a plugin
Audio and video are kept in fully separated paths (classes, threads).


The official repository

The official CinelerraCV git repository is managed by core developers.

The master branch stores the live development.
Every official release freezes the development into a dedicated branch.

Changes must be approved by a core developer.

Core developers

Core developers are Cinelerra hackers that are happy to accept a small responsibility to help CinelerraCV grow.
Core developers are volunteers that help Cinelerra in their spare time.
Core developers regularly work on CinCV code (when they can) and regularly communicate with the Community (when they can).
Core developers do peer reviewing, discuss about patches by core developers and other contributors.
Core developers keep an eye on the bug tracker.
They also discuss about long term general development choices.
Core developers have access to the official repository.
When a core developer can't be a core developer anymore s/he tells that to the Community before disappearing.

There are some minimum requirements for new developers:

Anyone who wants to become core developer of Cinelerra must have had at least two accepted commits to the official Cinelerra master branch.
Then he/she can send a letter of application to the mailing list describing what he/she wants to do as a core developer.
Commit access will be discussed and decided by the core developers.

Other contributors

Occasional code contribution is very welcome.

Patch storage

We want the contributed code stored in a stable place, with easy access to be sure that we'll forever have a copy of the original patch.
Small patches (max 60KB) can be sent to the mailing list as an e-mail attachment.
The Trac powered bug tracker is set to accept attachments as big as 256KB.
Bigger patches can be committed to the "mob" GIT repository.
Frequent contributors can ask for a personal git repository.

Any patch not immediately available or loaded onto a site that needs some quirk for downloading (registration, waiting times, fees…) will be rejected automatically.

Mail notification

Contributions must be notified to the mailing list.
Patches must start a new thread whith subject

[PATCH] Name of the patch

The body of the message must contain the description of the patch and must include the reference (link) to the patch.

Interaction with the community

Contributors are asked to collaborate for the integration.
Contributors must accept that their contribution will be reviewed by core developers, and can thus be rejected, with detailed comments.
Core developers will normally review the contribution within two weeks.
If no reply is given within four weeks, the contributor may send a reminder.

For Cinelerra's sake, contributors are asked to keep up the effort, improve and resubmit the work.
Please note: the mailing list is not a patch dump, but a place for collaborative work.

Proposed changes (patches or git commits)

Every change must be approved by at least one core developer before being integrated into the official repository.
Exceptions that can be commited directly are obvious bugfixes or fixes to recent commits.

The preferable way to prepare patches is git format-patch, but we accept patches in all formats that we can understand. We hope that this makes things simpler for new contributors.

Every patch sent must have a name in the subject of the mail (the subject must start with [PATCH]) and have a description about what/why/how the patch does improve Cinelerra-CV.

How to work with git format-patch

To create patches with git-format-patch and send them with git-send-email you may have to add a configuration like this to ~/.gitconfig:

    suffix = .patch
    numbered = auto
    signOff = true
    coverletter = auto
    smtpEncryption = ssl
    smtpServer =
    smtpUser = username
    smtpServerPort = 465

Afterwards, you can create and send patches like this:

    cd cinelerra-cv-2.3.git
    mkdir outgoing
    git format-patch -2 -o outgoing/
    git send-email outgoing/

SignOff is not currently required.

The smtp setup above is just a basic example. Please consult your internet or hosting provider for more information about smtp settings.

Every change must:

1. address a single feature

Separate, single-feature commits are easier to review and test. They also help building a clear history, making reversions possible.
This should apply at any level. For instance, even the creation of a new theme requires two commits:
1. making a copy of an old theme and rename it
2. applying changes to the theme

2. have a descriptive log

The change must be accompanied by the "what" and "why", with a detailed description directed at developers
that are likely at least half-aware of what is going on in the subsystem that is being changed.
The message should explain what the subsystem _should_ do, what it actually does (i.e. the reason of the
bug) and how to reproduce the problem. If the bug fix is non-obvious, it should be explained as well.
Possible complications of the change, risks, limitations or known bugs must also be included.
Every significant (non trivial) change should be linked to a Trac ticket number and possibly to a milestone.

3. be non-destructive

Features should not be removed or replaced without a very good reason (discussed and approved by core developers).

4. try hard to be compatible
Ideally the new version of CinCV should be able to import a project created in a former version of CinCV. Yet, when important innovations requires it, compatibility can be broken: projects saved from a newer version may not load to previous version.
In such cases, the change will be clearly marked with a tag. The ability to open old projects will be kept by maintaining an older version, keeping it buildable.
Compatibility between CinCV and CinHV is not a priority.

Patches must not introduce new compiler warnings when compiled with modern compilers. (Warnings can be ignored if the cause is outside of current patch).

5. follow the style

The new code should adhere to the coding standard that is used in surrounding code.
It is good tone to copy the coding style that you find rather than to force your own style onto existing code (e.g. white-space style, using tabs, not 8 spaces).

Different parts of Cinelerra have different coding styles. The most common is:

int main()
        int i;
        if(i == 1)
                i = 2;

In this example white spaces are made using tabs as follows:

int main()
<tab>int i;
<tab>if(i == 1)
<tab><tab>i = 2;

FIXME: add an Howto set up emacs, vi, and so on to follow this style

Patches must not have excessive empty lines, commented out parts of code, debug messages.

Notes about new files

The license of a new file must be compatible with GPLv2.

Files that are not created by the author of the patch must have the origin mentioned (at least in the commit log).

Every new graphical element is a new file.
It must have a "by" line (at least a notice with the author's name in the commit log) and a copyright notice.
It must be proved that the artwork is permitted to be used in Cinelerra.

Notes about git commit messages

The git commit message should be properly formatted:

  • a single summary line (max 76 characters),
  • a blank line,
  • the detailed description.