path: root/doc/artsbuilder/modules.docbook

<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
To validate or process this file as a standalone document, uncomment
this prolog. Be sure to comment it out again when you are done -->

<chapter id="arts-modules">
<title>&arts; modules</title>

  <sect1 id="modules-introduction">
<title>Introduction</title>

<para>
This chapter describes all of the standard &arts; modules. One of the
most powerful features of &arts;, modules can be connected together into
structures to implement new functions such as effects and instruments.
</para>

<para>
Modules are broken down into two categories. Synthesis modules are used
for implementing the <quote>plumbing</quote> that manipulates multimedia
data streams to implement new effects, instruments, mixers, and
applications. Visual modules allow you to provide a graphical user
interface to control the sound structures that are built up with the
synthesis modules.
</para>

</sect1>

<sect1 id="synth-modules-reference">
<title>Synthesis Modules Reference</title>
<para>
</para>

<sect2 id="mcat-synth-arithmetic-mixing">
<title>Arithmetic + Mixing</title>

<para>
</para>

<sect3 id="mref-synth-add-sect">
<title>Synth&lowbar;ADD</title>
<anchor id="mref-synth-add" />

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_ADD.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;ADD</phrase></textobject>
</mediaobject>

<para>
This adds two signals.
</para>

</sect3>

<sect3 id="mref-synth-mul-sect">
<title>Synth&lowbar;MUL</title>
<anchor id="mref-synth-mul"/>

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_MUL.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;MUL</phrase></textobject>
</mediaobject>

<para>
This multiplies a signal by a factor. You can use this to scale signals
down (0 &lt; factor &lt; 1) or up (factor &gt; 1) or invert signals
(factor &lt; 0). Note that the factor may be a signal and don't has to
be constant (&eg; envelope or real signal).
</para>

</sect3>

<sect3 id="mref-synth-div-sect">
<title>Synth&lowbar;DIV</title>
<anchor id="mref-synth-div"/>

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_DIV.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;DIV</phrase></textobject>
</mediaobject>

<para>
This divides a signal by a factor. You can use this to do divide one signal
by another one. Or set invalue1 to 1 and you will get the
reciprocal of the invalue2 as outvalue. Take care that invalue2 never
reaches 0 or you will get problems with divisions by zero.
</para>

</sect3>

<sect3 id="mref-synth-multi-add-sect">
<title>Synth&lowbar;MULTI&lowbar;ADD</title>
<anchor id="mref-synth-multi-add" />

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_MULTI_ADD.png"
  format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;MULTI&lowbar;ADD</phrase></textobject>
</mediaobject>

<para>
This adds an arbitrary number of signals. If you need to sum up the
waveforms produces by four different oscillators, you for instance can
connect all their outputs to one Synth&lowbar;MULTI&lowbar;ADD
module. This is more efficient than using three Synth&lowbar;ADD
modules.
</para>

</sect3>

<sect3 id="mref-synth-xfade-sect">
<title>Synth&lowbar;XFADE</title>
<anchor id="mref-synth-xfade" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_XFADE.png" format="PNG"/>
</imageobject>
<textobject><phrase>Synth&lowbar;XFADE</phrase></textobject>
</mediaobject>

<para>
This crossfades two signals. If the percentage input is -1, only the
left signal is heard, if it is 1, only the right signal is heard. When
it is 0, both signals a heard with the same volume.
</para>

<para>
This allows you to ensure that your signal stays in a well defined
range.  If you had two signals that were between -1 and 1 before
crossfading, they will be in the same range after crossfading.
</para>
</sect3>

<sect3 id="mref-synth-autopanner-sect">
<title>Synth&lowbar;AUTOPANNER</title>
<anchor id="mref-synth-autopanner" />

<para>
The opposite of a crossfader. This takes a mono signal and splits it
into a stereo signal: It is used to automatically pan the input signal
between the left and the right output. This makes mixes more lively. A
standard application would be a guitar or lead sound.
</para>

<para>
Connect a <acronym>LFO</acronym>, a sine or saw wave for example to
inlfo.  and select a frequency between 0.1 and 5Hz for a traditional
effect or even more for Special <acronym>FX</acronym>.
</para>

</sect3>

</sect2>

<sect2 id="mcat-synth-busses">
<title>Busses</title>

<sect3 id="mref-synth-bus-uplink-sect">
<title>Synth&lowbar;BUS&lowbar;UPLINK</title>
<anchor id="mref-synth-bus-uplink" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_BUS_UPLINK.png"
               format="PNG"/>
