PiTiVi

Quick Start Manual

Version 0.13.4 – development version
By Jean-François Fortin Tam – last revised April 29, 2010
Contents
About this manual.......................................................................................................................1
License....................................................................................................................................1
Work in progress.....................................................................................................................1
Patches welcome....................................................................................................................1
Introduction..................................................................................................................................2
Welcome.................................................................................................................................2
GStreamer and compatibility..................................................................................................2
About “non-compliant” codecs............................................................................................2
A word about editing-friendly codecs..................................................................................3
System requirements..............................................................................................................3
An overview of the user interface...........................................................................................4
Main window.......................................................................................................................4
Menu bar.............................................................................................................................4
The toolbars........................................................................................................................4
Ruler...................................................................................................................................5
Marker bar..........................................................................................................................5
Timeline..............................................................................................................................5
Playback toolbar.................................................................................................................5
Previewer............................................................................................................................5
Source list...........................................................................................................................6
Getting Started............................................................................................................................7
Creating a project....................................................................................................................7
Editing project settings............................................................................................................7
Saving a project......................................................................................................................7
Getting media..........................................................................................................................7
Importing files.....................................................................................................................8
Using the file chooser.....................................................................................................8
Using drag and drop.......................................................................................................8
Using the source list................................................................................................................9
Sorting................................................................................................................................9
Previewing a clip from the source list.................................................................................9
Tagging...............................................................................................................................9
Quick search.......................................................................................................................9
Filtering...............................................................................................................................9
View modes........................................................................................................................9
Making selections.................................................................................................................10
Selecting a single item......................................................................................................10
Selecting multiple items....................................................................................................10
Putting media in the timeline.................................................................................................10
Using clips.............................................................................................................................10
Clips vs files......................................................................................................................10
Moving clips along the timeline.........................................................................................11
Using ripple editing while moving clips.........................................................................11
Moving around the timeline...................................................................................................11
Scrolling............................................................................................................................11
Zooming............................................................................................................................11
 “Warping” between zoom levels...................................................................................12
Moving the playhead........................................................................................................12
Scrubbing..........................................................................................................................12
Understanding layers............................................................................................................13
Opacity (how solid “opaque” things are)...........................................................................13
How this translates in terms of user interface..................................................................13
Adding and removing layers.............................................................................................13
What about audio layers?.................................................................................................14
Editing with the timeline............................................................................................................15
Trimming...............................................................................................................................15
Trimming an individual clip...............................................................................................15
Ripple editing....................................................................................................................15
Roll editing........................................................................................................................16
Splitting.................................................................................................................................16
Keyframe curves...................................................................................................................17
General usage..................................................................................................................17
Audio curves.....................................................................................................................17
Video compositing curves.................................................................................................18
Transitions.................................................................................................................................19
Fade-ins and fade-outs.........................................................................................................19
Crossfading clips (PiTiVi 0.13.5 and newer).........................................................................19
Other transitions....................................................................................................................19
Rendering..................................................................................................................................20
Troubleshooting.........................................................................................................................21
Importing errors.....................................................................................................................21
Rendering problems..............................................................................................................21
Sound crackles/choppy audio..........................................................................................21
Rendering does not start..................................................................................................21
Other known problems..........................................................................................................22
Playback is slower than PiTiVi 0.13.3...............................................................................22
About this manual
License
This documentation is licensed under the Creative Commons Attribution
ShareAlike 3.0 license.

Work in progress
You may encounter unwritten portions due to features that have not yet been
implemented in PiTiVi at the time of writing.
You may also encounter smaller areas which have been documented in this
manual but have not been implemented in PiTiVi – those are areas where the
design and expected user interaction are quite narrow/certain.
In both cases, the fact that the feature is not yet implemented will be stated in
gray lettering, perhaps with links to relevant bug reports.

Patches welcome
If you happen to find errors, missing information or unclear passages in this
manual, please feel free to submit corrections. You can find contact
information on my personal website. You can also file bugs on the
“documentation” component in our bug tracker.

About this manual | 1

Introduction
Welcome
PiTiVi is a Free and Open Source nonlinear video editor built upon the
GStreamer multimedia framework.
It aims at being a powerful and flexible video editing solution for both the
novice and the enthusiast. It aims at being enjoyable and efficient to use while
not limiting your creativity. This manual is intended to help you grasp the
concepts behind its design and get productive quickly.

