# The &kdenlive; Handbook

## Introduction

&kapp; is a non-linear video editor for KDE. Please report any problems or feature requests to jasonwood@blueyonder.co.uk

### What is a video editor?

A video editor is an application that allows you to create a new video out of various scenes from one or more other videos.

### What is the difference between linear editing and non-linear editing?

Before editing video on computer was possible, most editing was done on linear editors - these work by having essentially, two video recorders. The first would hold the video that you are editing together, and the second would be used to find the next clip that you want to record. Find a clip, record it, find the next clip, record it. This is called linear editing because the medium of tape forced things to be edited sequentially. If you have edited 10 minutes worth of footage together, and decide that you made a mistake after five minutes, you can't just "push" the last five minutes around to add space for new clips.

Non-linear editing is by far a more flexible way of editing. You can place clips anywhere within your final video (in &kdenlive;, this is represented via the timeline), and you can move them around as much as you want, rearrange them in a completely different order. Best of all, at any point during this you can press play and (with a sufficiently powerful computer) watch back what you have done there and then.

## Quick Start Guide

Ok, so you have started &kdenlive; for the first time and want to dive straight into creating your own video. This quick start guide will take you from start to finish of making your own video.

### The Main Window

When you first start &kdenlive;, you will have a window looking something like this :

The main window

In the default layout, there are three areas of the main window. Whilst all layouts int &kdenlive; are fully configurable, it is assumed for this tutorial that you are using the default layout.

#### The Project Panel

The project panel

The panel to the top left holds various informational and editing panels about the current project. Of most interest to us for this tutorial is the Project List. This window shows which video clips are in the project.

#### The Monitor Panel

The monitor panel

The panel to the top right holds the various monitors that &kdenlive; uses. The workspace monitor displays the final video - what our final edit will look like. The clip monitor is used to preview clips, and to select a section of a clip to add to the timeline.

#### The Timeline

The timeline

The panel at the bottom of the window holds the timeline. The timeline gives you a visual representation of your project, and shows when clips start, when they end, and in the case of overlapping clips, which one will actually be used (whilst the architecture is mostly in place, &kdenlive;/&piave; do not as yet support effects. This will be added in &kdenlive;/&piave; 0.3.0

### Adding clips to your project

Now that you have a little understanding about the layout of &kdenlive;, it is time to add some clips to the project. Now, it goes without saying that to get any further, you will need to have some clips on your computer that you can use. At this moment in time, &kdenlive; does not include capture capabilities, and so you must use another application to get the clips that you want. I recommend Kino, which you can download from http://kino.schirmacher.de/.

Now that you have some clips, you can add them to your project. Select the Project List tab on the project pane, and then right click on it to bring up the context menu. From here, select Add Clips to bring up a standard &kde; open dialog. Find your clips, select as many as you want to add, and they will be added!

Attempting to add some invalid file types to the project may cause the underlying renderer to crash. This is a known bug, if it occurs, then simply save your project (it is safe to do so, although it is recommended that you save as a different filename), close &kdenlive; and restart. See the Known Issues section for more details.

Your added clips will now appear in the project list, along with their duration and a few other pieces of information about them.

The timeline

### Dragging clips to the timeline

Now that you have some clips in your project, it is time to start editing them together into your dream video. There are a two basic ways in which to add a clip to the timeline.

You can drag a clip directly from the project list. Select one of the clips that you have added to the project list, and drag it to the timeline. As soon as the mouse reaches a track, the clip will appear on the track. With this kind of drag, the entire duration of the clip is placed on the timeline. You can then edit the clip from the timeline.

When you click on a clip in the project list, the clip monitor will automatically load the clip. You can then press play on clip monitor and get an idea as to which bits of the clip you actually want on the timeline. Then, position the seek marker to where you want your clip to start and click the "inpoint" button. Move to where you want the clip to end and click the "outpoint" button. Finally, you can drag this cut-down clip by clicking on the video on the clip monitor and dragging to the timeline. The clip that appears on the timeline will be that part of the clip between the in and out points on the monitor.

### Selecting Clips on the Timeline

You can select a clip from the timeline by clicking the left mouse bouton. If you want to add clips to the current selection, hold down Shift while clicking on the clips you want to add. Finally, you can toggle whether a clip is selected or not by holding down Ctrl whilst clicking on it.

### Moving and Resizing Clips on the Timeline

Moving the selected clips around on the timeline is as simple as clicking on them with the left mouse bouton and dragging them around. You can resize clips directly from the timeline. Simply move the mouse cursor to the the beginning or end of the clip you want to resize. Now, click and drag with the left mouse bouton to resize the clip.

Resizing a clip changes it's in and outpoints. If you reselect the clip and look in the clip monitor, you will see that the in and out points on the monitor show the new positions.

It is not possible to resize a clip past it's length - if a clip is 30 seconds in length, then you will not be able to resize the clip so that it finishes playing 35 seconds into the clip!

When you are resizing and moving clips, there is a handy "snap to" feature, which will snap the edges of clips to other clips and the current seek position. This is useful for quickly lining clips up with each other, but in some cases may not be what you want. You can turn this behaviour on and off using the Timeline->Snap To Border menu item.

### Removing clips from the timeline

There are currently two ways to remove a clip from the timeline. The first way is to select the clip or clips that you want to delete, and to press delete.

The second way is to select the clips that you want to delete, and to drag them away from the timeline. As soon as the clips leave the timeline, they will disappear.

It not yet decided if this behaviour is a good thing or a bad thing. It may be removed in later versions of &kdenlive;. You have been warned!

## Using &kdenlive;

### The Project List

The project list shows all of the clips that are available for this project.

You can see the number of times that a particular clip is in use. This includes all usage of the clip - for instance, if a clip is being displayed in the clip monitor, then that counts as one usage for the clip. (FIXME - this behaviour is likely to change in the future).

#### Adding Clips to the Project

If you drag a clip onto the timeline that is not in the project (for instance, if you drag a dv straight from konqueror to &kdenlive;), then it will be automatically added to the project for you.

You can add clips to the projectlist yourself. Either use the project list context menu (right click on the window), or the Project menu on the menu bar. Select 'Add Clips' to bring up a file dialog in which you can select the clip you wish to add to this project. As long as the clips are valid, they will appear in the project list.

#### Deleting clips via the Project List

Delete clips is currently non-functional - the only way to delete clips is to use clean-project.

#### Examining Clip Properties

Clip Properties is currently non-functional - there is no way to examine the format of a clip except by examining the debug output ;-)