</imageobject>
<textobject><phrase>Synth&lowbar;BUS&lowbar;UPLINK</phrase></textobject>
</mediaobject>

<para>
An uplink to a bus. Give signals to left and right, and the name of the
bus where the data should go on the <quote>bus</quote> port. The
combined signal from all uplinks with this name will appear on every
downlink on that <quote>bus</quote>.
</para>
</sect3>

<sect3 id="mref-synth-bus-downlink-sect">
<title>Synth&lowbar;BUS&lowbar;DOWNLINK</title>
<anchor id="mref-synth-bus-downlink" />

<mediaobject>
<imageobject>
<imagedata fileref="images/Synth_BUS_DOWNLINK.png"
  format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;BUS&lowbar;DOWNLINK</phrase></textobject>
</mediaobject>

<para>
Gets (the sum of) all data that is put to a certain bus (with the name
you specify at the <quote>bus</quote> port).
</para>
</sect3>

</sect2>

<!-- TODO AFTER KDE2.1: move freeverb into delays, and rename category to
     Delays &amp; reverbs -->

<sect2 id="mcat-synth-delays">
<title>Delays</title>

<para>
</para>

<sect3 id="mref-synth-delay-sect">
<title>Synth&lowbar;DELAY</title>
<anchor id="mref-synth-delay" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_DELAY.png"
               format="PNG"/></imageobject></mediaobject>

<para>
This delays the input signal for an amount of time. The time
specification must be between 0 and maxdelay for a delay between 0 and
maxdelay seconds.
</para>

<para>
This kind of delay <emphasis>may not be used</emphasis> in feedback
structures. This is because it's a variable delay. You can modify it's
length while it is running, and even set it down to zero. But since in a
feedback structure the own output is needed to calculate the next
samples, a delay whose value could drop to zero during synthesis could
lead to a stall situation.
</para>

<para>
Use CDELAYs in that setup, perhaps combine a small constant delay (of
0.001 seconds) with a flexible delay.
</para>

<para>
You can also combine a CDELAY and a DELAY to achieve a variable length
delay with a minimum value in a feedback loop. Just make sure that you
have a CDELAY involved.
</para>

</sect3>

<sect3 id="mref-synth-cdelay-sect">
<title>Synth&lowbar;CDELAY</title>
<anchor id="mref-synth-cdelay" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_CDELAY.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;CDELAY</phrase></textobject>
</mediaobject>

<para>
This delays the input signal for an amount of time. The time
specification must be greater than 0 for a delay of 0 seconds or more.
The delay is constant during the calculation, that means it
can't be modified.
</para>

<para>
This saves computing time as no interpolation is done, and is useful for
recursive structures. See description above (Synth&lowbar;DELAY).
</para>

</sect3>

</sect2>

<sect2 id="mcat-synth-envelopes">
<title>Envelopes</title>

<para>
</para>

<sect3 id="mref-synth-envelope-adsr-sect">
<title>Synth&lowbar;ENVELOPE&lowbar;ADSR</title>
<anchor id="mref-synth-envelope-adsr" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_ENVELOPE_ADSR.png"
               format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;ENVELOPE&lowbar;ADSR</phrase></textobject>
</mediaobject>

<para>
This is a classic <acronym>ADSR</acronym> envelope which means you
specify:
</para>

<variablelist>
<varlistentry>
<term>active</term>
<listitem>
<para>
Whether the note is being pressed right now by the user.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>invalue</term>
<listitem>
<para>
The input signal.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>attack</term>
<listitem>
<para>
The time that should pass between the user presses the note and the signal
reaching it's maximum amplitude (in seconds).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>decay</term>
<listitem>
<para>
The time that should pass between the the signal reaching it's maximum
amplitude and the signal going back to some constant level (in seconds).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>sustain</term>
<listitem>
<para>
The constant level the signal is held at afterwards, until the user
releases the note.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>release</term>
<listitem>
<para>
The time that should pass after the user has released the note until the
signal is scaled down to zero (in seconds).
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
You'll get the scaled signal at outvalue. If the <acronym>ASDR</acronym>
envelope is finished, it will set done to 1. You can use this to provide
the <quote>done</quote> output of an instrument (which will make the
instrument structure be deleted by the &MIDI; router object once the
release phase is over).
</para>

</sect3>

<sect3 id="mref-synth-pscale-sect">
<title>Synth&lowbar;PSCALE</title>
<anchor id="mref-synth-pscale" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_PSCALE.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PSCALE</phrase></textobject>
</mediaobject>