GStreamer and compatibility

A great strength in PiTiVi lies in its use of the GStreamer multimedia
framework. GStreamer is used by dozens of multimedia applications across
desktop environments, operating systems and architectures.
This essentially means three things to you, the user:
• You can, in theory, import pretty much any media file supported by
GStreamer (but see the next section).
• You can render your projects using any supported container and codec
combination from GStreamer.
• You need a very recent version of GStreamer to maximize PiTiVi's
capabilities and reduce the possibilities of bugs. This is because the
PiTiVi project developers work hard in fixing problems directly in
GStreamer (instead of putting temporary workarounds inside PiTiVi).

About “non-compliant” codecs

Some GStreamer codecs, such as the Fluendo MP3 and MPEG muxers,
while providing you with a legal way to playback files (in countries where
software patents laws are upheld), may not be completely compliant to the
GStreamer specifications.
Some users have reported problems when using those codecs (read: not
being able to import MP3 files when those codecs are installed).
The reason for this behavior is that they are codecs oriented towards
playback, and, being not entirely spec-compliant with GStreamer, cannot be
used correctly by PiTiVi for editing.
This situation is unfortunate. If, eventually, those codecs are fixed to become
full-fledged GStreamer-compliant playback and editing codecs, they will work
with PiTiVi.

Introduction | 2
In countries where software patents are not upheld, you can simply use the
GStreamer “ugly” set of plugins.

A word about editing-friendly codecs

Some formats, like MPEG, are oriented towards playback only, and do not
compress each frame independently. While it is the goal of PiTiVi to support
working with these files, certain operations (like rapid seeking) will not
perform as well as they would with frame-independent compressed video
(such as MJPEG or DV).

System requirements
In terms of hardware, video editing typically requires a powerful computer,
depending on the type of video you are editing. While the processing power
of computers has increased tremendously over the years, so has demand for
higher quality video.
Editing HD (High Definition) video usually requires (at the time of this writing)
state of the art hardware (depending on the codec used), while SD (Standard
Definition) video editing can be done on modest hardware configurations. It is
up to you to make sure that your equipment is adequate. It should at least be
able to playback your media in Totem without lagging.
It is possible, however, to use low-quality versions of your footage during
editing and use the high-quality versions when rendering the final output, thus
allowing to bypass hardware limitations to some extent. This is called “proxy
editing”. This feature, however, is not yet available in PiTiVi.

Introduction | 3
An overview of the user interface

Main window

The main window, as the name implies, is the window containing the main
components of the PiTiVi user interface, namely: the menu bar, the toolbars,
the timeline and various customizable components (source list, previewer,
effects list, transitions list, etc.).

Menu bar
The menu bar contains all the possible actions of the toolbars, plus many
more. The menu bar also provides some instant-apply settings, as well as
access to further customizations in the “Project settings” dialog and
“Preferences” dialog.
The menu bar cannot be hidden.

The toolbars
Toolbars provide access to the most commonly used functions of PiTiVi. All
items in toolbars can also be accessed through the menu bar. Toolbars can
be activated or deactivated in the View menu.
You can hover the mouse cursor over a
toolbar item to reveal an information
tooltip regarding its function.

Introduction | 4
Ruler
The ruler plays a crucial role in your interaction with the timeline. In addition
to giving you time measurements (in seconds), it is the primary way of moving
the playhead (and thus, your position in time).
The current playhead position is indicated by a red vertical line:

Technical note: When zoomed in, frames are visually represented on the
ruler as alternating light and dark areas in the bottom part; those are based
on the project framerate settings.

To move your position in time, click anywhere on the ruler. You can also
“scrub” the timeline by clicking on the ruler and holding down the mouse
button while moving. See the Scrubbing section for more details.

Marker bar
Markers are visual cues that you can create to “mark” important points or
regions in your project's timeline. The marker bar allows you to view and edit
markers that you created. See the “Using markers” section of this manual to
learn how to create and manage them. (bug 608682)

Timeline
The timeline is the core user interface component that you will use for editing.
It is a visual, time-proportional representation of your project's chronology.

Playback toolbar
This toolbar, located below the previewer, contains buttons controlling
• The playback of the timeline.
• The playback of a clip being previewed from the source list.
The Play button transforms into a Pause button when playing, and reverts to
a Play button again when not playing.

