Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 864 insertions, 0 deletions

diff --git a/doc/artsbuilder/artsbuilder.docbook b/doc/artsbuilder/artsbuilder.docbook
new file mode 100644
index 00000000..b5f4f68c
--- /dev/null
+++ b/doc/artsbuilder/artsbuilder.docbook
@@ -0,0 +1,864 @@
+<chapter id="artsbuilder">
+<title>&arts-builder;</title>
+
+<sect1 id="overview">
+<title>Overview</title>
+
+<para>
+First of all, when trying to run &arts-builder; , you should also be
+running the sound server (&artsd;). Usually, when you use &kde; 2.1,
+this should already be the case. If not, you can configure the automatic
+sound server startup in &kcontrol; under
+<menuchoice><guilabel>Sound</guilabel><guilabel>Sound
+Server</guilabel></menuchoice>.
+</para>
+
+<para>
+When you are running &arts;, it always runs small modules. &arts-builder;
+is a tool to create new structures of small connected modules. You
+simply click the modules inside the grid. To do so, choose them from the
+<guimenu>Modules</guimenu> menu, and then click somewhere in the
+green-gray plane.
+</para>
+
+<para>
+Modules usually have ports (where usually audio signals are flowing in
+or out). To connect two ports, click on the first, which causes it to
+turn orange, and then click on the second. You can only connect an input
+port (on the upper side of a module) with an output port (on the lower
+side of a module). If you want to assign a fixed value to a port (or
+disconnect it), do so by double clicking on the port.
+</para>
+
+</sect1>
+
+<sect1 id="artsbuilder-tutorial">
+<title>Tutorial</title>
+
+<sect2 id="step-1">
+<title>Step 1</title>
+
+<para>
+Start &arts-builder;.
+</para>
+
+<para>
+You need a Synth&lowbar;AMAN&lowbar;PLAY-module to hear the output you
+are creating. So create a Synth&lowbar;AMAN&lowbar;PLAY-module by
+selecting <menuchoice><guimenu>Modules</guimenu>
+<guisubmenu>Synthesis</guisubmenu> <guisubmenu>SoundIO</guisubmenu>
+<guisubmenu>Synth&lowbar;AMAN&lowbar;PLAY</guisubmenu></menuchoice> and
+clicking on the empty module space. Put it below the fifth line or so,
+because we'll add some stuff above.
+</para>
+
+<para>
+The module will have a parameter <parameter>title</parameter> (leftmost
+port), and <parameter>autoRestoreID</parameter> (besides the leftmost
+port) for finding it. To fill these out, doubleclick on these ports,
+select constant value and type <userinput>tutorial</userinput> in the
+edit box. Click <guibutton>OK</guibutton> to apply.
+</para>
+
+<para>
+Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute
+structure</guimenuitem> </menuchoice>. You will hear absolutely
+nothing. The play module needs some input yet... ;) If you have listened
+to the silence for a while, click <guibutton>OK</guibutton> and go to
+Step 2
+</para>
+</sect2>
+
+<sect2 id="step-2">
+<title>Step 2</title>
+
+<para>Create a Synth&lowbar;WAVE&lowbar;SIN module (from <menuchoice>
+<guimenu>Modules</guimenu> <guimenuitem>Synthesis</guimenuitem>
+<guimenuitem>Waveforms</guimenuitem></menuchoice>) 
+and put it above the Synth&lowbar;AMAN&lowbar;PLAY module. (Leave one line
+space in between).
+</para>
+
+<para>
+As you see, it produces some output, but requires a
+<guilabel>pos</guilabel> as input. First lets put the output to the
+speakers. Click on the <guilabel>out</guilabel> port of the
+Synth&lowbar;WAVE&lowbar;SIN and then on the <guilabel>left</guilabel>
+port of Synth&lowbar;AMAN&lowbar;PLAY. Voila, you have connected two
+modules.
+</para>
+
+<para>
+All oscillators in &arts; don't require a frequency as input, but a
+position in the wave. The position should be between 0 and 1, which maps
+for a standard Synth&lowbar;WAVE&lowbar;SIN object to the range
+0..2*pi. To generate oscillating values from a frequency, a
+Synth&lowbar;FREQUENCY modules is used.
+</para>
+
+<para>
+Create a Synth&lowbar;FREQUENCY module (from <menuchoice>
+<guimenu>Modules</guimenu> <guimenu>Synthesis</guimenu>
+<guimenu>Oscillation &amp; Modulation</guimenu> </menuchoice>) and
+connect it's <quote>pos</quote> output to the <quote>pos</quote> input
+of your Synth&lowbar;WAVE&lowbar;SIN. Specify the frequency port of the
+FREQUENCY generator as constant value 440.
+</para>
+
+
+<para>
+Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute
+structure</guimenuitem></menuchoice>. You will hear a sinus wave at 440
+Hz on one of your speakers. If you have listened to it for a while,
+click <guibutton>OK</guibutton> and go to Step 3.
+</para>
+
+</sect2>
+
+<sect2 id="step-3">
+<title>Step 3</title>
+
+<para>
+Ok, it would be nicer if you would hear the sin wave on both speakers.
+Connect the right port of Synth&lowbar;PLAY to the outvalue of the
+Synth&lowbar;WAVE&lowbar;SIN as well.
+</para>
+
+<para>Create a Synth&lowbar;SEQUENCE object (from
+<menuchoice><guimenu>Modules</guimenu>
+<guisubmenu>Synthesis</guisubmenu><guisubmenu>Midi &amp;
+Sequencing</guisubmenu></menuchoice>). It should be at the top of the
+screen. If you need more room you can move the other modules by
+selecting them (to select multiple modules use &Shift;), and dragging
+them around.
+</para>
+
+<para>
+Now connect the frequency output of Synth&lowbar;SEQUENCE to the
+frequency input of the Synth&lowbar;FREQUENCY module. Then specify the
+sequence speed as constant value 0.13 (the speed is the leftmost port).
+</para>
+
+<para>
+Now go to the rightmost port (sequence) of Synth&lowbar;SEQUENCE and
+type in as constant value <userinput>A-3;C-4;E-4;C-4;</userinput> this
+specifies a sequence. More to that in the Module Reference.
+</para>
+
+<note>
+<para>Synth&lowbar;SEQUENCE really <emphasis>needs</emphasis> a sequence
+and the speed. Without that you'll perhaps get core dumps.
+</para>
+</note>
+
+<para>
+Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute
+Structure</guimenuitem></menuchoice>.  You will hear a nice sequence
+playing.  If you have enjoyed the feeling, click
+<guibutton>OK</guibutton> and go to Step 4.
+</para>
+</sect2>
+
+<sect2 id="step-4">
+<title>Step 4</title>
+
+<para>Create a Synth&lowbar;PSCALE module (from
+<menuchoice><guimenu>Modules</guimenu>
+<guisubmenu>Synthesis</guisubmenu> <guisubmenu>Envelopes</guisubmenu>
+</menuchoice>). Disconnect the outvalue of the SIN wave by doubleclicking it
+and choosing <guilabel>not connected</guilabel>. Connect
+</para>
+
+<orderedlist><listitem>
+<para>The SIN outvalue to the PSCALE invalue</para>
+</listitem>
+<listitem>
+<para>The PSCALE outvalue to the AMAN_PLAY left</para>
+</listitem>
+<listitem>
+<para>The PSCALE outvalue to the AMAN_PLAY right</para>
+</listitem>
+<listitem>
+<para>The SEQUENCE pos to the PSCALE pos</para>
+</listitem>
+</orderedlist>
+
+<para>
+Finally, set the PSCALE top to some value, for instance 0.1.
+</para>
+
+<para>
+How that works now: The Synth&lowbar;SEQUENCE gives additional
+information about the position of the note it is playing right now,
+while 0 means just started and 1 means finished. The Synth&lowbar;PSCALE
+module will scale the audio stream that is directed through it from a
+volume 0 (silent) to 1 (original loudness) back to 0 (silent). According
+to the position. The position where the peak should occur can be given
+as pos. 0.1 means that after 10&percnt; of the note has been played, the
+volume has reached its maximum, and starts decaying afterwards.
+</para>
+
+
+<para>Select <menuchoice><guimenu>File</guimenu><guimenuitem>Execute
+Structure</guimenuitem></menuchoice>.  You will hear a nice sequence
+playing.  If you have enjoyed the feeling, click
+<guibutton>OK</guibutton> and go to Step 5.
+</para>
+
+</sect2>
+
+<sect2 id="step-5-starting-to-beam-data-around">
+<title>Step 5: Starting to beam data around ;)</title>
+
+<para>Start another &arts-builder;</para>
+
+<para>
+Put a Synth&lowbar;AMAN&lowbar;PLAY into it, configure it to a sane
+name. Put a Synth&lowbar;BUS&lowbar;DOWNLINK into it and:</para>
+
+<orderedlist>
+<listitem>
+<para>
+Set Synth&lowbar;BUS&lowbar;DOWNLINK bus to audio (that is just a name,
+call it fred if you like)
+</para>
+</listitem>
+<listitem>
+<para>
+Connect Synth&lowbar;BUS&lowbar;DOWNLINK left to
+Synth&lowbar;AMAN&lowbar;PLAY left
+</para>
+</listitem>
+<listitem>
+<para>
+Connect Synth&lowbar;BUS&lowbar;DOWNLINK right to
+Synth&lowbar;AMAN&lowbar;PLAY right
+</para>
+</listitem>
+</orderedlist>
+
+<para>
+Start executing the structure. As expected, you hear nothing, ... not
+yet.
+</para>
+
+<para>
+Go back to the structure with the Synth&lowbar;WAVE&lowbar;SIN stuff and
+replace the Synth&lowbar;AMAN&lowbar;PLAY module by an
+Synth&lowbar;BUS&lowbar;UPLINK, and configure the name to audio (or fred
+if you like). Deleting modules works with selecting them and choosing
+<menuchoice><guimenu>Edit</guimenu>
+<guimenuitem>delete</guimenuitem></menuchoice> from the menu (or
+pressing the <keycap>Del</keycap> key).
+</para>
+
+<para>
+Hit <menuchoice><guimenu>File</guimenu> <guilabel>Execute
+structure</guilabel></menuchoice>. You will hear the sequence with
+scaled notes, transported over the bus.
+</para>
+
+<para>
+If you want to find out why something like this can actually be useful,
+click <guibutton>OK</guibutton> (in the &arts-builder; that is executing
+the Synth&lowbar;SEQUENCE stuff, you can leave the other one running)
+and go to Step 6.
+</para>
+</sect2>
+
+<sect2 id="step-6-beaming-for-advanced-users">
+<title>Step 6: Beaming for advanced users</title>
+
+<para>
+Choose <menuchoice><guimenu>File</guimenu><guimenuitem>Rename</guimenuitem>
+</menuchoice> structure from the menu of the artsbuilder which
+contains the Synth&lowbar;SEQUENCE stuff, and call it tutorial. Hit
+<guibutton>OK</guibutton>.
+</para>
+
+<para>
+Choose <menuchoice><guimenu>File</guimenu> <guimenuitem>Save</guimenuitem>
+</menuchoice>
+</para>
+
+<para>
+Start yet another &arts-builder; and choose
+<menuchoice><guimenu>File</guimenu><guimenuitem>Load</guimenuitem>
+</menuchoice>, and load the tutorial again.
+</para>
+
+<para>
+Now you can select
+<menuchoice><guimenu>File</guimenu><guimenuitem>Execute
+structure</guimenuitem> </menuchoice>in both &arts-builder;s having that
+structure. You'll now hear two times the same thing. Depending on the
+time when you start it it will sound more or less nice.
+</para>
+
+<para>
+Another thing that is good to do at this point in time is: start
+&noatun;, and play some <literal role="extension">mp3</literal>. Start
+&artscontrol;. Go to
+<menuchoice><guimenu>View</guimenu><guimenuitem>View audio
+manager</guimenuitem></menuchoice>. What you will see is &noatun; and
+your <quote>tutorial</quote> playback structure playing something. The
+nice thing you can do is this: doubleclick on &noatun;. You'll now get a
+list of available busses. And see? You can assign &noatun; to send it's
+output via the audio bus your tutorial playback structure provides.
+</para>
+</sect2>
+
+<sect2 id="step-7-midi-synthesis">
+<title>Step 7: Midi synthesis</title>
+
+<para>
+Finally, now you should be able to turn your sin wave into an real
+instrument. This only makes sense if you have something handy that could
+send &MIDI; events to &arts;. I'll describe here how you can use some
+external keyboard, but a midibus aware sequence like &brahms; will work
+as well.
+</para>
+
+<para>
+First of all, clean up on your desktop until you only have one
+&arts-builder; with the sine wave structure running (not executing).
+Then, three times go to <menuchoice><guimenu>Ports</guimenu>
+<guisubmenu>Create IN audio signal</guisubmenu></menuchoice>, and three
+times to <menuchoice><guimenu>Ports</guimenu> <guisubmenu>Create OUT
+audio signal</guisubmenu></menuchoice>. Place the ports somewhere.
+</para>
+
+<para>
+Finally, go to <menuchoice><guimenu>Ports</guimenu> <guilabel>Change
+positions and names</guilabel></menuchoice> and call the ports
+frequency, velocity, pressed, left, right, done.
+</para>
+
+<para>
+Finally, you can delete the Synth&lowbar;SEQUENCE module, and rather
+connect connect the frequency input port of the structure to the
+Synth&lowbar;FREQUENCY frequency port. Hm. But what do do about
+pos?</para> <para>We don't have this, because with no algorithm in the
+world, you can predict when the user will release the note he just
+pressed on the midi keyboard. So we rather have a pressed parameter
+instead that just indicates wether the user still holds down the
+key. (pressed = 1: key still hold down, pressed = 0: key
+released)
+</para>
+
+<para>
+That means the Synth&lowbar;PSCALE object also must be replaced
+now. Plug in a Synth&lowbar;ENVELOPE&lowbar;ADSR instead (from
+<menuchoice><guimenu>Modules</guimenu>
+<guisubmenu>Synthesis</guisubmenu> <guisubmenu>Envelopes</guisubmenu>
+</menuchoice>).  Connect:
+</para>
+
+<orderedlist>
+<listitem>
+<para>The pressed structure input to the ADSR active</para>
+</listitem>
+<listitem>
+<para>The SIN outvalue to the ADSR invalue</para>
+</listitem>
+<listitem>
+<para>The ADSR outvalue to the left structure output</para>
+</listitem><listitem>
+<para>The ADSR outvalue to the right structure output</para>
+</listitem>
+</orderedlist>
+
+<para>
+Set the parameters attack to 0.1, decay to 0.2, sustain to 0.7, release
+to 0.1.
+</para>
+
+<para>
+Another thing we need to think of is that the instrument structure
+somehow should know when it is ready playing and then be cleaned up,
+because otherwise it would be never stopped even if the note has been
+released. Fortunately, the ADSR envelope knows when the will be nothing
+to hear anymore, since it anyway scales the signal to zero at some point
+after the note has been released.
+</para>
+
+<para>
+This is indicated by setting the done output to 1. So connect this to
+the done output of the structure. The structure will be removed as soon
+as done goes up to 1.
+</para>
+
+<para>
+Rename your structure to instrument_tutorial (from <menuchoice><guimenu>
+File</guimenu> <guimenuitem>Rename
+structure</guimenuitem></menuchoice>. Then, save it using save as (the
+default name offered should be instrument_tutorial
+now).</para><para>Start artscontrol, and go to
+<menuchoice><guimenu>View</guimenu><guimenuitem>Midi
+Manager</guimenuitem></menuchoice>, and choose
+<menuchoice><guimenu>Add</guimenu><guimenuitem>aRts Synthesis Midi
+Output</guimenuitem></menuchoice>.  Finally, you should be able to
+select your instrument (tutorial) here.
+</para>
+
+<para>
+Open a terminal and type
+<userinput><command>midisend</command></userinput>. You'll see that
+<command>midisend</command> and the instrument are listed now in the
+&arts; &MIDI; manager.  After selecting both and hitting
+<guibutton>connect</guibutton>, we're finally done. Take your keyboard
+and start playing (of course it should be connected to your computer).
+</para>
+</sect2>
+
+<sect2 id="suggestions">
+<title>Suggestions</title>
+
+<para>
+You now should be able to work with &arts;. Here are a few tips what you
+could try to improve with your structures now:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+Try using other things than a SIN wave. When you plug in a TRI wave, you
+will most likely think the sound is not too nice. But try appending a
+SHELVE&lowbar;CUTOFF filter right after the TRI wave to cut the
+frequenciesabove a certain frequency (try something like 1000 Hz, or
+even better two times the input frequency or input frequency+200Hz or
+something like that).
+</para>
+</listitem>
+<listitem>
+<para>
+Try using more than one oscillator. Synth&lowbar;XFADE can be used to
+cross fade (mix) two signals, Synth&lowbar;ADD to add them.
+</para>
+</listitem>
+<listitem>
+<para>
+Try setting the frequencies of the oscillators to not exactly the same
+value, that gives nice oscillations.
+</para>
+</listitem>
+<listitem>
+<para>
+Experiment with more than one envelope.
+</para>
+</listitem>
+<listitem>
+<para>
+Try synthesizing instruments with different output left and right.
+</para>
+</listitem>
+<listitem>
+<para>
+Try postprocessing the signal after it comes out the bus downlink.  You
+could for instance mix a delayed version of the signal to the original
+to get an echo effect.
+</para>
+</listitem>
+<listitem>
+<para>
+Try using the velocity setting (its the strength with which the note has
+been pressed, you could also say volume). The special effect is always
+when this not only modifies the volume of the resulting signal, but as
+well the sound of the instrument (for instance the cutoff frequency).
+</para>
+</listitem>
+<listitem>
+<para>...</para>
+</listitem>
+</itemizedlist>
+
+<para>
+If you have created something great, please consider providing it for
+the &arts; web page. Or for inclusion into the next release.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="artsbuilder-examples">
+<title>Examples</title>
+
+<para>
+&arts-builder; comes with several examples, which can be opened through
+<menuchoice><guimenu>File</guimenu><guimenuitem>Open
+Example...</guimenuitem> </menuchoice>. Some of them are in the
+folder, some of them (which for some reason don't work with the
+current release) are left in the todo folder.
+</para>
+<para>
+The examples fall into several categories:
+</para>
+
+<itemizedlist>
+<listitem>
+<para>
+Standalone examples illustrating how to use each of the built-in
+arts modules (named <filename>example_*.arts</filename>). These
+typically send some output to a sound card.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Instruments built from lower level arts modules (named
+<filename>instrument_*.arts</filename>). These following a standard
+convention for input and output ports so they can be used by the &MIDI;
+manager in &artscontrol;.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Templates for creating new modules (names
+<filename>template_*.arts</filename>).
+</para>
+</listitem>
+
+<listitem>
+<para>
+Effects which can be used as reusable building blocks (named
+<filename>effect_*.arts</filename>) [ all in todo ]
+</para>
+</listitem>
+
+<listitem>
+<para>
+Mixer elements used for creating mixers, including graphical
+controls (named <filename>mixer_element_*.arts</filename>). [ all in todo ]
+</para>
+</listitem>
+
+<listitem>
+<para>
+Miscellaneous modules that don't fit into any of the above categories.
+</para>
+</listitem>
+</itemizedlist>
+
+<variablelist>
+<title>Detailed Description Of Each Module:</title>
+<varlistentry>
+<term><filename>example_stereo_beep.arts</filename></term>
+<listitem>
+<para>
+Generates a 440Hz sine wave tone in the left channel and an 880Hz sine
+wave tone in the right channel, and sends it to the sound card
+output. This is referenced in the &arts; documentation.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_sine.arts</filename></term>
+<listitem>
+<para>
+Generates a 440 Hz sine wave.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_pulse.arts</filename></term>
+<listitem>
+<para>
+Generates a 440 Hz pulse wave with a 20% duty cycle.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_softsaw.arts</filename></term>
+<listitem>
+<para>
+Generates a 440 Hz sawtooth wave.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_square.arts</filename></term>
+<listitem>
+<para>
+Generates a 440 Hz square wave.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_tri.arts</filename></term>
+<listitem>
+<para>
+Generates a 440 Hz triangle wave.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_noise.arts</filename></term>
+<listitem>
+<para>
+Generates white noise.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_dtmf1.arts</filename></term>
+<listitem>
+<para>
+Generates a dual tone by producing 697 and 1209 Hz sine waves, scaling
+them by 0.5, and adding them together. This is the DTMF tone for the
+digit "1" on a telephone keypad.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_atan_saturate.arts</filename></term>
+<listitem>
+<para>
+Runs a triangle wave through the atan saturate filter.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_autopanner.arts</filename></term>
+<listitem>
+<para>
+Uses an autopanner to pan a 400 Hz sine wave between the left and right
+speakers at a 2 Hz rate.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_brickwall.arts</filename></term>
+<listitem>
+<para>
+Scales a sine wave by a factor of 5 and then runs it through a brickwall
+limiter.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_bus.arts</filename></term>
+<listitem>
+<para>
+Downlinks from a bus called <quote>Bus</quote> and uplinks to the bus
+<quote>out_soundcard</quote> with the left and right channels reversed.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_cdelay.arts</filename></term>
+<listitem>
+<para>
+Downlinks from a bus called <quote>Delay</quote>, uplinks the right
+channel through a 0.5 second cdelay, and the left channel unchanged. You
+can use &artscontrol; to connect the effect to a sound player and
+observe the results.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_delay.arts</filename></term>
+<listitem>
+<para>
+This is the same as <filename>example_cdelay.arts</filename> but used
+the delay effect. 
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_capture_wav.arts</filename></term>
+<listitem>
+<para>
+This uses the Synth_CAPTURE_WAV to save a 400 Hz sine wave as a wav
+file. Run the module for a few seconds, and then examine the file
+created in <filename class="directory">/tmp</filename>. You can play the
+file with a player such as <application>kaiman</application>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_data.arts</filename></term>
+<listitem>
+<para>
+This uses the Data module to generate a constant stream of the value
+<quote>3</quote> and sends it to a Debug module to periodically display
+it. It also contains a Nil module, illustrating how it can be used to do
+nothing at all.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_adsr.arts</filename></term>
+<listitem>
+<para>
+Shows how to create a simple instrument sound using the Envelope Adsr
+module, repetitively triggered by a square wave.  
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_fm.arts</filename></term>
+<listitem>
+<para>
+This uses the FM Source module to generate a 440 Hz sine wave which is
+frequency modulated at a 5 Hz rate.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_freeverb.arts</filename></term>
+<listitem>
+<para>
+This connects the Freeverb effect from a bus downlink to a bus
+outlink. You can use artscontrol to connect the effect to a sound player
+and observe the results.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_flanger.arts</filename></term>
+<listitem>
+<para>
+This implements a simple flanger effect (it doesn't appear to work yet,
+though).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_moog.arts</filename></term>
+<listitem>
+<para>
+This structure combines the two channels from a bus into one, passes it
+though the Moog VCF filter, and sends it out the out_soundcard bus.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_pitch_shift.arts</filename></term>
+<listitem>
+<para>
+This structure passes the left channel of sound card data through the
+Pitch Shift effect. Adjust the speed parameter to vary the effect.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_rc.arts</filename></term>
+<listitem>
+<para>
+This structure passes a white noise generator though an RC filter and
+out to the sound card. By viewing the FFT Scope display in artscontrol
+you can see how this varies from an unfiltered noise waveform.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_sequence.arts</filename></term>
+<listitem>
+<para>
+This demonstrates the Sequence module by playing a sequence of notes.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_shelve_cutoff.arts</filename></term>
+<listitem>
+<para>
+This structure passes a white noise generator though a Shelve Cutoff
+filter and out to the sound card. By viewing the FFT Scope display in
+artscontrol you can see how this varies from an unfiltered noise
+waveform.  
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_equalizer.arts</filename></term>
+<listitem>
+<para>
+This demonstrates the Std_Equalizer module. It boosts the low and high
+frequencies by 6 dB.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_tremolo.arts</filename></term>
+<listitem>
+<para>
+This demonstrates the Tremolo effect. It modulates the left and right
+channels using a 10 Hz tremolo.  
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_xfade.arts</filename></term>
+<listitem>
+<para>
+This example mixes 440 and 880 Hz sine waves using a cross fader.
+Adjust the value of the cross fader's percentage input from -1 to 1 to
+control the mixing of the two signals.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_pscale.arts</filename></term>
+<listitem>
+<para>
+This illustrates the Pscale module (I'm not sure if this is a
+meaningful example).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><filename>example_play_wav.arts</filename></term>
+<listitem>
+<para>
+This illustrates the Play Wave module. You will need to
+enter the full path to a <literal role="extension">.wav</literal> file
+as the filename parameter.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>example_multi_add.arts</term>
+<listitem>
+<para>
+This shows the Multi Add module which accepts any number of inputs. It
+sums three Data modules which produce inputs of 1, 2, and 3, and
+displays the result 6.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+</chapter>