<para>
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 (get the position from
Synth&lowbar;SEQUENCE).  The position where the peak should occur can be
given as pos.
</para>

<para>
Example: Setting top to 0.1 means that after 10&percnt; of the note has
been played, the volume has reached its maximum, and starts decaying
afterwards.
</para>
</sect3>

</sect2>

<sect2 id="mcat-synth-effects">
<title>Effects</title>

<sect3 id="mref-synth-freeverb-sect">
<title>Synth&lowbar;FREEVERB</title>
<anchor id="mref-synth-freeverb" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_FREEVERB.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;FREEVERB</phrase></textobject>
</mediaobject>

<para>
This is a reverb effect. In the current implementation, it is thought to
pass a stereo signal through the reverb, and it will -add- it's reverb
effect to the signal.
</para>

<note>
<para>
This means that it can be used inside an StereoEffectStack as well.
</para>
</note>

<para>
The input signal should be connected to (inleft, inright), the output
signal will be (outleft, outright).
</para>

<para>
The parameters which you can configure are:
</para>

<variablelist>
<varlistentry>
<term>roomsize</term>
<listitem>
<para>
The size of the room which the reverb simulates (range: 0..1, where 1 is
the largest possible room).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>damp</term>
<listitem>
<para>
This specifies a filter which will make the simulated room absorb high
frequencies (range 0..1, where 1 means absorb high frequencies quite
aggressive).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>wet</term>
<listitem>
<para>
The amount of reverb-signal (that is, the amount of the signal that
should be modified by the filters, resulting in a <quote>wet</quote>,
that is <quote>reverb sound</quote>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>dry</term>
<listitem>
<para>
The amount of pure signal passed through, resulting in an echo (or
combined delay) rather than reverb effect (range: 0..1).
</para>
<!-- TODO: do some measurements to show that this documentation -is- correct,
I am not sure if it is echo, or really pure (non-delayed), or multiple delay
or whatever -->
</listitem>
</varlistentry>

<varlistentry>
<term>width</term>
<listitem>
<para>
The amount of stereo-magic the reverb algorithm adds to the reverb
effect, making the reverb sound wider in the stereo panorama (range:
0..1).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mode</term>
<listitem>
<para>
[ TODO: I think if mode is 1, the reverb holds the current image of the
sound, whereas 0 is normal operation ]
</para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="mref-synth-tremolo-sect">
<title>Synth&lowbar;TREMOLO</title>
<anchor id="mref-synth-tremolo" />

<mediaobject><imageobject><imagedata fileref="images/Synth_TREMOLO.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;TREMOLO</phrase></textobject>
</mediaobject>

<para>
The tremolo module modulates the amplitude according to a
<acronym>LFO</acronym>-Wave.  Traditionally you would use a sine wave
but why limit yourself?  What you get is a very intense effect that cuts
through most arrangements because of its high dynamic range.  The
tremolo effect is still one of guitarists favorite effects although
it's not as popular as in the 1960's.
</para>

<para>
[ TODO: currently this is implemented as invalue + abs(inlfo) - maybe it
would make more sense to implement it as invalue * (1+inlfo*depth),
where depth would be a parameter between 0..1 - decide this after &kde;2.1
; if you have a comment, send a mail to the &arts; list ;). ]
</para>

</sect3>
<sect3 id="mref-synth-fx-cflanger-sect">
<title>Synth&lowbar;FX&lowbar;CFLANGER</title>
<anchor id="mref-synth-fx-cflanger" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_FX_CFLANGER.png" format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;FX&lowbar;CFLANGER</phrase></textobject>
</mediaobject>

<para>
A flanger is a time-varying delay effect. To make development of complex
flanger effects simpler, this module is provided, which contains the
core of a one-channel flanger.
</para>

<para>It has the following ports:</para>

<variablelist>
<varlistentry>
<term>invalue</term>
<listitem>
<para>
The signal which you want to process.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>lfo</term>
<listitem>
<para>
Preferably a sine wave which modulates the delay time inside the
flanger (-1 .. 1).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mintime</term>
<listitem>
<para>
The minimum value for the delay inside the flanger in milliseconds.
Suggested values: try something like 1 ms. Please use values &lt; 1000
ms.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>maxtime</term>
<listitem>
<para>
The minimum value for the delay inside the flanger in milliseconds.
Suggested values: try something like 5 ms. Please use values &lt; 1000
ms.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>outvalue</term>
<listitem>
<para>
The output signal. It is important that you mix that with the
original (unflanged) signal to get the desired effect.
</para>
</listitem>
</varlistentry>
</variablelist>