Previewer
The previewer displays
• Your project's video when playing back.
• The video frame at the current position of the playhead.
• A “live preview” when trimming a clip's beginning/end point.

Introduction | 5
Source list
The source list displays the imported media files in your project. This list is a
flexible database that can be sorted and searched (bug 432664 and 578710).

Introduction | 6
Getting Started
Creating a project
When you initially start PiTiVi, a new blank project is already created. To open
an existing project, use File > Open or press Ctrl+O.
If you currently have an active project and wish to start a new one, use File >
New or press Ctrl+N.

Editing project settings

When starting a new project, you should make sure to go adjust the project
settings, such as framerate, resolution and preferred codecs. The video
resolution will affect the aspect ratio of the previewer.
To edit the project settings, use the Project > Project Settings menu.

Saving a project
To save your project work, use the File > Save menu, the Save button on the
main toolbar or press Ctrl+S.
• Note: a saved project file is not the rendered media file output. To
render your project, see the Rendering section.
When you save a project for the first time, a dialog window appears, asking
you where to save the project file and how to name it.
If you want to save your project as a different file, use File > Save as or press
Ctrl+Shift+S. This can be used to create different versions of your project.

Getting media
Multiple ways of getting media are planned. However, at the time of this
writing, the only supported method is importing files from your hard drive.
It is planned to support the following additional sources in the future:
• Capture from a DV or HDV camcorder using an IEEE 1394 connection.
• Capture from a webcam.
• Dumping a network/Internet stream.
• Importing from DVD.
• Importing from an audio CD.
• Downloading from content providers such as Jamendo, Magnature,
CreativeCommons, etc.

Getting Started | 7
Importing files

Using the file chooser

You can import media into the source list by using the file chooser dialog,
which has the advantage of letting you preview the files you want to import
(bug 586003). To do so, use the Project > Import clips... menu, the Import
clips button on the main toolbar, or press Ctrl+i.
The following file chooser dialog window will appear:

Press Ctrl or Shift to select multiple files at the same time. You can also
import all the files contained in a folder (and its subfolders) by using Project
> Import folder of clips... in the menu bar.

Using drag and drop

The concept of drag and drop is a well-established method of bridging the
gap between software applications. As such, this feature can be used to:
• Quickly and easily import music or video clips from a media player
(such as Rhythmbox or Totem) by dragging them over PiTiVi's source
list.
• Allow using a full-fledged file manager (such as Nautilus, Thunar,
Dolphin or Konqueror) instead of the file chooser dialog.

Getting Started | 8
 • Leverage the searching capability of another application (such as
Rhythmbox, Tracker, GNOME Search Tool, etc.).

Using the source list

Sorting
You can sort your project media by clicking on the columns' headers: (bug
432664)

Previewing a clip from the source list

To preview a clip before placing it on the timeline,
you can double-click on it in the source list, or
right-click and choose “Play clip” from the popup
menu.

Tagging
This feature is not yet implemented (bug 586071).

Quick search
If you want to quickly locate a clip in the source list and know the beginning of
its name, click anywhere in the source list and start typing the name of the file
you're looking for.
• As you type, the first matching file will become selected.
• You can keep typing to refine your search.
• When there are multiple results, you can use the up and down arrow
keys to switch the selection between each search result.
This method only allows searching from the beginning of the filename.

Filtering
This feature is not yet implemented (bug 578710).

View modes
The source list can display your clips in a list (View > Show Clips as a List)
or in an icon view (View > Show Clips as Icons).
The list view mode shows more details about each clip, but the icon view
mode can display more clips without needing to scroll (especially on high
resolution computer monitors).

Getting Started | 9
Making selections

Selecting a single item

To select a file or a clip in PiTiVi, click it.

Selecting multiple items

Multiple selections allow you to apply actions (dragging, deleting, grouping,
etc.) to many clips at once.
Selecting multiple adjacent items:
1. Click the first item.
2. Hold the Shift key.
3. Click the last item.
Selecting multiple nonadjacent items
1. Hold down the Ctrl key.
2. Click on all the items you want to select.
You can deselect an individual item by clicking on it again with the Ctrl key
held down. This can be used in conjunction with the “Selecting multiple
adjacent items” technique above.

