Commit 5f239c55 authored by Thibault Saunier's avatar Thibault Saunier

Import pitivi wiki in our docs to be generated with hotdoc

To build just go to docs/ and run `hotdoc run`
Result has been uploaded here:

Differential Revision:
parent 1f7c2c59
......@@ -27,3 +27,5 @@ help/index.cache
# Architecture
The image on the right should give you a general idea of what
technologies Pitivi depends on.
![Main Pitivi dependencies](images/Architecture_2015.png)
The Pitivi **user interface** is made using GTK+, a toolkit for creating
graphical user interfaces using widgets and event handling.
The **backend** is made of the following components:
- [GES]( (GStreamer Editing Services), a library
wrapping Non-Linear Engine to offer
a higher level friendly API for video editing. Non-Linear Engine is
media-agnostic and has no notions of video editing. Non-Linear
Engine is basically composed of a few thread-safe GStreamer plugins
which allow compositing and mixing and translating the project's
timeline dynamically into a GStreamer pipeline.
- [GStreamer](, a multimedia
framework that allows us to do anything multimedia-related. It is
very flexible and uses elements that are packaged in the form of
plugins. These elements can be codecs/muxers/demuxers/effects, etc.
Ultimately, all the components above are based on GLib and communicate
through its signals.
- GLib is a low level C library that provides fundamental types and
algorithms. It is a base upon which everything is constructed. Since
we interact with GStreamer through [GES](, in Pitivi
we can see the GLib basic types (gboolean, gchar, gint, gfloat,
gdouble etc).
- [GObject]( is a part of
GLib that provides an object-oriented framework for C.
# Bug reporting
Welcome, testers!
To report a bug/problem in the software, or request a new
feature/enhancement, [create a
and set Projects: Pitivi.
Bug reporting and feature requests are managed with Freedesktop's
[Phabricator]( You need to create
an account to file tasks and comment on them. Take a look at the
[existing list of bugs/feature
requests]( to see if
your problem has already been reported *(hint: use control+F in your
browser to search!)*.
Example queries:
- [Everything]( - All
the tasks (bug reports and feature requests).
- [Patches](
— All the patches (diffs) attached to tasks that have not yet been
- [Pitivi tasks for
newcomers]( —
feature requests and some small bugs that are considered easier for
new contributors to tackle.
# Providing debugging information
## Sharing sample files, projects, and “scenarios”
In some cases we might ask you to share **sample media files** with us
to debug a particular issue. If you don't have your own hosting space,
we have a FTP account with unlimited space available for this purpose,
provided by [](
1. Using a FTP client (such as FileZilla, available on most Linux
distributions), connect to “” using the username
“” ( is part of the username). Ask
[us]( for the password on IRC.
2. Please follow our simple naming convention and put your files in a
folder called with the ID of the bug report (eg. T3553) so we can
find it easily.
3. Your uploaded files will be in a private staging folder (only
visible through FTP); once reviewed, we may move your uploaded files
to <> for ease of
You can also share in a similar way a **project archive** containing the
project and all the media is uses:
1. Use the “Select unused clips” feature to easily remove unused media
from your project, this will help you save space (and upload time).
2. Click the menu button top-right and choose the “Export project as
tarball...” menu item. Save the .xges\_tar file somewhere. It will
contain your project file and its associated media.
3. Upload it as described above.
In addition to the project archive, it is extremely helpful to provide
**“scenario” files**. These are automatically generated each time you
use a project and contain the operations you made. Combined with the
project archive, these allow us to perform exactly the actions that have
occurred to trigger the bug. This makes reproducing the issue on our
machines a very easy and reliable process, which saves you a ton of
time! Here's **how to provide scenario files to facilitate the
1. Save your project, right before triggering the bug.
2. Trigger the bug (make Pitivi crash or freeze).
3. Get the last/newest scenario file from `~/.cache/pitivi/scenarios/`
or `~/.var/app/org.pitivi.Pitivi/cache/pitivi/scenarios/`
4. Upload it as described above, so we can reproduce your issue and
integrate it into our test suite so that it does not happen again in
the future!
## Stack traces for crashes
When reporting a **crash** or when the application freezed **deadlock**,
it would be good to provide a **stack trace**.
### When running with Flatpak
Make sure you have the GNOME Sdk and Debug symbols installed:
` GNOME_REPO=$(flatpak remote-list --user -d | grep `[``](` | awk '{ print $1 }')`\
` flatpak install --user $GNOME_REPO org.gnome.Sdk 3.20`\
` flatpak install --user $GNOME_REPO org.gnome.Sdk.Debug 3.20`\
` flatpak install --user $GNOME_REPO org.gnome.Sdk 3.22`\
` flatpak install --user $GNOME_REPO org.gnome.Sdk.Debug 3.22`
Start a shell in the Pitivi bundle environment
`flatpak run -d --command=bash org.pitivi.Pitivi`
Start Pitivi inside gdb
`gdb python3 -ex 'run /app/bin/pitivi`'
When Pitivi crashes, run `bt full` to get the backtrace. When Pitivi
freezes, press Ctrl+Z and run `thread apply all bt` to get the
backtraces for all the threads.
### When running from the packages of your Linux distro
See GNOME's [Getting
instructions for some comprehensive documentation and tips on the
For those of you who already know how to install the relevant debug
packages etc, we provide you with some simple reminders below of
commands that can be particularly useful in Pitivi's context.
When you want to “attach” to an existing Python process (useful for
deadlocks, where the application will be hung instead of crashed):
When you want to run Pitivi entirely in gdb from the start:
`gdb python3`\
`set pagination 0  # avoids the need to press Enter to ``scroll`
`run /usr/bin/pitivi  # the version installed system-wide.`
When Pitivi crashes, run `bt full` to get the backtrace. When Pitivi
freezes, press Ctrl+Z and run `thread apply all bt` to get the
backtraces for all the threads.
## Debug logs
When you need to know what’s going on inside pitivi, you can launch it
with a debug level. In
there are five levels: ( <span style="color:red;">ERROR</span>,
<span style="color:yellow; background-color:gray;">WARN</span>,
<span style="color:magenta;">FIXME</span>,
<span style="color:green;">INFO</span>,
<span style="color:blue;">DEBUG</span>,
<span style="color:cyan;">LOG</span> ) = range(1, 7). As such, if you
want to see errors and warnings only, you launch
`PITIVI_DEBUG=2 bin/pitivi`
...and if you want to see everything you do
`PITIVI_DEBUG=6 bin/pitivi`
If that's “too much” and you want to focus on particular parts of the
code, you can do so. For example, you can get output from the `Timeline`
and `MediaLibraryWidget` classes only:
`PITIVI_DEBUG=`**`timeline`**`:6,`**`medialibrarywidget`**`:6 bin/pitivi`
Here are various examples of commands you can use to generate detailed
debug logs that include not only Pitivi's debug output, but also
A basic log can be obtained by running:
`PITIVI_DEBUG=*:5 GST_DEBUG=2 bin/pitivi > debug.log 2>&1`
To get debugging information from Non-Linear Engine, you could use:
`PITIVI_DEBUG=5 GST_DEBUG=3,nle*:5,python:5 bin/pitivi > debug.log 2>&1`
The information most likely to be useful would probably be the debug
info from [GES]( in addition to Pitivi's:
`PITIVI_DEBUG=5 GST_DEBUG=ges:5 bin/pitivi > debug.log 2>&1;`
Some additional tips:
- When using GST\_DEBUG, the resulting logs will most likely be too
big to be attached to a bug report directly. Instead, compress them
(in gzip, bzip2 or lzma format) before attaching them to a bug
# Python performance profiling
In the rare cases where a performance problem is caused by our UI code,
you can profile Pitivi itself, with this command (and yes,
“JUMP\_THROUGH\_HOOPS” is needed for this case, it is an environment
variable of
`JUMP_THROUGH_HOOPS=1 python3 -m cProfile -s time -o pitivi_performance.profile bin/pitivi`
The resulting “pitivi\_performance.profile” file can then be processed
to create a visual representation of where the most time was spent and
which functions were called the most often in the code. See also [Jeff's
blog posts on profiling](
# Command line tools
This is a list of tools to use for developing Pitivi.
# Commands
## ges-launch
Used to play back xges files and render them.
`# Render project.xges to video.ogv.`\
`$ ges-launch-1.0 -l project.xges -o video.ogv`
## gst-launch
Launches GStreamer pipelines.
`# Play a video with the decodebin`\
`$ gst-launch-1.0 filesrc location=foo.ogv ! decodebin ! autovideosink`
## gst-inspect
Lists installed GStreamer plugins.
`# Find all plugins containing ``2000`\
`$ gst-inspect-1.0 | grep 2000`
`# List details of matroskamux`\
`$ gst-inspect-1.0 matroskamux`
## gst-discoverer
Prints information of a media file.
`# Print info of foo.mp3`\
`$ gst-discoverer-1.0 foo.mp3`
## gst-validate-launcher
Launches gst validate test suites.
`# -t enables blacklisted tests`\
`$ gst-validate-launcher -t ges.playback.*`
# Building
## cerbero
The GStreamer build system. Used to compile the Pitivi bundle builds or
the GStreamer SDK.
`# Build Pitivi with dependencies`\
`$ cerbero build pitivi`
## Pitivi build environment
Builds Pitivi in an own environment
`# Open shell in Pitivi environment`\
`$ ./bin/`
`# Update git repos and build everything`\
`$ ./bin/ --build`
To build less packages the script checks if a sufficient GStreamer
release is installed in your system. To build a git master version in
this case, you need to set this value to a higher version:
in bin/
# Debugging
If you want debug information to be printed in general, you have to use
the GST\_DEBUG envoirement variable. Execute commands like so:
`$ GST_DEBUG=3 gst-launch-1.0 videotestsrc ! autovideosink`
You can also filter the debug categories
`$ GST_DEBUG=audiotestsrc:5 gst-launch-1.0 videotestsrc ! autovideosink`
## Pipeline graph
You need graphviz installed for this.
`$ GST_DEBUG_DUMP_DOT_DIR=/tmp/ gst-launch-1.0 videotestsrc ! autovideosink`
Now you can convert the dot files to png:
`$ dot -Tpng -o file.png`
## gdb
The GNU debugger. A C debugger.
To debug a segfault, you need following syntax to run gdb:
`$ gdb --args python ./bin/pitivi`
`$ gdb --args sh ges-launch-1.0 -l project.xges`
# Releases
For short-term release plans and events, see the calendar
For long term plans, see the [Roadmap](
- [0.99](releases/ “Giant enemy crab” should be released early
in 2017.
Among the current releases, only the latest release is supported at any
given time (unless otherwise noted):
- 2016 Dec 5th: [0.98](releases/ “Getting there”
- 2016 Aug 8th: [0.97](releases/
- 2016 Jun 30th: [0.96](releases/ “Cogito Ergo Proxy”
- 2015 Nov 13th: [0.95](releases/ “Enfant suisse”
- 2014 Nov 2nd: [0.94](releases/ “Tricks or Tracebacks?”
- 2014 Mar 20th: [0.93](releases/ “Ra is a Happy”
- 2013 Nov 4th: [0.92](releases/ “Baby Steps”
- 2013 Sep 29th: [0.91](releases/ “Charming Defects”
- 2012 May 3rd: [0.15.2](releases/ “I accidentally... the
whole render”
- 2012 Feb 24th: [0.15.1](releases/ “Endless Excursion”
- 2011 Sep 27th: [0.15](releases/ “Ich bin ein berliner”
- 2011 May 31st: [0.14](releases/ “No longer kills kittens”
- 2010 Sep 15th: [0.13.5](releases/ “I Missed My Lunch”
- 2010 Mar 10th: [0.13.4](releases/ “Cabernet d’Anjou”
- 2009 Sep 12th: [0.13.3](releases/ “... we shall never
- 2009 Aug 13th: [0.13.2](releases/ “Jailbreak (out of
Deadlock City)”
- 2009 May 27th: [0.13.1](releases/ “L'Aquila Immota Manet :
The eagle remains unmoved”
- 2008 Dec 11th: [0.11.3](releases/ “Paella Cubana”
- 2008 Oct 15th: [0.11.2](releases/ “Milanesa de Lomo”
- 2007 Nov 18th: [0.11.1](releases/ “A gentlemen game played
by hooligans”
- 2007 Oct 14th: [0.11.0](releases/ “A hooligan's game played
by gentlemen”
- 2007 May 30th: [0.10.3](releases/ “Got some new t-shirts”
- 2007 Jan 28th: [0.10.2](releases/ “A New Toy”
- 2006 May 23rd: [0.10.1](releases/ “Sister and Friend”
- 2006 Apr 26th: 0.10.0 “It's a birthday party”
# Talks
See the Pitivi website's [showcase
page]( for video recordings and
slides of some of these talks.
- 2014 July 27th: GUADEC (Pitivi)
- 2013 October 22nd: GStreamer Conference (GES)
- 2013 August 4th: GUADEC (Pitivi)
- 2012 August 27th/28th: GStreamer Conference (GES)
- 2012 July 29th: GUADEC (Pitivi & GES)
- 2012 June 9th: GNOME Asia (Pitivi & GES)
- 2011 Dec 10th: ExpoLibre Talca (Pitivi & GES)
- 2011 May 25th: Meego Conference (GES)
- 2011 May 11th: Libre Graphics Meeting 2011 (Pitivi)
- 2010 March 26th or 28th: Ubuntu Global Jam in Montréal (lightning
talk about Pitivi, in French)
- 2009 July: GUADEC 2009 (Pitivi)
- 2009 May 8th: Libre Graphics Meeting 2009 (Pitivi)
- 2006 July 22nd: LUGRadio Live 2006
- 2006 June 23rd-30th: GUADEC 2006 (Pitivi)
# In the Media
For a roundup of mentions in the media, see the
[Praise]( page.
# Proposal
## What is its ultimate goal?
The ultimate goal of this project is to make it easier for PiTiVi users
to intuitively edit and share videos.
## What components will it have?
I will be creating modules for PiTiVi using GStreamer.
## What benefits does it have for GStreamer and its community?
Currently, PiTiVi is the one of the leading video editors on Linux which
uses GStreamer. It is bundled with Ubuntu. It is very simple to use but
lacks a few essential features which, if implemented, would greatly
expand its userbase. It would be a major boost for the GStreamer and
PiTiVi community.
## Why you’d like to complete this particular project?
While PiTiVi has many necessary functions, it is lacking in the
following areas:
### 1. Rendering presets
Most users want the output formatted for a specific device or service –
YouTube, iPod, iPhone, DVD, mobile, etc. Presently, the user would have
to manually specify the codecs, containter and codec settings like
resolution, frame rate,etc. He would have to either be familiar with the
codecs or would have to google it up.
`   1. The user should just be able to click on the output format and render. This would enable us to expand the userbase to people without much codec knowledge.`\
`   2. User can add, remove and rename presets and edit codec settings within the render dialog menu.`\
`   3. The presets should be stored seperately and the user should be able to import and export presets from GUI.`\
`   4. Enable us to bundle a default set of rendering and project setting presets`
Presets Suggested : iPod , iPad, PlayStation 3, DVD (NTSC, PAL), HTML5 (
Theora + Vorbis ), Flash video (for embedding), HD (using mkv -&gt; good
Reference : <>
### 2. Upload to video services
Users should by able to easily upload their videos to YouTube, Vimeo, and DailyMotion from PiTiVi using their respective APIs
through the intuitive GUI.
Create a uploader class to make integrating other video services in the
future easier.
Support limitations of each – file size, splitting
### 3. Fix UI Bugs
Users have reported for multiple GUI enhancements. Though they have
normal priority, coding it would greatly improve the easy of use
`   1. Bug 622079 – Use current clip’s parameter -> Club with render profile setting`\
`   2. Bug 608682 – Ability to add markers to identify scenes and as a visual reminder in timeline, Add with Insert -> Marker and keyboard shortcut`\
`   3. Bug 594485 – Ask for confirmation before deleting previously rendered file`\
`   4. Bug 630374 -Add the ability to export the image currently seen in the viewer`\
`   5. Bug 608108 – More details in unsaved dialog box`\
`   6. Bug 578671 – Catch encoder exceptions and show in debugger window`\
`   7. Bug 586071 & `[``](` – Custom labeling of clips`
Moderate 1:
`   1. Bug 575464 – Vertical timeline markers for every defined duration (10 seconds)`\
`   2. Bug 596131 – Implement color-correction like white balance using GStreamer ( GES? )`\
`   3. Bug 603738 – Hide toolbar + timeline in fullscreen`
Moderate 2:
`   1. Bug 637078 – Ability to render only selected portion of the timeline`\
`   2. Bug 632319 – Manual layer interface`\
`   3. Bug 593919 – Implement cropping/panning/zooming for clips`\
`   4. Bug 642129 – Change properties (resize, time duration) of multiple photos at one go.`
## How do you plan to achieve completion of your project?
Following is a breakup of the project goals. Estimated time for each
target is in braces.
`   Up to May 23 – Study PiTiVi code. Gain indepth knowledge of GStreamer and codec settings and GooCanvas.`\
`   Target 1 ( 2-3 weeks ) – Implement Preset Manager for Render`\
`   Target 2 ( 2 weeks ) – Implement video uploading to YouTube, Vimeo, and DailyMotion from GUI`\
`   Target 3 ( 1 week ) – Code Cleanup – Mid-term Evaluation`\
`   Target 4 ( 2 weeks ) – Implement Easy GUI enhancements`\
`   Target 5 ( 2 weeks ) – Implement Moderate 1 GUI enhancements`\
`   Target 6 ( 2 weeks ) – Implement Moderate 2 GUI enhancements`\
`   Target 5 ( 1 week ) – Final Code Cleanup and Documentation`
## What will showable at mid-term ?
At midterm, Render profile presets and video uploading service would be
## About Me
My Name is Feroze Naina, and I’m currently doing my B.Eng in Chennai,
GES (GStreamer Editing Services) is a cross-platform library that sits
on top of [GStreamer]( and
Non-Linear Engine. GES simplifies the
creation of multimedia editing applications. Basically, GES is a
complete [SDK]( for making a video
editor (but not only that).
Traditionally, Pitivi was a user interface and a homemade video editing
“core” (or “backend”) that interacted directly with
[GNonLin](attic/ Starting in version
[0.91](releases/, Pitivi's core has been replaced by GES. This
means that Pitivi is mostly only a user interface on top of GES.
Starting in version [0.95](releases/, GNonLin has been replaced
by Non-Linear Engine to improve stability.
GES does not aim at serving the needs of Pitivi only: we are building
the platform of the future and breaking the cycle of failed projects.
Indeed, other applications are already using GES or migrating to it.
> *“Pitivi is one of the 'generous' projects that develops not just an
> editor, but a set of libraries to implement editors. \[Applications
> built on top of those libraries\] are not really re-inventing the
> wheel, they can piggyback on top of the work that these folks are
> doing, and then implement UI features that they care about the
> most.”*\
> — Bassam Kurdali, director of [Elephants
> Dream]( and
> [Tube](
In addition to the fact that GES encourages code reuse among audio/video
editing software, here are some concrete advantages that we've noticed
while porting Pitivi to GES:
- It solves many architectural issues of the past.
- It vastly simplifies Pitivi development:
- More than 20 000 lines of code have been removed from Pitivi as
a result
- [A big
of the Pitivi codebase was done in early 2011, significantly
reducing the amount of modules/files to deal with.
- No more confusion between the UI and backend parts
- Much less GStreamer knowledge is required to contribute to
Pitivi itself.
- It has much better performance.
Further reading for contributors:
- See the [Architecture]( page for a visual
overview of the relationship between Pitivi, GES, Non-Linear Engine
and other components.
- Read the [GES API reference
if you need to interact with GES. This documentation can also be
found locally in the “docs/libs/html/” subdirectory of your GES git
- [The initial GES
which explains why GES was created, what its various components are
and how it fits with GStreamer.
# Git
[Git]( is the most popular [distributed revision
system]( used
by the kernel, X, GStreamer, GNOME, etc... Git allows you to get a
checkout (with full history) of the Pitivi code, create your own
branches, publish those, etc... without the need for access to the
central repository.
Indeed, one of the very big strengths of a decentralized (a.k.a.
distributed) system is that it is truly open and meritocratic: it allows
you to do whatever changes you want to your repository, request
feedback/reviews and then request that others pull your changes into the
main repository on which others base their work upon. See
<> for an explanation of
this phenomenon.
This page is not meant to be a general tutorial for Git; for that, see
the [GNOME Git page](, the [official Git
tutorial/documentation page]( and [git
ready]( In this page, we will cover some more
advanced usage and the **specifics of how we use Git in the Pitivi
project**. This is aimed at people coming from Bazaar or Subversion.
# First steps: checking out the main repository
`git clone `[`git://`](git://`  # do the initial repository checkout`
You should now have a directory called pitivi with the latest version of
the files checked out. You are in the **`master`** branch.
**Note**: unlike in Bazaar or other DVCSes, in git you only do this
once; the “remotes” and branches in are all self-contained in the
repository. In other words, you only do one checkout and do everything
inside it using branches and remotes.
# Dealing with remotes and branches
You can see all local branches by using the `git branch` command. The
branch you are working in is marked with an asterisk (**\***). You can
view all branches, including the remote ones, by doing:
`git branch -a`
You'll notice that it shows you all the branches available from the
<> repository.
Let's say we add multiple people's remote repositories inside your local
repository (see [Git repositories]( for the
list of our known remotes):
`git remote add nekohayo `[``](\
`git remote add thiblahute `[``](
To update the remotes:
`git remote update`
And now you would be able to do stuff like:
`git checkout thiblahute/somebranch`
Or, to create a new local branch based on that branch:
`git checkout -b mynewbranch thiblahute/somebranch`
“git remote update” does not update your local branches, only the
remotes. For example, if you have a local branch called “titles” based
on “nekohayo/titles” (remote branch) and the “titles” branch on the
“nekohayo” remote changed, you will have to checkout your local “titles”
branch and update it to reflect the changes (with git pull --rebase, or
a git reset --hard, depending on whether or not you want to keep your
local changes).
When the remote party has deleted some branches, you're still left with
local copies of those remote branches... eventually you can clean it up
`git remote prune REMOTE_NAME`
I like to think of “git checkout” like “svn switch”: it allows you to
move between branches (among other things). So, to go back to the main
branch, you do “git checkout master”.
## Creating a work branch
It is good practice never to do work on the master branch (more details
in the next section). Therefore you need to create a work branch :
` git branch work master`
If you use `git branch` you will now see your new branch... but you are
still in `master`.
To switch to your `work` branch you need to check it out using:
` git checkout work`