<tip>
<para>
You can use this as a basis for a chorus effect.
</para>
</tip>

</sect3>

</sect2>

<sect2 id="mcat-synth-filters">
<title>Filters</title>

<sect3 id="mref-synth-pitch-shift-sect">
<title>Synth&lowbar;PITCH&lowbar;SHIFT</title>
<anchor id="mref-synth-pitch-shift" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_PITCH_SHIFT.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PITCH&lowbar;SHIFT</phrase></textobject>
</mediaobject>

<para>
This pitch shifting effect changes the frequency of the input signal
without affecting the speed. An application for this is for instance
changing the pitch of your voice while you record (and replay) it in
realtime.
</para>

<para>
The <emphasis>speed</emphasis> parameter is the relative speed with
which the signal will be replayed. So a speed of two would make it sound
twice as high (&ie; an input frequency of 440 Hz would result in an
output frequency of 880 Hz).
</para>

<para>
The <emphasis>frequency</emphasis> parameter is used internally to
switch between different grains of the signal. It is tunable, and
depending on your choice, the pitch shifting will sound more or less
realistic for your use case. A good value to start with is something
like 5 or 10.
</para>

</sect3>

<sect3 id="mref-synth-shelve-cutoff-sect">
<title>Synth&lowbar;SHELVE&lowbar;CUTOFF</title>
<anchor id="mref-synth-shelve-cutoff" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_SHELVE_CUTOFF.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;SHELVE&lowbar;CUTOFF</phrase></textobject>
</mediaobject>

<para>
Filters out all frequencies over the cutoff frequency.
</para>

</sect3>

<sect3 id="mref-synth-brickwall-limiter-sect">
<title>Synth&lowbar;BRICKWALL&lowbar;LIMITER</title>
<anchor id="mref-synth-brickwall-limiter" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_BRICKWALL_LIMITER.png"
                            format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;BRICKWALL&lowbar;LIMITER</phrase></textobject>
</mediaobject>

<para>
This modules clips a signal to make it fit into the range of [-1;1]. It
doesn't do anything to prevent the distortion that happens when clipping
loud signals. You can use this as effect (for instance to create a
slightly clipped sine wave). However, it's probably a good idea to run
the signal through a lowpass filter afterwards if you do so, to make it
sound less aggressive.
</para>
</sect3>

<sect3 id="mref-synth-std-equalizer-sect">
<title>Synth&lowbar;STD&lowbar;EQUALIZER</title>
<anchor id="mref-synth-std-equalizer" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_STD_EQUALIZER.png" format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;STD&lowbar;EQUALIZER</phrase></textobject>
</mediaobject>

<para>
This is a nice parametric equalizer building block. It's parameters are:
</para>

<variablelist>
<varlistentry>
<term>invalue, outvalue</term>
<listitem>
<para>
The signal that gets filtered by the equalizer.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>low</term>
<listitem>
<para>
How low frequencies should be changed. The value is in dB, while 0 means
don't change low frequencies, -6 would mean take them out by 6dB, and +6
mean boost them by 6dB.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mid</term>
<listitem>
<para>
How middle frequencies should be changed by the equalizer in dB (see
low).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>high</term>
<listitem>
<para>
How high frequencies should be changed by the equalizer in dB (see low).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>frequency</term>
<listitem>
<para>
This is the center frequency of the equalizer in Hz, the mid frequencies
are around that spectrum, the low and high frequencies below and above.
Note that the frequency may not be higher than half the sampling rate,
usually that is 22050 Hz, and not lower than 1 Hz.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>q</term>
<listitem>
<para>
This influences how broad the mid spectrum is. It must be be a positive
number &gt; 0. A value of one is reasonable, higher values of q mean a
narrower spectrum of middle frequencies. Lower values than one mean a
broader spectrum.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="mref-synth-rc-sect">
<title>Synth&lowbar;RC</title>
<anchor id="mref-synth-rc" />

<mediaobject><imageobject><imagedata fileref="images/Synth_RC.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;RC</phrase></textobject>
</mediaobject>