Putting media in the timeline

From the source list, you can insert one or more clips by selecting them
(using the Ctrl or Shift keys to select multiple clips) and:
• Dragging and dropping them onto place in the timeline.
• Pressing the Insert (Ins) key or using the Project > Insert at end of
timeline menu. Those clips will be inserted at the end of the timeline.
It is also possible to import files directly into the timeline by dragging them
from another application and dropping them onto PiTiVi's timeline. The files
will automatically be added to the source list in the process. (bug 570118).

Using clips

Clips vs files
• Files are data on your hard disk (videos, music, pictures, etc.) that can
be accessed by PiTiVi and incorporated in your video editing project.
• Clips are a visual representation of your files on the timeline. They
represent the period of time they consume on the timeline and can be
edited independently: each time you drag a file from the source list to

Getting Started | 10
 the timeline, a new clip is created. As such, a file can be reused as
much as you want to create any amount of different clips.
Since PiTiVi is a non-destructive editor, clips are edited, not files. As such,
your files stay intact.

Moving clips along the timeline

You can move a clip within a layer or move it to a different layer.
Click and drag a single clip to move it, and release the mouse button to place
it. Dragging horizontally keeps the clip on the same layer, but dragging it
vertically moves the clip to a different layer.
To move multiple clips at the same time, use the Ctrl or Shift keys to select
multiple clips. Selected clips do not need to be on the same layer. Then, drag
the clips just as you would do for a single clip; their position relative to each
other will be preserved.

Using ripple editing while moving clips

While dragging clips around in the timeline, you can use the ripple technique
to move the “following” clips (the clips that start after the one you're directly
editing) to fill the gap.
1. Click and drag the clip you want to move, with the mouse button held
down
2. During the drag, hold down Shift on the keyboard
3. Release the mouse button to end the drag operation, then release the
Shift key.
During the drag operation, if you changed your mind and only want to drag
one clip at a time, just release the Shift key before you release the mouse
button.

Moving around the timeline

Scrolling
You can use the scrollbars (located on the right and bottom of the timeline),
use the mouse wheel anywhere over the timeline to scroll horizontally, or hold
down the Shift key while using the mousewheel to scroll the timeline layers
vertically.

Zooming
Zooming directly affects your editing accuracy and your ability to move quickly
along the timeline:

Getting Started | 11
 • When zooming in, video clips display more thumbnails and audio clips
display increasingly detailed waveforms, allowing you to do precise
edits.
• Zooming out allows you to scroll faster along the timeline. Zoom can
thus be used in conjunction with scrolling to move quickly between
distant points of your project's chronology.
You can zoom in and out by holding the Ctrl
key while using the mousewheel over the
timeline, using the View > Zoom In and View
> Zoom Out menu items, or dragging the
zoom slider on the left of the ruler.

“Warping” between zoom levels

Using your mouse's scroll wheel, you can also “warp” instantly from any zoom
level to another in a single click. To do that, click with your mousewheel
anywhere on the zoom slider.

Moving the playhead

You can change the position of the playhead by clicking anywhere on the
ruler or on the timeline.
When clicking on the timeline:
• If a clip is under the mouse cursor, it will replace the current clip
selection (see the Selecting multiple items section for more detailed
instructions).
• If there is no clip under the cursor, all selected clips (if any) will be
deselected.
When clicking on the ruler, only the playhead's position changes; clip
selections are not affected.

Scrubbing
Scrubbing is a way of moving the playhead that allows you to:
• Search for a specific position in time by approximation/trial and error.
• Review repeatedly the visual motion in a scene by moving back and
forth in time.
To scrub, click on the ruler and move the mouse with the button still held
down.
You can also scrub by dragging the black vertical line that stems from the
playhead and spans across the timeline.

Getting Started | 12
Understanding layers
Layers are a fundamental concept for advanced editing in the timeline:
compositing, mixing multiple videos simultaneously, and adding titles depend
on this feature.
It is easier to think of layers in terms of images painted on glass. With several
pieces of glass stacked on top of each other, each of these pieces of glass is
a layer. If the top piece of glass is completely painted over, none of the pieces
of glass underneath will be visible.
If, on the other hand, you only paint over a portion of a piece of glass, you will
be able to see what is underneath the non-painted parts.

Opacity (how solid “opaque” things are)