#### Clean Project - Removing unused Clips

Use clean project to remove any clips from your project that are currently unused. This is great if your project list has become cluttered and you want to get a concise view of which clips exist. Cleaning a project will not alter your final edit in anyway - the only clips that are removed are those that are no longer in use anywhere.

### The Debug Panel

The Debug Panel

The debug panel is of most use to developers of &kdenlive;. It gives a highly detailed account of what is going on behind the scenes of &kdenlive;. This section will not help you to understand the output of the debug panel, but will tell you why it looks like it is and how to operate it.

On the left, the debug panel shows a list of the renderers in use by &kdenlive;. Each renderer has a name that says which part of &kdenlive; it is used by. There are three such renderers in the current version of &kdenlive;. Clip monitor handles playback of video in the Clip Monitor. Workspace monitor handles playback in the Workspace Monitor. The Document renderer handles all other tasks, such as determining the lengths of video files, and exporting the final video footage.

If you select one of the renderers from the list, the text area will show all debug output from the renderer. For general usage of &kdenlive;, you do not need to understand this, but it is very important when filing bug reports to send a copy of these messages - doing so will better aid us in fixing your problems. Click the Save Messages button to bring up a standard save dialog in which you can save the output.

The Save Messages button will save output for all of the renderers. You do not need to save each renderer's output individually.

There is a checkbox on the debug panel that allows you to turn off the output of the debug messages. This may be necessary on slower machines or if you run &kdenlive; for a long time, as keeping track of the messages does slow &kdenlive; down, and will consume more and more memory the longer that &kdenlive; is running for.

### The Effect List

This is non-functional in the current version of &kdenlive;.

### The Effect Setup Panel

This is non-functional in the current version of &kdenlive;.

### The Timeline

This is...

### The Clip Monitor

This is...

### The Workspace Monitor

The workspace monitor shows the video that is the result of the current timeline. It works in a similar way to the clip monitor.

