PiTiVi

Quick Start Manual

Version 0.13.4 development version By Jean-Franois Fortin Tam last revised October 23, 2011

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. In countries where software patents are not upheld, you can simply use the GStreamer ugly set of plugins. Introduction | 2

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.

An overview of the user interface

Main window

Introduction | 3

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.

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)

Introduction | 4

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.

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 | 5

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 | 6

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 | 7

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 | 8

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 | 9

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 | 10

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 | 11

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 | 12

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 | 13

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 | 14

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 | 15

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 | 16

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 | 17

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 fadeout 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 | 18

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 | 19

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 | 20

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 | 21