Each layer (and each clip) has its own transparency. To continue the paint on
glass metaphor, if the paint is thin enough, it can be seen through. Visually,
an opacity of 100% means you cannot see the clips below that layer or clip,
and an opacity of of 50% means you can partly see them.

How this translates in terms of user interface

While, in real life, you can stack pieces of glass onto each other in three
dimensions, your computer monitor only has two dimensions. Thus, the
“layers on top” (the “Z” axis in the physical world) are also visually “on top”,
albeit on the “Y” axis.
The following diagram illustrates the “pieces of glass” (left) and how they are
show as “layers” in PiTiVi's user interface (right).

Clips located on a layer above will block the clips below from view, unless it
has an opacity value lower than 100% (as shown with the two topmost layers
in the previous illustration).

Adding and removing layers

Layers are created and removed automatically. There is no “layer
management” interface in PiTiVi (at least, not yet).
To create a layer, drag a clip downwards until a new layer appears for it.

Getting Started | 13
If there are no more clips on a layer, it is automatically removed. Thus, to
remove a layer, simply drag its clips upwards onto another layer.

What about audio layers?

Unlike in vision, multiple sounds do not (objectively) “block” each other. As
such, if you have multiple audio clips on separate layers, their sound will be
mixed together. Controlling the volume of those audio clips simply changes
their relative loudness.

Getting Started | 14
Editing with the timeline
Trimming
Trimming is the act of changing the beginning or end point of a clip in the
timeline.

Trimming an individual clip

Move the mouse cursor over a clip, and trimming handles will appear. Drag
one of the trimming handles on the left or right edge of the clip to trim.

Clips that are grouped together, such as a video clip with its associated audio
clip, will trim in unison when you drag the trimming handles. To trim only the
audio or only the video part, you need to ungroup them first (see the section
on Grouping/linking).

Ripple editing
Ripple edits are a variant of basic trimming which, in addition to trimming a
clip, moves the “following” clips (the clips that start after the one you're
directly editing) to fill the gap.
• Note: the ripple applies to all “following” clips, regardless of whether or
not they are on the same layer.
Before:

After:

To do a ripple edit:
1. Place the mouse cursor on a trimming handle between two adjacent
clips.
2. Press and hold Shift.
3. Drag the trimming handle.

Editing with the timeline | 15

Ripple editing can also be used when moving clips around in the timeline. For
detailed explanations on how to do this, see the section Using ripple editing
while moving clips.

Roll editing
Roll edits are a variant of basic trimming which, in addition to trimming a clip,
trims the adjacent clips to prevent creating gaps.
• Note: the roll applies to all temporally adjacent clips, regardless of
whether or not they are on the same layer.
Before:

After:

To do a roll edit:
1. Place the mouse cursor on a trimming handle between two adjacent
clips.
2. Press and hold Ctrl.
3. Drag the trimming handle.

Splitting
As the name implies, splitting a clip divides it into two adjacent clips, with new
beginning/end points being created accordingly.
In PiTiVi, splitting is a “non-modal” operation; this means that you do not have
to “activate” a particular tool before doing the split action. Splitting occurs
where the playhead is currently located (see also Moving the playhead).
Combined with zooming, frame-by-frame seeking with the keyboard or
scrubbing, modeless splitting is not only fast and efficient, it is also very
accurate.
Selections affect splitting in the following ways:
• Only the selected clips under the playhead will be split.
• If no clips are selected, all the clips under the playhead will be split.

To split a single clip:

1. Click on the clip.
2. Reposition the playhead (if needed).
3. Click on the “Split” button on the timeline toolbar or press S.

Editing with the timeline | 16

To split all the clips across the all layers:
1. Click on a blank area of the timeline (this will deselect all selected
clips, if any).
2. Reposition the playhead (if needed).
3. Click on the “Split” button on the timeline toolbar or press S.
To split multiple selected clips:
1. Position the playhead where you want to split.
2. Add or remove clips to the selection with the Ctrl modifier key. This will
not affect the playhead's position.
3. Click on the “Split” button on the timeline toolbar or press S.

Keyframe curves
Some types of clips (currently only audio clips) support interpolating property
values over their time. The user can add one or more “keyframes” to control
the interpolation, a term borrowed from animation. PiTiVi represents the value
of the property in between keyframes as a “curve” drawn over the clip.
Currently only linear interpolation is supported.