Inpoints and outpoints on the workspace monitor achieve the same purpose as they do on the clip monitor. You can choose a part of the current timeline, and drag a clip of it back to the timeline. You will get a "project clip", which is a clip that contains all of the clips on the timeline in the state when you made it. It is useful for grouping together a number of clips when you have finished editing them and want to be able to treat them as a single clip.

### Rendering your project

When you have finished editing, you can render your project via the Render->Export Timeline menu. This brings up a dialog, which allows you to choose your export format, export options, and filename to save as.

The rendering project dialog box

The current version of &kdenlive;/&piave; only supports export to raw dv format.

### Loading and Saving your project

Load your project via the File->open menu. Save your project via the File->save-as menu.

### Setup the Renderer

With this dialogbox, you can configre all parameters for the renderer program.

The setup renderer dialog box

## Command Reference

### The main &kdenlive; window

#### The File Menu

Ctrl n File New

- Creates a new document.

Ctrl o File Open

- Open a saved project.

File Open Recent

- Open a recently used project.

Ctrl s File Save

- Saves the project.

File Save As...

- Saves the project under a different filename.

Ctrl q File Quit

- Quits &kapp;

#### The Edit Menu

Ctrl z Edit Undo

- Undo the last edit to the timeline.

Ctrl Shift z Edit Redo

- Redo a previously undone edit to the timeline.

Ctrl x Edit Cut

- Non-functional at present

Ctrl c Edit Copy

- Non-funtional at present.

Ctrl v Edit Paste

- Non-functional at present

#### The Project Menu

Project Add Clips

- Add clips to the project list.

Project Delete Clips

- Delete the selected clip from the project. This deletes all references to the clip, including those on the timeline, or those within composite clips.

Project Clean Project

- Remove unused clips from the project list.

Project Clip Properties

- Non-functional at present

#### The Timeline Menu

q Timeline Move/Resize Tool

- Select the move/resize tool to use on the timeline. This tool lets you move and resize clips on the timeline. It is the standard operating mode of the timeline.

w Timeline Razor Tool

- Select the Razor tool to use on the timeline. This tool will cut (razor) the clip into two pieces at the time selected.

e Timeline Spacer Tool

- Select the Spacer tool to use on the timeline. This tool lets you select all clips to the right of where you click on the timeline.

Timeline Snap To Frames

- If checked, all operations will snap to the nearest frame.

Timeline Snap To Border

- If checked, moving and resizing clips will snap to nearby clip borders and the seek marker.

#### The Render Menu

Render Export Timeline

- Export the timeline to a video clip. Also known as rendering down.

#### The Layout Menu

F9 Layout Menu Load Layout 1

- Loads up a previously saved screen layout.

F10 Layout Menu Load Layout 2

- Loads up a previously saved screen layout.

F11 Layout Menu Load Layout 3

- Loads up a previously saved screen layout.

F12 Layout Menu Load Layout 4

- Loads up a previously saved screen layout.

Ctrl Shift F9 Layout Menu Save Layout 1

- Saves the current screen layout to layout slot 1.

Ctrl Shift F10 Layout Menu Save Layout 2

- Saves the current screen layout to layout slot 2.

Ctrl Shift F11 Layout Menu Save Layout 3

- Saves the current screen layout in layout slot 3.

Ctrl Shift F12 Layout Menu Save Layout 4

- Saves the current screen layout in layout slot 4.

#### The Settings Menu

Settings Show Toolbar

- Show/hide the toolbars.

Settings Show Statusbar

- Show/Hide the status bar.

Settings Configure Shortcuts...

- Configure &kdenlive; keyboard shortcuts.

Settings Configure Toolbars...

- Configure the toolbars.

Settings Configure &kdenlive;...

- Configure &kdenlive;

#### The Help Menu

Help &kdenlive; Handbook

- View the &kdenlive; handbook (this document).

Shift F1 Help What's This?

- After selecting this, click on part of the gui to find out what it does.

Help Report Bug...

- Report a bug about &kdenlive;

Help About &kdenlive;

- See information about &kdenlive;, including the license, authors and contributers.

Help About KDE

- See information about the KDE project.

## Developer's Guide to &kdenlive;

To be written.

## Known Issues, Workarounds and Recovery Procedures

If &kdenlive; or one of the &piave; renderers crashes, it is possible that it will prevent the current or and new copies of &kdenlive; from running correctly.

