project statement download
PIAVE is a render and effect engine, developed and currently running on GNU/Linux. PIAVE can be used in various ways. You can link your own project with libpiave and use its features. The Modesto GUI does this. As a standalone application PIAVE can read the description of a project in VEML format (XML) and start rendering. In server mode, you can connect a client (e.g. a GUI) to PIAVE via a unix or tcp socket and remote control the engine. KdenLive uses this feature.

PIAVE is part of the Modesto project. Check it out on modesto/sourceforge.

A very nice GUI frontend can be found here: KdenLive (or at kdenlive/sourceforge)

In case of problems/bug/comments, please use the kdenlive sourceforge mailing list and look into the archives.

latest version (Mar2004):


Installation instructions:


HTML source documentation:

piave v0.2.3

CVS repository:

modesto CVS

  • 07 Mar 04 : The new release 0.2.4 with fixes for a few nast bugs. This is also the last release before the VEML syntax will be changed in CVS HEAD. So communication between kdenlive and piave HEAD will be broken until both are in sync again.
  • 14 Oct 03 : The new release 0.2.3 contains many merges from the devel branch (AVI, ogg/wav, ieee1394, ...) and many bugfixes from Jason to get piave in sync with the latest release of kdenlive. Both, kdenlive and piave, now come with the release number 0.2.3 which reflects the current sync status.
  • 23 Jun 03 : CAULIER Gilles has added french translations and as a prerequisite the complete i18n infrastructure. If you want to add another translation, there is even a small HOWTO to get you started. Please find it here.
  • 20 May 03 : Opened new branch for development.
    • stable branch: "HEAD" - compatible with kdenlive CVS (today)
    • unstable branch: "V00-03-devel" - will become 0.3.0 when stable
  • 26 Mar 03 : Nothing has changed for a while and since I am in the process of writing up my PhD. Since things are in a somewhat stable state I make a new release (0.2.2) now (what I probably should have done a while ago) and go on from there as soon as I have some time again.
  • 14 Feb 03 : Many bugs have been fixed and it looks like we are almost in sync with KdenLive again. There are still spurious hangs/crashes. All dependencies to libxml++ have been removed. enix support is under development.
  • 26 Jan 03 : The next development step is commited to the HEAD. piave now has a fully fledged plugin interface to handle plugin loading at runtime. This enables the localized handling of capabilities and properties within the plugin. reporting to kdenlive works. Unfortunately the HEAD has some problems in communication with kdenlive, so it is only good for PIAVE testing. I have removed all dependecies to gdk-pixbuf.
  • 13 Jan 03 : 0.2.1 - Today is my birthday. A good day to release the first beta of PIAVE. Please see the features section to see what is already working and the todo/help section to see what is not yet working and where you could help if you want to. 0.1.0 has been skipped to get versioning in sync with KdenLive. See the release notes here.
  • 11 Jan 03 : 0.0.3 - I think I have ironed out most of the bugs introduced with the last feature update. Communication with KdenLive! basically works now for the most important parts. Exporting to raw DV works as long as there are no empty frames in the timeline.
  • 04 Jan 03 : another step towards initial beta release. piave can now parse scenelists by kdenlive. No hardcoded samples anymore. You can add clips in the kdenlive project, cut them, arrange them, and play them. There are a huge number of obivous and not so obvious bugs right now, so many that I won't make a release.
  • 23 Dec 02 : 0.0.2 - simple player and interaction with kdenlive. With exception of the scenelist all vital information can be communicated. The next release will probably be 0.1.0, which is a first usable product. 0.1.0 will allow to get clip arangements in a single track from kdenlive and export them to a raw DV file. Developers wanted!!! (as usual ;-)
  • 04 Aug 02 : 0.0.1 - initial alpha release.
PIAVE is C++ library. The main objects of PIAVE are the class "StoryBoard" and the plugin manager "PluginMgr".

A StoryBoard represents the root of the render tree. The class itself is actually very simple. Only the available collection of nodes, effects, transitions, etc. make it interesting. Each node in the render tree contains inputs and effects. Unary nodes contain a single input and a single effect. Binary nodes contain two inputs A+B and a single effect which operates on both inputs. This can be a transition from A to B or anything else that involves two video inputs. Inputs can either be video files or other nodes. This way you can construct a complete rendertree. In principle it is possible to construct any kind of production this way.