General usage
Curves are an intrinsic property of clips and can not be removed by the user.
The start and end points of the curve are fixed to the start and end points of
the clip, and also can not be removed by the user.
• You can add a new keyframe by double-clicking on an empty portion of
a curve.
• You can remove a keyframe by double-clicking on it.
• You can adjust the time and value of a keyframe by moving it with the
mouse. You can place the keyframe anywhere on the clip you like,
even if this changes the order of the keyframes.
• You can click-and-drag on a segment of a curve between two
keyframes to adjust the vertical position of the segment.

Audio curves
For volume curves the vertical position represents the volume of the clip on a
scale from 0 to 200%.

Editing with the timeline | 17

Video compositing curves
The vertical position represents the alpha (opacity) of the clip on a scale from
0 to 100%. See the “Understanding layers” section for more details.

Editing with the timeline | 18

Transitions
Fade-ins and fade-outs
You can do “fades” of single clip by using PiTiVi's video mixing capabilities,
which relies on keyframes controlling each clip's opacity (see also:
Understanding layers).
To fade a clip to black:
1. Double-click on its opacity keyframe curve where you want the fade-
out to start (or the fade-in to end).

2. Click an drag the last (or first) keyframe of the clip downwards.

Crossfading clips (PiTiVi 0.13.5 and newer)

To do a crossfade between two clips on the same layer, simply drag one of
the clips onto the other so that it overlaps. The overlapping region will be
used for transitions (crossfade by default) between the two clips. You can
adjust the length of the transition by moving or trimming the clips.

Technical note: crossfades are achieved using PiTiVi's video mixing

features, which use keyframes to control the opacity of clips.
This also means that if you set opacity keyframes for that clip, they will be
taken into account for the crossfade.

Other transitions
Other types of transitions (such as wipes) are not yet implemented (bug
#609353).

Transitions | 19
Rendering
Rendering is the process of exporting your project into a new, finalized media
file. Rendering only creates a new “rendered” video file, and does not affect
the project itself; you can still make edits to your project and render again as
many times as needed.
1. From the Project menu, use Render.
2. Adjust the various encoding settings, if needed, to use settings
different from the project settings.
3. Click the Render button.
Note: if your computer is set to suspend or hibernate automatically, PiTiVi will
automatically inhibit the power saving features during the render process (bug
#571885).

Rendering | 20
Troubleshooting
Importing errors
There are currently four known types of errors that can happen when trying to
import files in the source list:
• Timeouts: if a file takes longer than 10 seconds to import, it will be
ignored.
• Broken codec: this could be a broken codec in GStreamer's plugins,
or a codec that is not entirely compliant to PiTiVi's editing
requirements.
• Unsupported file type: PiTiVi being intended for video editing, it can
only import video, audio, and image files.
• Bugs: if none of the above apply, it could be a software bug in
GStreamer or PiTiVi. Look in our current list of bug reports, and if your
case was not already reported, file a bug report.

Rendering problems

Sound crackles/choppy audio

Check if your project audio sample rate is high enough. By default, PiTiVi
renders audio at 44100 Hz. If you have audio content that is sampled at
48000 Hz, simply change the project settings to match the highest sample
rate in your project.
See also bug #589684.

Rendering does not start

Many users have experienced a problem where rendering did not behave
correctly when you loaded a PiTiVi project and tried to render directly, without
seeking (moving the playhead) in the timeline first. This issue (bug #603102)
has been resolved in the development version.
If you are using PiTiVi 0.13.3 or earlier, the workaround is to try moving the
playhead on the timeline after loading a project file. Rendering should then
function normally.
If you are using PiTiVi 0.13.4 or newer, feel free to file a detailed bug report.

Troubleshooting | 21
Other known problems

Playback is slower than PiTiVi 0.13.3

See also: performance problems in 0.13.4.
Some clips (especially in high definition at high frame rates) or combinations
of multiple simultaneous clips may result in slower playback performance.
This is due to video mixing and is known as bug #610626. Any help in
improving performance is welcome.
Another possibility is that your videos are being scaled during playback. Make
sure you have correctly set your project settings to match the resolution
of your clips. A known problem is that playback performance will be severely
impaired if the clips have to be scaled in real time (bug #613416).

Troubleshooting | 22