<h1>NOTICE!!</h1>
<h1>This file is deprecated, please see the user's guide for the most
recent information.</h1>
<p>
<h1>LADSPA Support HOWTO</h1>

<h2>Ladspa Plugins</h2>
Ladspa is a relatively new simple audio plugin architecture.  This standard is
open, and aims to enable linux audio applications to share audio plugins.  
GDAM has preliminary support for both loading ladspa plugins and creating
them from mininetwork layouts.
<P>

<h2>How to install ladspa</h2>
<ul>
<li>
<a href="http://www.muse.demon.co.uk/ladspa.html">Download</a> the LADSPA SDK.
<li>
Copy the ladspa.h to <tt>/usr/local/include</tt>.
</ul>

Note:  you must do this BEFORE you configure GDAM - otherwise
it will automatically compile without LADSPA support.
<p>
The packages should ALWAYS include LADSPA support.
<p>
However, even with the packages, you will need ladspa.h to
compile new plugins.

<h2>How to install ladspapluginmaker</h2>
Currently, the latest version is 
<a href="http://www.ffem.org/gdam/download/ladspapluginmaker-0.0e.tar.gz">
ladspapluginmaker-0.0e
</a>.
More packages are available on the <a href="download.html">download page</a>.

<h1>How to write LADSPA plugins using GDAM</h1>
<h2>Overview</h2>

The procedure has two steps:
<ol>
<li>Create a flow graph graphically using GDAM (inside the mininetwork
    filter).  Save it to XML.
<li>Convert the XML to a LADSPA plugin using <tt>ladspapluginmaker</tt>.
    Usually this will convert the xml to C code, then it runs the compiler.
</ol>


<h2>Using the mininetwork</h2>
The mininetwork has many types of "nodes"
which you can create, delete, and connect.
<br>
Here is the example we will use throughout:
<center>
  <img src="http://www.ffem.org/gdam/ladspa/mininet.jpg" alt="Screenshot of the Mininetwork Widget"
       width="492" height="708">
</center>
This actually sounds like a plucked string filter.
(I'll describe it a bit more below).
<br>
You can see it contains a bunch of nodes
which are connected.
<br>
You can drag them around, and drag pipes from inputs to outputs.
Here are exactly what the various mouse buttons do:
<ul>
<li>left mouse button:
    <ul>
    <li> if you clicked on a node's input or output, you may
         drag a pipe to another node's input or output. (you must
	 connect inputs to outputs though!).
    <li> if you clicked on a node,
    you may drag it, and it will be selected.  When it is selected,
    a menu of adjustable parameters appears. (eg for the gain filter,
    a gain slider appears in that window.)
    <li> if you clicked outside a node, a new unconnected node is formed.
    </ul>
<li>middle:
    <ul>
    <li>if you clicked on a node, it is deleted, but its
    inputs are attached to its outputs.
    <li>if you clicked on a pipe,
    a new node is formed in the middle of the pipe,
    properly connected.
    </ul>
<li>right:
    <ul>
    <li>if you clicked on a node, it and all its pipes will be deleted.
    <li>if you clicked on a pipe, it will be deleted.
    </ul>
</ul>

<br>
The inputs to each node are on the top of the node --
each node has only one output, but you can connect an
arbitrary number of things to that output.
<br>
Here are some common nodes:
<ul>
<li>
   <img src="http://www.ffem.org/gdam/ladspa/mix.jpg" alt="mix node">:
      the mix.
      <br>
      This just adds all its inputs together.

<li>
   <img src="http://www.ffem.org/gdam/ladspa/modulator.jpg" alt="modulator">:
   the modulator.
   <br>
   This multiplies its inputs like a ring modulator.
   Or equivalently it is a variable gain.

<li>
   <img src="http://www.ffem.org/gdam/ladspa/gain.jpg" alt="gain node">:
   constant gain.
   <br>
   This multiplies its single input by a constant value.

<li>
   <img src="http://www.ffem.org/gdam/ladspa/delay.jpg" alt="delay node">:
   constant delay.
   <br>
   This delays its input for a certain number of samples.
   [in the gui, you can change the constant, but it is constant once
   it is converted to a LADSPA plugin].

<li>
   <img src="http://www.ffem.org/gdam/ladspa/variabledelay.jpg" alt="variable delay node">:
   <br>
   This delays its input for a number of samples, which is computed
   from another nodes output.
   <br>
   The actual delay at any time is given by:

   <center>
   delay = (base_delay) + (delay_fluctuation * input_value)
   </center>

   where the input_value is from the delay-input (which is the top-right
   connector on the variable delay).

<li>
   <img src="http://www.ffem.org/gdam/ladspa/input.jpg" alt="input">:
   the input to the filter.
   <br>
   You cannot create new inputs or destroy the existing one.

<li>
   <img src="http://www.ffem.org/gdam/ladspa/output.jpg" alt="output">:
   the output from the filter.
   <br>
   You cannot create new outputs or destroy the existing one.
</ul>

<h3>Brief digression into plucked string</h3>

So the plucked string is basically a feedback of the tuning
frequency with a lowpass filter.
<ul>
<li>In the upper-left corner, the input is revolumized (by a modulator)
with a control node (at left).  This implements the input gain slider.
<li>In the mix in the center is the mix which is collecting feedback.
<li>The right side is the feedback loop.  It is revolumized
to control how loud the reverb should be.
<li>The two lower-right nodes implement a very simple lowpass
filter that just averages the last two samples.
</ul>
This is usually called a Karplus-Strong string filter.

<h2>Saving it</h2>
You just press the save button, at the left.
It will prompt you for a filename -- you'll
have to specify it in the next step.

<h2>Converting it</h2>
Download and build <tt>ladspapluginmaker</tt>.

Suppose you saved the mininetwork as <a href="http://www.ffem.org/gdam/examples/pluckedstring.xml">pluckedstring.xml</a>.
Then you would run the following command:
<pre>
	ladspapluginmaker --input pluckedstring.xml \
	                  --output output_dir \
			  --class PluckedString \
			  --basename pluckedstring \
			  --description "Karplus-Strong Plucked String" \
			  --unique-id 10 \
			  --build
</pre>
<p>
The <tt>--unique-id</tt> deserves brief mention.
<br>
        Currently all plugins are centrally allocated
        by talking to Richard Furse &lt;richard@muse.demon.co.uk&gt;.
        He will assign you a list of UniqueIDs.
        In the interim, you can use ids &lt;4000 for development
        purposes.
<p>
(TODO: put more of these options in the xml!)

<br>
This will create a directory <tt>output_dir</tt> with
three files in it:
<ul>
<li><a href="http://www.ffem.org/gdam/examples/pluckedstring.c">output_dir/pluckedstring.c</a> - the c file implementing the plugin
<li><a href="http://www.ffem.org/gdam/examples/pluckedstring.h">output_dir/pluckedstring.h</a> - the h file with the instance structure
(which is named <tt>PluckedString</tt>) in it.
<li>output_dir/pluckedstring.so - the library we obtained by compiling
the above source files.
</ul>

<h2>Loading LADSPA Filters with GDAM</h2>
GDAM automatically scans for LADSPA plugins when it
starts up.  It looks in <tt>/usr/lib/ladspa</tt>
and <tt>/usr/local/lib/ladspa</tt>.  It will
write a summary file to <tt>~/.gdam/ladspa.xml</tt>.

This is what the loaded plugin looks like:
<center>
<img src="http://www.ffem.org/gdam/ladspa/ladspa.jpg" alt="ladspa plugin screenshot" width="363" heigth="394">
</center>