To simplify the tree, it is possible to splitup a production into seperate scenes with no overlapping effects. For many purposes it can be usefull to print aut the render tree (e.g. debugging or save to file etc.). The natural format to do that is XML. Here is an example of a very simple project that just joins several chunks from input files. The object hirachy in memory is translated almost 1:1 to XML:

  <scene duration="0.52" >
   <file name="/scratch/samples/4x3-PAL-1.dv" inpoint="0" />
  <scene duration="0.36" >                                                    
   <file name="/scratch/samples/4x3-PAL-4.dv" inpoint="0.52"  />
  <scene duration="0.44" >                                                    
   <file name="/scratch/samples/4x3-PAL-2.dv" inpoint="0.88" />
A more complex example is the transion from one input to another with an alpha blend. Here is the XML translation for a single scene setup:
  <scene duration="10.0" >
    <effect name="AlphaBlend" inpoint="4.0" outpoint="6.5">
      <input name="A" start="0.0" duration="6.5">
        <file name="/scratch/samples/4x3-PAL-1.dv" inpoint="0"    />
      <input name="B" start="4.0" duration="6.0">
        <file name="/scratch/samples/4x3-PAL-5.dv" inpoint="23.7"    />
        <keyframe time="0.0" value="0.0" />
        <keyframe time="1.0" value="1.0" />
The inpoint/outpoint/start times are always relative to the local time of the parent node. time values for keyframes are always relative to the duration (i.e. outpoint-inpoint) of the effect. The example would show 4 seconds of input A then make a 2.5 second crossfade to input B and show 3.5 more seconds of input B.

The plugin manager handles plugins, of course. PIAVE knows input and output plugins, which can be seen as "file formats", codec plugins, which handle specific video codecs. Effects are plugins as well.

PIAVE is supposed to be used by a GUI to handle the lowlevel video manipulation. Since a central design goal was to completely seperate GUI and render engine, it is necessary to communcate the capabilities of the available plugins to the GUI. PIAVE uses a very simple but powerfull "property tree" for this purpose. The configuration is very similar to an XML tree.
The plugin manager has two duties. First it serves as a register for all available plugins. The GUI can ask the PluginMgr what plugins are available and what cpabilities the plugins have. Second, it is an object factory that can instantiate plugin with certain properties. Here are some code snippets for illustration. First the definition of the plugin. This is taken from the codebase of the SDL plugin. The SDL plugin provides two X11 visuals, one that uses xv extensions, and one that doesn't.

    PropertyNode * caps = new PropertyNode( "outstream" );
    caps->addAttr( "name", getName() );

    PropertyNode * visual = caps->addDaughter( "screen" );
    PropertyNode * display = visual->addDaughter( "X11" );
    display->addAttr( "visual", "xv" );
    display->addAttr( "fallback", "rgb" );

    display = visual->addDaughter( "X11" );
    display->addAttr( "visual", "rgb" );

    PropertyNode * about = caps->addDaughter( "about" );
    about->setContent( "Use SDL to display video. Uses xv overlay if available.\n" );
Translated to XML this would look like:
          <outstream name="SDLStream">
                  <X11 visual="xv" fallback="rgb" />
                  <X11 visual="rgb" />
          Use SDL to display video. Uses xv overlay if available.