<para>
A damped resonator filter filtering all frequencies around some peak
value.  There is no useful way of specifying middle frequency (that
won't be cut), since the input are two strange constants f and b. The
code is very old, from the first days of the synthesizer, and will
probably replaced by a new filter which will have a frequency and a
resonance value as parameters.
</para>

<para>
Try something like b=5, f=5 or b=10, f=10 or b=15, f=15 though.
</para>

</sect3>

<sect3 id="mref-synth-moog-vcf-sect">
<title>Synth&lowbar;MOOG&lowbar;VCF</title>
<anchor id="mref-synth-moog-vcf" />

<mediaobject><imageobject><imagedata fileref="images/Synth_MOOG_VCF.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;MOOG&lowbar;VCF</phrase></textobject>
</mediaobject>

<para>
Filters out all frequencies over the cutoff frequency (it's a 24db 4pole
filter, which filters -24db per octave above the cutoff frequency), but
offers an additional parameter for tuning the filter resonance, while 0
means no resonance and 4 means self oscillation.
</para>

</sect3>

</sect2>

<sect2 id="mcat-synth-midi-sequencing">
<title>Midi + Sequencing</title>

<sect3 id="mref-synth-midi-test-sect">
<title>Synth&lowbar;MIDI&lowbar;TEST</title>
<anchor id="mref-synth-midi-test" />

<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_TEST.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;MIDI&lowbar;TEST</phrase></textobject>
</mediaobject>

<para>
This modules loads an instrument structure from a file, and registers
itself as midi output with the &arts; &MIDI; manager. Notes sent to this
output will result in instrument voices being created.
</para>

<note>
<para>
You can setup something like this more convenient in &artscontrol; than
manually in &arts-builder;.
</para>
</note>

</sect3>

<sect3 id="mref-synth-sequence-sect">
<title>Synth&lowbar;SEQUENCE</title>
<anchor id="mref-synth-sequence" />

<mediaobject><imageobject><imagedata fileref="images/Synth_SEQUENCE.png"
format="PNG" /></imageobject></mediaobject>

<para>
Will play a sequence of notes over and over again. The notes are given
in tracker notation, and are separated by semicolons. An example is
<literal>A-3;C-4;E-4;C-4;</literal>. The speed is given as seconds per
note, so if you want to get 120 bpm, you will probably specify 0.5
seconds/note, as 60 seconds/0.5 seconds per note=120 bpm.
</para>

<para>
You can give each note an length relative to the speed by using a colon
after the note and then then
length. <literal>A-3:2;C-4:0.5;D-4:0.5;E-4;</literal> demonstrates
this. As you see, midi composing programs tend to offer more comfort ;)
</para>

<para>
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. This information you can use with
Synth&lowbar;PSCALE (see below).
</para>
</sect3>

<sect3 id="mref-synth-sequence-freq-sect">
<title>Synth&lowbar;SEQUENCE&lowbar;FREQ</title>
<anchor id="mref-synth-sequence-freq" />

<mediaobject><imageobject><imagedata fileref="images/Synth_SEQUENCE_FREQ.png"
format="PNG" /></imageobject></mediaobject>

<para>
This module works just like Synth&lowbar;SEQUENCE with the only difference that
you don't write notenames but frequencies.
</para>

</sect3>

</sect2>

<sect2 id="mcat-synth-samples">
<title>Samples</title>

<sect3 id="mref-synth-play-wav-sect">
<title>Synth&lowbar;PLAY&lowbar;WAV</title>
<anchor id="mref-synth-play-wav" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_PLAY_WAV.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PLAY&lowbar;WAV</phrase></textobject>
</mediaobject>

<para>
This will play a <literal role="extension">wav</literal> file. It will
only be present if you have libaudiofile on your computer. The wave file
will start as soon as the module gets created. 
</para>

<para>
It will stop as soon as it's over, then finished will be set to 1. The
speed parameter can be used to replay the file faster or slower, where
1.0 is the normal (recorded) speed.
</para>
<!-- TODO: KDE2.2: check that this really works together in instruments with
the done parameter things ;) -->
</sect3>

</sect2>

<sect2 id="mcat-synth-soundio">
<title>Sound IO</title>

<sect3 id="mref-synth-play-sect">
<title>Synth&lowbar;PLAY</title>
<anchor id="mref-synth-play" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_PLAY.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;PLAY</phrase></textobject>
</mediaobject>

<important>
<para>
You will normally not need this module, unless you are writing
standalone applications. Inside &artsd;, there normally is already a
Synth&lowbar;PLAY module, and creating another one will not work.
</para>
</important>

<para>
The Synth&lowbar;PLAY-module will output your audio signal to the
soundcard. The left and right channels should contain the
<emphasis>normalized</emphasis> input for the channels.  If your input
is not between -1 and 1, you get clipping.
</para>