There are two reasons why this may happen. The first is if one of the &piave; processes did not shut down on the previous run of &kdenlive;. The simple solution to this is to close down &kdenlive; and type from the command line:

    			% killall -9 piave

This will kill any stray &piave; processes, and should allow you to run &kdenlive; normally again.

If you try the above and it says piave:no process killed then it may be that one of the ports that &piave; listens on has not yet been freed after the previous run. Wait for about one minute before starting &kdenlive; again - the TCP port will time out and become usable again.

## Questions and Answers

&reporting.bugs;

What file formats does &kapp; support?

Currently, &kapp; supports playback of AVI files that use the DV codec (other types of AVI file will fail) and Raw DV files. Both of these formats are exported by &kino;.

On a technical note, &kapp; does not provide any video formats itself; all video formats are provided by the backend renderer, &piave;.

When will &kapp; support divx/mpeg files?

Short answer : When somebody codes the relevant plugin for &piave;.

The long answer : Supporting divx files in an editing application is difficult. divx and mpeg formats are not designed for video editing. Some frames contain only part of the information required to display that frame, which makes the random acces required by a video editing application difficult to achieve. There are also quality issues with decompressing and recompressing files that need to be taken into account. For these reasons, support for these formats in &kapp; itself are of low priority compared to the effect framework, the capture program and other such features.

If somebody is interested is adding divx/mpeg support to &kapp; (or to be technically correct, &piave;) then please contact me, and I will point you in the right direction. In the meantime, it is suggested that you capture video directly in Raw DV using &kino;, or convert your files to Raw DV format for use with &kapp;

When will &kapp; support mp3 files and other audio formats?

Sometime in the future, perhaps version 0.4.0 or 0.5.0. The roadmap on the website gives a rough idea of the order in which features are being added to &kapp;. The next priority is the effect framework, which will be the made addition for the 0.3.0 release. Once &kapp; 0.3.0 is released, we will decide on the next most important feature. This may be separate audio tracks.

When I add clips to the project, the times show up as 'unknown'. I know these clips are valid, why does this happen?

This is a sign that something has gone wrong with &piave;. Whilst &kapp; will do it's best to pull itself back into working order, this is still relatively new software and it doesn't manage it as often as one would hope! The best solution is to quit &kapp; (if you have done any work, then you are quite safe to save it), perform the following operation:

    						% killall -9 piave.

Wait a few seconds, and then restart kdenlive.

The &kdenlive; user interface is not keeping up when I play a video! What is wrong?

Go to the debug panel and try checking the Ignore Incoming Messages button. This will turn off output to the debug window, which can slow the interface down considerably whilst playing back videos, especially when they are long in length.

## Credits and License

&kapp;

Program copyright 2002-2003 Jason Wood jasonwood@blueyonder.co.uk

Contributors:

- Caulier Gilles caulier.Gilles@free.fr : &kdenlive; and &piave; i18n, French translations, splashscreen

- Rolf Dubitzky dubitzky@pktw06.phy.tu-dresden.de : &piave; implementations

Documentation copyright 2003 Jason Wood jasonwood@blueyonder.co.uk

&underFDL; &underGPL;

## Installation

### How to obtain &kdenlive;

The &kdenlive; WEB site is http://www.uchian.pwp.blueyonder.co.uk/kdenlive.html. &kdenlive; can be found in the SourceForge project page on http://sourceforge.net/projects/kdenlive/

### Requirements

In order to successfully use &kdenlive;, you need KDE 3.0 or higher. Additionally, you need piave in order to do anthing useful - kdenlive itself is after all, just an interface :-)

All required libraries as well as &kdenlive; itself can be found on or via The &kdenlive; home page.

You can find a list of changes at http://pwp.blueyonder.co.uk/kdenlive.html. FIXME : this link does not actually point at a changelog.

### Compilation and Installation

In order to compile and install &kdenlive; on your system, type the following in the base directory of the &kdenlive; distribution:

                            % ./configure --prefix=`kde-config --prefix`

                            % make

                            % make install

Additional parameters for ./configure script may be required. Type the following in the base directory of the &kdenlive; distribution:

    			% ./configure --help

Since &kdenlive; uses autoconf and automake you should have not trouble compiling it. Should you run into problems please report them to jasonwood@blueyonder.co.uk.

&documentation.index;