And second, somewhere in the GUI or whatever tool you are implementing to work with libpiave, you can use something like the following to get a plugin that provides output to screen. This can be the SDL plugin from above, or any other plugin tet provides the requested features, e.g. a plugin that makes direct use of X extensions to make a YUV overlay.
    /* setup request */
    PropertyNode * screen_caps = new PropertyNode( "outstream" );
    PropertyNode * screen = screen_caps->addDaughter( "screen" );
    PropertyNode * display = screen->addDaughter( "X11" );
    display->addAttr( "visual", "xv" );

    /* try to find a plugin with specified capabilities */
    Plugin * p = PluginMgr::find( screen_caps );
    if ( p ) {
        /* we found a plugin that provides screen output
         * now we can reuse the screen propety to instantiate
         * a plugin of the requested kind/
        screen->addAttr( "width" , 720 );
        screen->addAttr( "height" , 576 );
        PluginBase * b = p->newElement( screen );
The GUI can ask the plugin manager to report available plugins and ask for the capabilities of a plugin. An effect plugin reports which parameters it has. Possible parameters include simple integer or floating point numbers or more complex things like "box on screen" or "color". It is in the responsibility of the GUI to display dialogs for these parameters. The visualization of a "box on screen" might be very different from four generic floats.
This "property tree" can simple be translated to XML. For a simple two-track-effect which can render an alpha blend of two video sources it looks like this:
       <effect name="AlphaBlend">
            <input name="A" video="yes" audio="yes" />
            <input name="B" video="yes" audio="yes" />
            <parameter max="1.0" min="0.0" name="fade" type="double">
       Controls the transparency of video B. At 0.0, video A is completely on screen.
       At 1.0, video B is completely visible.
            <preset name="crossfade">
                    <keyframe time="0.0" value="0.0" />
                    <keyframe time="1.0" value="1.0" />
            <preset name="overlay">
                    <keyframe time="0.0" value="0.5" />
                    <keyframe time="1.0" value="0.5" />
            <preset name="inandout">
                    <keyframe time="0.0" value="0.0" />
                    <keyframe time="0.2" value="1.0" />
                    <keyframe time="0.8" value="1.0" />
                    <keyframe time="1.0" value="0.0" />
       This binary operator can be used to overlay a still images,
       fade in text, cross fade transitions, etc, etc...

You can see, that parameters are not static. You can set keyframes with values. Inbetween the keyframes PIAVE will interpolate the parameter. Times are given relative to the length od the effect.

The seperation of GUI and render engine is brought to a maximum with kdenlive where piave is used as a completely seperate process, a standalone program that executes commands sned by the GUI. It would also be possible to link against libpiave and use the features in a more direct way.

screen shots

KdenLive using piave. piave timeline is hardcoded. no communication with kdenlive.

0.2.0 of KdenLive! and piave. first beta release. clips can be added, cutted, aranged, deleted. the video monitor shows the correct frame. playing with sound works. no transitions/effects. Raw DV files only.
90% runtime loadable plugin interface for iostreams and effects
90% video input - raw DV files at present
95% exporting to raw DV files (PAL only) - no mixed format input
90% still images are handled by gdk-pixbuf. Most ommen formats are supported. Not when in YUV mode
80% transitions and effects are available, but, since they are not yet supported by kdenlive, not all parameters are implemented. The transitions and filters are in a proof of principle state but what is there works nice. The infrastructure is tested and working.
90% communication via VEML to KdenLive is working and the basic functionality is implemented. With this GUI it is possible to cut and arange DV files. capabilitieas are not yet reported. Effects and effect parameters are not yet specified.
todo (help!)
0% ieee1394 to control DV cams and grab video
10%ffmpeg / xine-lib / aRts::video - support decoding of other file formats
10%ffmpeg - support encoding of other file formats
0% wav / mp3 / etc. sound support for sound tracks
20%handle sound independent of video
0% field based effect rendering





  • mplayer the reference. What mplayer can't play is probably no video.
  • XINE nicer code base than mplayer, not as complete, no encoding.
  • Ogle DVD Player why can't they spend an afternoon for a less crappy GUI?
  • VideoLan libdvdcss!



  • effectv filters and effects (works in GStreamer)
  • jahshakafx Real Time effects in OpenGL/ML


  • avifile home of aviplay, avimerge, avisplit
  • smilutilshome of smil2raw, smil2yuv, smil2wav. Use with kino-smil.
  • mjpeg-tools home of divxdec lav2yuv lavvideo mpeg2enc mpegtranscode yuv2divx yuv2lav yuvdenoise yuvkineco yuvmedianfilter yuvplay yuvscaler yuvycsnoise
  • dv2jpg you can feed the output to mjpeg-tools



Rolf Dubitzky,