<para>
As already mentioned, there may only be one Synth&lowbar;PLAY module
used, as this one directly accesses your soundcard. Use busses if you
want to mix more than one audio stream together before playing. Use the
Synth&lowbar;AMAN&lowbar;PLAY module to get something like an output
inside &artsd;.
</para>

<para>
Note that Synth&lowbar;PLAY also does the timing of the whole
structure. This means: no Synth&lowbar;PLAY = no source for timing = no
sound. So you absolutely need (exactly) one Synth&lowbar;PLAY object.
</para>

</sect3>

<sect3 id="mref-synth-record-sect">
<title>Synth&lowbar;RECORD</title>
<anchor id="mref-synth-record" />

<mediaobject><imageobject><imagedata fileref="images/Synth_RECORD.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;RECORD</phrase></textobject>
</mediaobject>

<important>
<para>You will normally not need this module, unless you are writing
standalone applications. Inside artsd, there normally is already a
Synth&lowbar;RECORD module, and creating another one will not work.
</para>
</important>

<para>
The Synth&lowbar;RECORD-module will record a signal from the soundcard.
The left and right channels will contain the input for the channels
(between -1 and 1).
</para>

<para>
As already mentioned, there may only be one Synth&lowbar;RECORD module
used, as this one directly accesses your soundcard. Use busses if you
want to use the recorded audio stream in more than one place. Use the
Synth&lowbar;AMAN&lowbar;RECORD module to get something like an input
inside artsd. For this to work, &artsd; must run <emphasis>with full
duplex enabled </emphasis>.
</para>
</sect3>

<sect3 id="mref-synth-aman-play-sect">
<title>Synth&lowbar;AMAN&lowbar;PLAY</title>
<anchor id="mref-synth-aman-play" />

<mediaobject><imageobject><imagedata fileref="images/Synth_AMAN_PLAY.png"
format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;AMAN&lowbar;PLAY</phrase></textobject>
</mediaobject>

<para>
The Synth&lowbar;AMAN&lowbar;PLAY-module will output your audio signal.
It is nice (but not necessary) if you output a normalized signal
(between -1 and 1).
</para>

<para>
This module will use the audio manager to assign where the signal will
be played. The audio manager can be controlled through &artscontrol;. To
make it more intuitive to use, it is good to give the signal you play a
name. This can be achieved through setting
<emphasis>title</emphasis>. Another feature of the audio manager is to
be able to remember where you played a signal the last time. To do so it
needs to be able to distinguish signals. That is why you should assign
something unique to <emphasis>autoRestoreID</emphasis>, too.
</para>
</sect3>

<sect3 id="mref-synth-aman-record-sect">
<title>Synth&lowbar;AMAN&lowbar;RECORD</title>
<anchor id="mref-synth-aman-record" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_AMAN_RECORD.png" format="PNG"/></imageobject>
<textobject><phrase>Synth&lowbar;AMAN&lowbar;RECORD</phrase></textobject>
</mediaobject>

<para>
The Synth&lowbar;AMAN&lowbar;RECORD-module will record an audio signal
from an external source (&ie;. line in/microphone) within &artsd;. The
output will be a normalized signal (between -1 and 1).
</para>

<para>
This module will use the audio manager to assign where the signal will
be played. The audio manager can be controlled through artscontrol. To
make it more intuitive to use, it is good to give the signal you record
a name. This can be achieved through setting
<emphasis>title</emphasis>. Another feature of the audio manager is to
be able to remember where you recorded a signal the last time. To do so
it needs to be able to distinguish signals. That is why you should
assign something unique to <emphasis>autoRestoreID</emphasis>, too.
</para>
</sect3>

<sect3 id="mref-synth-capture-sect">
<title>Synth&lowbar;CAPTURE</title>
<anchor id="mref-synth-capture" />

<mediaobject><imageobject><imagedata fileref="images/Synth_CAPTURE.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;CAPTURE</phrase></textobject>
</mediaobject>

<para>
The Synth&lowbar;CAPTURE-module will write an audio signal to a wave
file on your hard disc. The file will always be called
<filename>/tmp/mcop-<replaceable>usename</replaceable>/capture.wav</filename>
</para>
</sect3>

</sect2>

<sect2 id="mcat-synth-tests">
<title>Tests</title>

<sect3 id="mref-synth-nil-sect">
<title>Synth&lowbar;NIL</title>
<anchor id="mref-synth-nil" />

