Commit 93b1d4ef authored by Alexandru Băluț's avatar Alexandru Băluț

docs: Remove useless obsolete info


Differential Revision:
parent 3e214c78
# Troubleshooting
This is a list of some known issues that are recurrent in users reports.
Issues will be removed as they get fixed (or relatively soon
afterwards). See also the list of [bugs related to
See [Bug reporting]( for instructions on how to
get debug logs to be used for debugging and troubleshooting.
**Tip: restart Pitivi between tries**:
> When an error happens, it is possible that Pitivi may enter an
> inconsistent state (ie: the UI is not responsive anymore, or actions
> don't seem to do anything). Sometimes, restarting Pitivi may solve the
> problem. To be exact, it is a good practice to restart it between
> tries when trying to investigate and isolate bugs. In the next version
> of Pitivi based on [GES](, rendering errors will be
> [shown to
> you](
## I use cinnamon and I can't select clips in the timeline !
As of April 2014, we have spotted that issue. A bug report has been
opened against cinnamon here :
<>. Until the next
version of cinnamon, the solution is to “unset CLUTTER\_DISABLE\_XINPUT”
before launching pitivi.
## Rendering hangs at 1 second (or less) remaining
This is a known bug with Pitivi 0.15.x. There are several ways you can
reduce the probability of this happening:
- If you have extremely long clips (ie: hours) or heavy media files
(ie: gigabytes) in your timeline, try with smaller clips for the
sake of testing
- Make sure the audio track and the video track cover the whole
timeline, without gaps. This means you must have at least one audio
clip under the playhead at all times, and that the beginning/end of
the timeline must match between video and audio.
- If you're using PNG images, try with JPEGs instead.
These tricks are not guaranteed to work in all situations, but they are
some of the most common causes of rendering failing.
## Rendering doesn't start (stuck at “estimating”)
This might be due to many reasons, including an invalid codecs
combination, incorrect codec settings, or something else.
### “The rendered files weighs 0 bytes!”
That's [bug 692316](,
which is most likely fixed for future versions of Pitivi
([0.91](releases/ and newer). In that case, the workaround is
simply to try starting the render again.
### Make sure you have the proper codecs
Some codecs in GStreamer (such as Dirac) are not reliable for use with
Pitivi. When rendering, we recommend you try the following combinations
of containers and codecs:
- Webm
- VP8 video
- Vorbis audio
- Theora video
- Vorbis audio
- Matroska
- x264enc (H.264 video)
- AAC audio
Starting with Pitivi [0.91](releases/, this will not be an issue
anymore, as bad quality codecs will not show up.
### Incorrect codec settings
Some codecs require video resolution width and height to be multiples of
4, 8 or 16. Typically, always make sure that they're at least multiples
of 2. Otherwise, some video codecs won't encode at all, sometimes
they'll encode with suboptimal or broken results.
## Playback performance is bad
See [Performance problems](
## What are the recommended rendering settings to export to YouTube?
“Why don't Theora files work on YouTube?”
- Youtube doesn't support Theora 1.1 videos. Uploading such files will
result in a garbled/corrupt green video.
For files destined to YouTube, you could use this combination:
- Container: Matroska (.mkv): matroskamux
- Video codec: H.264: x264enc
- Audio codec: AAC
# Dependencies
This page is intended for contributors wishing to work with the
**development version**. Otherwise, take a look at [the download
page]( on the main website.
To build Pitivi, you will need the latest devel packages for gstreamer,
pygst, and all related packages. Generally speaking, you will need:
- The latest GStreamer 1.x and plugins including headers (if your
distro doesn't provide it). Since we often fix issues upstream in
GStreamer, even the latest stable GStreamer 1.x releases might not
be enough, we sometimes depend on GStreamer from git. Follow the
[HACKING]( instruction to setup everything.
- GObject introspection including header files (if your distro doesn't
provide it)
- automake
- libtool
- intltool and itstool
- Python 3 including header files
- PyGObject including header files
- GTK 3 including header files
- development headers for OpenGL/OpenGLU through Mesa (used for
glimagesink if you're building GStreamer)
- gtk-doc-tools, yelp-tools, gnome-doc-utils
- gdk-pixbuf2
- gnome-common
- matplotlib
- numpy
- PulseAudio and ALSA header files
Optional but very much recommended:
- gnome-desktop3 (for thumbnails in the media library)
- libnotify's python bindings
- libcanberra's python bindings (pycanberra)
Specifically, if you want to know the **exact versions of our current
dependencies**, have a look at the bottom of
You can use the following commands to do that in one go:
## On Fedora
For starters, copy-paste this paragraph into a terminal to get the basic
Pitivi dependencies, as well as various build dependencies for
`sudo dnf install \`\
`   gcc gcc-c++ yasm-devel python3-devel \`\
`   bison flex intltool itstool libtool libxml2-devel meson ninja-build \`\
`   gnome-common gnome-desktop3-devel gnome-doc-utils gtk3-devel gtk-doc yelp-tools \`\
`   gstreamer1*-devel mesa-libGL-devel mesa-libGLU-devel \`\
`   python3-cairo-devel cairo-gobject-devel \`\
`   pygobject3-devel gdk-pixbuf2-devel \`\
`   python3-matplotlib python3-matplotlib-gtk3 python3-numpy python3-canberra ninja-build \`\
`   redhat-rpm-config`
And then, if you need to build GStreamer (quite likely;
or the environment script will tell you which version is required), you
need to ensure that you have all the required dependencies to build the
various GStreamer plugins. See the next section below.
### GStreamer's dependencies
The yum-builddep utility installs the RPMS needed to build a specific
package by looking at that package's source RPM in your yum
repositories. It only works for one package at a time; this python
script invokes it for each of the relevant packages. Some of the
packages are from the [rpmfusion]( repository so
make sure you have that repository enabled before running the script.
Copy and paste the following script into a .py file, make it executable
and run it as root:
`#!/usr/bin/env python`\
`import sys, os, pwd`
`print(``Will`` ``get`` ``the`` ``build`` ``deps`` ``from`` ``gstreamer1`` ``packages``)`\
`duck = [``gstreamer1``,`\
`    ``gstreamer1-plugins-base``,`\
`    ``gstreamer1-plugins-good``,`\
`    ``gstreamer1-plugins-bad``,`\
`    ``gstreamer1-plugins-bad-nonfree``,`\
`    ``gstreamer1-plugins-ugly``,`\
`    ``python-gstreamer1``,`\
`    ``gstreamer1-libav``,`\
`    ``pitivi``]`
`user = pwd.getpwuid(os.getuid())[0]`\
`if user ==``root``:`\
`    for wat in duck:`\
`        os.system(``dnf`` ``builddep`` ``-y`` ``%s`` % wat)`\
`    print(``You`` ``must`` ``be`` ``root`` ``to`` ``run`` ``this`` ``script.``)`\
`    sys.exit(1)`
Also, to be able to build gst-transcoder, you will need to do this hack
on Fedora after installing “ninja-build”:
`sudo ln -s /usr/bin/ninja-build /usr/bin/ninja`
## On Ubuntu/Debian
You can simply paste the following, which should (hopefully) solve your
dependencies. This was reportedly working on Ubuntu 12.10 but package
names change all the time, so if something is missing (or you have a
better way to solve the deps), please tell us about it.
`# Basic build tools:`\
`sudo apt-get install git build-essential automake libtool itstool gtk-doc-tools yelp-tools gnome-common gnome-doc-utils yasm flex bison`
`# Stuff related to introspection, GTK, canvases, and various other dependencies:`\
`sudo apt-get install libgirepository1.0-dev python3-dev python3-gi python-gi-dev \`\
`python3-cairo-dev libcairo2-dev python3-gi-cairo python3-matplotlib python3-numpy \`\
`libgdk-pixbuf2.0-dev libpulse-dev libgtk-3-dev \`\
`libxml2-dev \`
`# GStreamer 1.x, if you're lucky and your distro packages are recent enough:`\
`sudo apt-get install gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-alsa gstreamer1.0-pulseaudio \`\
`libgstreamer-plugins-bad1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev libgstreamer1.0-0`
`# GStreamer plugins' full set of dependencies to build all the codecs:`\
`sudo apt-get build-dep gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly`\
`sudo apt-get install libglu1-mesa-dev`
## In a Virtual Env
If you are using python virtual environments to do your development, you
aren't going to be able to use the python library packages listed above
for your install, and the packages are not available via install tools.
Install everything \*else\* listed above (keep python-dev)and then
install the following packages.
replace (ENV) with the path to your virtual env (e.g.
/home/aleks/src/python-def/ )
WARNING: the versions used here may change, but the general build
process should still hold. If you get errors about version mismatches,
just grab the appropriate ones and start over.
### PyCairo
Download py2cairo-1.10.0 from the appropriate place, extract it, then:
`./configure --prefix=(ENV)`\
`make && make install`
I don't recall any special overrides, but depending on your distro, you
may need to do something like this if configure complains that it can't
find cairo.h:
`CFLAGS=-I/usr/include/cairo/ ./configure --prefix=(ENV)`\
`make && make install`
### PyGObject
Download pygobject-3.0.0 from the appropriate place, extract it, cd into
it, then:
`PYCAIRO_LIBS=(ENV)/include/pycairo/ PYCAIRO_CFLAGS=-I(ENV)/pycairo/ CFLAGS=-I/usr/include/cairo/ ./configure --prefix=(ENV)`\
`make && make install`
### PyGST
grab gst-python from git, cd to it, ./ This is going to FAIL.
after that, do this:
`PYGOBJECT_LIBS=(ENV)/include/pygobject-3.0/ PYGOBJECT_CFLAGS=-I(ENV)/include/pygobject-3.0/ ./configure --prefix=(ENV)`\
`make && make install`
# GStreamer from Git
The following directions will help you set up latest GStreamer from git.
See also [GStreamer using jhbuild](attic/
for an automated process that is potentially easier (and safer).
# Build system
In order to proceed from here, you need to first have a working build
system. Here are something to get you started; you might need additional
packages or some tinkering. However setting up a build environment is
beyond the scope of this tutorial.
## Fedora
`$ yum groupinstall ``Development`` ``Tools`
## Ubuntu
At the very least, make sure you have build-essentials and binutils.
`$ apt-get install build-essential binutils git`\
`$ apt-get build-dep pitivi`
## Your Distro Here
Add the directions for your distribution
# Set Up \~/bin
We're going to be using a couple of scripts. They'll be easiest to run
if you put them somewhere that's in your current path. I have a
directory called `bin` in my home directory that I use for this purpose.
If you already know how to do this, or you already have \~/bin in your
path, skip this section.
`$ cd`\
`$ mkdir bin`
Now edit `~/.bashrc`, and add this line to the end of the file.
`export PATH=``~/bin:$PATH`
Save the file.
Now edit `~/.bash_profile` and make sure it contains the line
`. ~/.bashrc`
Save the file, then type
`$ exec bash`
`~/bin` should now be in your current path. To check this, type:
`$ env | grep PATH`
You should see a line that starts with `PATH=~/bin`
From now on when you log in or create a new terminal window, `~/bin`
will be in your current path.
# Install build dependencies
Exactly how to do this will vary from system to system.
## Fedora
On Fedora 12 install at least the following packages:
`$ yum install intltool gtk-doc liboil-devel`
And to build plugins needed to use Pitivi, install these packages
as well:
`$ yum install libogg-devel libvorbis-devel libvisual-devel alsa-lib-devel libtheora-devel`
## Debian/Ubuntu
On debian/ubuntu the following command should suffice:
Save a list of all gstreamer library package names: <code>
`$ apt-cache search --names-only '^(lib)?gstreamer\S*' | sed 's/`$.*$` -.*/\1 /' > dependencies`
Install the build dependencies for those packages: <code>
`` $ sudo apt-get build-dep `cat dependencies` ``
## Your Distro Here
Add the directions for your distribution
## Full List of Dependencies
Someone add the full list of build dependencies here.
# Get Latest Gstreamer
## Create a Sources directory
Find a place for your gstreamer sources to go. You could use /usr/src/,
but I prefer to keep them in my home directory so that I do not need
root privileges to update them. For example:
`$ mkdir -p ~/src/gstreamer/head`\
`$ cd ~/src/gstreamer/head`
<b>N.B. that the lowest level directory must be called <i>head</i></b>.
The rest of this tutorial will assume that you are in your sources
## Checkout Sources
We're going to check out gstreamer from git. Gstreamer is split up into
several modules:
- gstreamer
- gst-plugins-base
- gst-plugins-good
- gst-plugins-bad
- gst-plugins-ugly
- gst-python
- gnonlin
- gst-ffmpeg
To check them all out at once...
$ for i in gstreamer gnonlin gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-python gst-ffmpeg
git clone git://$i
To check them out individually, where `module-name` is one of the
gstreamer modules, do:
`$ git clone `[`git://`](git://
# Install GST\_Head Script
We do not want to install gstreamer at this point. gstreamer provides
the gst-uninstalled script which allows you to temporarily switch your
Gstreamer to an uninstalled version.
From your sources directory, copy this script to `~/bin` directory:
`$ cp ~/src/gstreamer/head/gstreamer/scripts/gst-uninstalled ~/bin/gst-head`
The reason we rename the script is that the bit after the dash (head)
refers to the sub-directory in `~/src/gstreamer` (in our case, head).
This allows you to easily have multiple un-installed versions of
Now edit this file and look for the `MYGST` line. Change it to this:
<b>N.B. Each time you want to use your CVS gstreamer, you will need to
run this script. Run it like this:</b>
`$ ~/bin/gst-head`
# Build Sources
This will take a bit of time. If you have a dual- or quad-core computer,
you can replace `make` with `make -j2` in all of the following steps to
speed up the build.
First, we need to build gstreamer:
`$ cd gstreamer`\
`$ ./`\
`$ make`\
`$ cd ..`
Now we need to run gst-head. This allows the other plugins to build
against this gstreamer.
`$ gst-head`
You'll notice you're now in the sources directory: this is because the
gst-head script starts a subshell in this directory. This is how it is
able to make it appear as though your uninstalled version of gstreamer
is the current version.
Build all the modules using these commands, where `module-name` is one
of the gstreamer modules.
`$ cd module-name`\
`$ ./`\
`$ make`\
`$ exit`\
`$ gst-head`
<b>N.B. do <i>not</i> run `make install`</b>
Build the modules in this order:
- gst-plugins-base
- gst-plugins-good
- gst-plugins-bad (optional)
- gst-plugins-ugly (optional)
- gst-python
- gnonlin
- gst-ffmpeg (optional)
# Congrats
If you got to this step, you should be able to check out the CVS version
of PiTiVi. Make sure you run
`$ gst-head`
before you try to start PiTiVi, or PiTiVi will not find your new
versions of gstreamer. You will have to do this once every time you log
in, or every time you want to start PiTiVi in a new terminal. If you
decide you are done using the new version of gstreamer, you can type
`$ exit`
in your terminal to exit the subshell started by running gst-head.
# `gst-inspect` is your friend
This section will explain how to use gst-inspect to verify that your
installation is complete.
# Updating
# GStreamer using jhbuild
JHBuild is a build tool that automates the process of building the GNOME
software stack. It is organized somewhat like a package manager and is
cabable of tracking dependencies between packages. JHBuild eliminates a
great deal of the work of compiling GStreamer manually.
**Warning: The following instructions are not supported** by the PiTiVi
developers. They are provided for informational purposes only. The
author takes no responsibility for damage you may cause to your system
as a result of attempting to follow these instructions. Proceed at your
own risk! Your results may vary.
# Intended Audience
This document is primarily intended for PiTiVi developers and testers
who need to test PiTiVi against the latest development versions of
gstreamer. It is emphatically **not intended for end users** You are
assumed to be familiar with the process of compiling software from
source, and how to deal with problems when they arise.
These instructions assume a debian-based system. For non-debian systems,
replace the apt-get commands and package names with those appropriate
for your distro.
For more information on JHBUild, see <>
# Installing GStreamer Using JHBuild
First things first: Make sure your system is up-to-date, and for ubuntu,
make sure universe, multiverse, etc are enabled in System -&gt;
Administration -&gt; Software Sources. Then run:
`sudo apt-get install git-core gettext build-essential \`\
` libglew1.5 libglew1.5-dev python-gtk2-dev autoconf \`\
` automake1.9 cvs libxml2-dev liboil0.3-dev subversion`
Get some coffee...
## Install GStreamer Build Dependencies
`sudo apt-get build-dep libgstreamer0.10-0 libgstreamer-plugins-base0.10-0 \`\
On Debian and Ubuntu Maverick you may also need to install `autopoint`
`sudo apt-get install autopoint && \`\
`sudo apt-get build-dep libgstreamer0.10-0 libgstreamer-plugins-base0.10-0 \`\
Get some more coffee...
To have the x264 encoder (for H.264) available, you should also install
the **libx264-dev** package.
## Configure Your Environment
If you do not have \~/bin and \~/src directories, create them:
`mkdir bin`\
`mkdir src`
If \~/bin and \~/.local/bin are not already in your path, do this:
`echo 'export PATH=${HOME}/bin/:${HOME}/.local/bin:${PATH}' >> ~/.bashrc`\
`exec bash`
## Install JHbuild
`cd src`\
`git clone `[`git://`](git://\
`cd jhbuild`\
`make -f Makefile.plain`\
`make -f Makefile.plain install`
## Install gst-jhbuild Script
`cd ~/bin`\
`cat > gst-jhbuild << ``EOF`
And paste the following (then press Enter):
jhbuild -f $JHBUILDFILE "$@"
Then run:
`chmod +x gst-jhbuild`
## Install JHBuild Config Files for GStreamer
`mkdir -p src/gstreamer/jhbuild`\
`cd src/gstreamer/jhbuild`\
`cat > gstreamer.jhbuildrc << ``EOF`
And paste the following:
# gstreamer.jhbuildrc
moduleset = [os.path.expanduser('~/src/gstreamer/jhbuild/gstreamer.modules')]
modules = [ 'my-gst-all' ]
checkoutroot = os.path.expanduser('~/src/gstreamer/repos')
prefix = os.path.expanduser('~/src/gstreamer/install')
autogenargs = ''
autogenargs = autogenargs + ' --disable-static'
# consider commenting this out on a single-core system or using -j3, -j4 or -j7
# on systems with > 2 cores
makeargs = "-j2"
os.environ['ACLOCAL'] = 'aclocal -I ' + prefix + '/share/aclocal/'
os.environ['INSTALL'] = os.path.expanduser('~/bin/install-check')
If you want to disable building documentation (to save time), use the
--disable-gtk-doc parameter, like so:
`autogenargs = autogenargs + ' --disable-static --disable-gtk-doc'`
Then run:
`wget `[``](
Note: the official gstreamer module set is [available
Using the official module set may require changes to gstreamer.jhbuildrc
## Build gstreamer
`gst-jhbuild build`
Get lunch...
# Problems
If you're lucky, you'll have a freshly-built copy of gstreamer when you
come back from lunch. If you're unlucky, you'll be staring at a prompt
similar to this one:
*** Error during phase build of gstreamer: ########## Error running make -j2 *** [1/10]
[1] Rerun phase build
[2] Ignore error and continue to install
[3] Give up on module
[4] Start shell
[5] Reload configuration
[6] Go to phase "wipe directory and start over"
[7] Go to phase "configure"
[8] Go to phase "clean"
[9] Go to phase "distclean"
If a build failure occurs, it's probably because one or more of the
above steps were performed incorrectly. Go back over everything and
figure out what you did wrong. Likely sources of error are missing
dependencies. Beyond that, you are assumed to be familiar with the
process of building software from source and capable of resolving issues
with software compilation. Having said that, sometimes waiting a few
minutes and trying again with option \[6\] will magically just work.
One hint you can use to diagnose problems with gstreamer.jhbuildrc and
gstreamer.modules is to start a subshell and see if the sources build
normally when you run
`make clean && ./ && make`
If the sources build normally in this fashion but not using JHBuild, you
can bet that JHBuild or its configuration files are to blame.
Option \[4\] will start a shell at that build phase. You can use it to
tweak the source tree as you see fit, and when you exit the shell you'll
be returned to the menu where you can resume the build process.
- if you want to continue build at the configuration phase (i.e.
re-run ./configure), do that from the menu! Otherwise, the install
phase will fail.
- if you change gstreamer.jhbuildrc or gstreamer.modules, you can try
to reload the configuration with option \[5\] but in the author's
experience, your best bet is to kill and re-start JHBuild.
If you think you've determined that there is a problem with the
gstreamer.jhbuildrc, gstreamer.modules, or these instructions, report
this on the PiTiVi irc channel or on the PiTiVi mailing list. We will
try to keep the JHBuild config files up-to-date.
Keep in mind that the PiTiVi developers want to spend their time working
on PiTiVi, and any issues you have with gstreamer or its dependenci