<mediaobject><imageobject><imagedata fileref="images/Synth_NIL.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;NIL</phrase></textobject>
</mediaobject>

<para>
This just does nothing. It is only useful for test situations.
</para>

</sect3>

<sect3 id="mref-synth-debug-sect">
<title>Synth&lowbar;DEBUG</title>
<anchor id="mref-synth-debug" />

<mediaobject><imageobject><imagedata fileref="images/Synth_DEBUG.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;DEBUG</phrase></textobject>
</mediaobject>

<para>
You can use this for debugging. It will print out the value of the
signal at invalue in regular intervals (ca. 1 second), combined with the
comment you have specified. That way you can find out if some signals
stay in certain ranges, or if they are there at all.
</para>
</sect3>

<sect3 id="mref-synth-midi-debug-sect">
<title>Synth&lowbar;MIDI&lowbar;DEBUG</title>
<anchor id="mref-synth-midi-debug" />

<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_DEBUG.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;MIDI&lowbar;DEBUG</phrase></textobject>
</mediaobject>

<para>
You can use this to debug how your &MIDI; events are actually arriving
in &arts;.
</para>

<para>
When a MIDI&lowbar;DEBUG is running &artsserver; will print out a lines
like:
</para>

<screen><computeroutput>201 100753.837585 on 0 42 127</computeroutput></screen>

<screen><computeroutput>202 101323.128355 off 0 42</computeroutput></screen>

<para>
While the first line would be telling you that 100753ms (that is 100
seconds) after the MIDI&lowbar;DEBUG started, a &MIDI; on event arrived
on channel 0. This midi on event had the velocity (volume) of 127, the
loudest possible. The next line shows the midi release event. [ TODO:
this does not work currently, make it work, and do it via &MIDI; manager
].
</para>
</sect3>

<sect3 id="mref-synth-data-sect">
<title>Synth&lowbar;DATA</title>
<anchor id="mref-synth-data" />

<mediaobject><imageobject><imagedata fileref="images/Synth_DATA.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;DATA</phrase></textobject>
</mediaobject>

<para>
This creates a signal with a constant number. 
</para>
<!-- TODO: this doesn't really belong in test, does it? -->
</sect3>
</sect2>

<sect2 id="mcat-synth-osc-mod">
<title>Oscillation &amp; Modulation</title>

<sect3 id="mref-synth-frequency-sect">
<title>Synth&lowbar;FREQUENCY</title>
<anchor id="mref-synth-frequency" />

<mediaobject><imageobject><imagedata fileref="images/Synth_FREQUENCY.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;FREQUENCY</phrase></textobject>
</mediaobject>

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

<sect3 id="mref-synth-fm-source-sect">
<title>Synth&lowbar;FM&lowbar;SOURCE</title>
<anchor id="mref-synth-fm-source" />

<mediaobject><imageobject><imagedata fileref="images/Synth_FM_SOURCE.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;FM&lowbar;SOURCE</phrase></textobject>
</mediaobject>

<para>
This is used for frequency modulation. Put your frequency to the
frequency input and put another signal on the modulator input. Then set
modlevel to something, say 0.3. The frequency will be modulated with
modulator then.  Just try it. Works nice when you put a feedback in
there, that means take a combination of the delayed output signal from
the Synth&lowbar;FM&lowbar;SOURCE (you need to put it to some oscillator
as it only takes the role of Synth&lowbar;FREQUENCY) and some other
signal to get good results.
</para>

<para>
Works nicely in combination with Synth&lowbar;WAVE&lowbar;SIN
oscillators.
</para>
</sect3>

</sect2>

<sect2 id="mcat-synth-waveforms">
<title>Wave Forms</title>

<sect3 id="mref-synth-wave-sin-sect">
<title>Synth&lowbar;WAVE&lowbar;SIN</title>
<anchor id="mref-synth-wave-sin" />

<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_SIN.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;SIN</phrase></textobject>
</mediaobject>

<para>
Sinus oscillator. Put a pos signal from Synth&lowbar;FREQUENCY or
Synth&lowbar;FM&lowbar;SOURCE at the input. And get a sinus wave as
output. The pos signal specifies the position in the wave, the range
0..1 is mapped to 0..2*pi internally.
</para>

</sect3>

<sect3 id="mref-synth-wave-tri-sect">
<title>Synth&lowbar;WAVE&lowbar;TRI</title>
<anchor id="mref-synth-wave-tri" />

<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_TRI.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;TRI</phrase></textobject>
</mediaobject>

<para>
Triangle oscillator. Put a pos signal from Synth&lowbar;FREQUENCY or
Synth&lowbar;FM&lowbar;SOURCE at the input. And get a triangle wave as
output. The pos signal specifies the position in the wave, the range
0..1 is mapped to 0..2*pi internally. Be careful. The input signal
<emphasis>must</emphasis> be in the range 0..1 for the output signal to
produce good results.
</para>
</sect3>

<sect3 id="mref-synth-noise-sect">
<title>Synth&lowbar;NOISE</title>
<anchor id="mref-synth-noise" />

<mediaobject><imageobject><imagedata fileref="images/Synth_NOISE.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;NOISE</phrase></textobject>
</mediaobject>

<para>
Noise generator. This generates a random signal between -1 and 1.
</para>

</sect3>

<sect3 id="mref-synth-wave-square-sect">
<title>Synth&lowbar;WAVE&lowbar;SQUARE</title>
<anchor id="mref-synth-wave-square" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_WAVE_SQUARE.png" format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;SQUARE</phrase></textobject>
</mediaobject>

<para>
Square oscillator. Put a pos signal from Synth&lowbar;FREQUENCY or
Synth&lowbar;FM&lowbar;SOURCE at the input. And get a square wave as
output. The pos signal specifies the position in the wave, the range
0..1 is mapped to 0..2*pi internally. Be careful. The input signal
<emphasis>must</emphasis> be in the range 0..1 for the output signal to
produce good results.
</para>
</sect3>

<sect3 id="mref-synth-wave-softsaw-sect">
<title>Synth&lowbar;WAVE&lowbar;SOFTSAW</title>
<anchor id="mref-synth-wave-softsaw" />

<mediaobject><imageobject><imagedata
fileref="images/Synth_WAVE_SOFTSAW.png" format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;SOFTSAW</phrase></textobject>
</mediaobject>

<para>
Softened saw wave, similar in look like the Synth&lowbar;WAVE&lowbar;TRI
oscillator.  Put a pos signal from Synth&lowbar;FREQUENCY or
Synth&lowbar;FM&lowbar;SOURCE at the input. You'll get a softened saw
wave as output. The pos signal specifies the position in the wave, the
range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal
<emphasis>must</emphasis> be in the range 0..1 for the output signal to
produce good results.
</para>
</sect3>

<sect3 id="mref-synth-wave-pulse-sect">
<title>Synth&lowbar;WAVE&lowbar;PULSE</title>
<anchor id="mref-synth-wave-pulse" />

<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_PULSE.png"
format="PNG" /></imageobject>
<textobject><phrase>Synth&lowbar;WAVE&lowbar;PULSE</phrase></textobject>
</mediaobject>

<para>
Pulse oscillator - this module is similar in spirit like the rectangular
oscillator (Synth_WAVE_RECT), but it provides a configurable up/down
ratio, through the <emphasis>dutycycle</emphasis> parameter. Put a pos
signal from Synth&lowbar;FREQUENCY or Synth&lowbar;FM&lowbar;SOURCE at
the input. Get a pulse wave as output. The pos signal specifies the
position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be
careful. The input signal <emphasis>must</emphasis> be in the range 0..1
for the output signal to produce good results.
</para>
</sect3>
</sect2>
<sect2 id="mcat-synth-misc">
<title>Miscellaneous</title>

<sect3 id="mref-synth-compressor-sect">
<title>Synth&lowbar;COMPRESSOR</title>
<anchor id="mref-synth-compressor" />

<mediaobject>
<imageobject><imagedata fileref="images/Synth_COMPRESSOR.png"
               format="PNG"/></imageobject></mediaobject>

<para>
This module reduces the dynamic range of the signal. For example
compressors are useful in compensating for the wide variations in
loudness of somebody talking into a microphone.
</para>

<para>
As soon as the input level exceeds a certain level (the threshold)
the signal gets compressed. It simply multiplies everything above
the threshold with the ratio, which should be a number between 0 and
1. Finally the whole signal is multiplied by the output factor.
</para>

<para>
The attack and release arguments delay the start and end of the
compression. Use this if you, for example, still want to hear the
loud beginning of a basedrum. The argument is in milliseconds and an
attack or release of 0ms is possible but may result in a slight noise.
</para>

</sect3>
</sect2>
</sect1>

<sect1 id="visual-modules-reference">
<title>Visual Modules Reference</title>

<para>
TODO when visual modules are more "finished".
</para>
</sect1>

</chapter>