diff options
Diffstat (limited to 'doc/artsbuilder/modules.docbook')
| -rw-r--r-- | doc/artsbuilder/modules.docbook | 1336 |
1 files changed, 1336 insertions, 0 deletions
diff --git a/doc/artsbuilder/modules.docbook b/doc/artsbuilder/modules.docbook new file mode 100644 index 00000000..d0da50d8 --- /dev/null +++ b/doc/artsbuilder/modules.docbook @@ -0,0 +1,1336 @@ +<!-- <?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_ADD</title> +<anchor id="mref-synth-add" /> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_ADD.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_ADD</phrase></textobject> +</mediaobject> + +<para> +This adds two signals. +</para> + +</sect3> + +<sect3 id="mref-synth-mul-sect"> +<title>Synth_MUL</title> +<anchor id="mref-synth-mul"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_MUL.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_MUL</phrase></textobject> +</mediaobject> + +<para> +This multiplies a signal by a factor. You can use this to scale signals +down (0 < factor < 1) or up (factor > 1) or invert signals +(factor < 0). Note that the factor may be a signal and don't has to +be constant (⪚ envelope or real signal). +</para> + +</sect3> + +<sect3 id="mref-synth-div-sect"> +<title>Synth_DIV</title> +<anchor id="mref-synth-div"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_DIV.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_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_MULTI_ADD</title> +<anchor id="mref-synth-multi-add" /> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_MULTI_ADD.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_MULTI_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_MULTI_ADD +module. This is more efficient than using three Synth_ADD +modules. +</para> + +</sect3> + +<sect3 id="mref-synth-xfade-sect"> +<title>Synth_XFADE</title> +<anchor id="mref-synth-xfade" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_XFADE.png" format="PNG"/> +</imageobject> +<textobject><phrase>Synth_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_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_BUS_UPLINK</title> +<anchor id="mref-synth-bus-uplink" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_BUS_UPLINK.png" + format="PNG"/> +</imageobject> +<textobject><phrase>Synth_BUS_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_BUS_DOWNLINK</title> +<anchor id="mref-synth-bus-downlink" /> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_BUS_DOWNLINK.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_BUS_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 & reverbs --> + +<sect2 id="mcat-synth-delays"> +<title>Delays</title> + +<para> +</para> + +<sect3 id="mref-synth-delay-sect"> +<title>Synth_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_CDELAY</title> +<anchor id="mref-synth-cdelay" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_CDELAY.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_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_DELAY). +</para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-envelopes"> +<title>Envelopes</title> + +<para> +</para> + +<sect3 id="mref-synth-envelope-adsr-sect"> +<title>Synth_ENVELOPE_ADSR</title> +<anchor id="mref-synth-envelope-adsr" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_ENVELOPE_ADSR.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_ENVELOPE_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_PSCALE</title> +<anchor id="mref-synth-pscale" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_PSCALE.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_PSCALE</phrase></textobject> +</mediaobject> + +<para> +The Synth_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_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% 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_FREEVERB</title> +<anchor id="mref-synth-freeverb" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_FREEVERB.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_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_TREMOLO</title> +<anchor id="mref-synth-tremolo" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_TREMOLO.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_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_FX_CFLANGER</title> +<anchor id="mref-synth-fx-cflanger" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_FX_CFLANGER.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_FX_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 < 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 < 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_PITCH_SHIFT</title> +<anchor id="mref-synth-pitch-shift" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_PITCH_SHIFT.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_PITCH_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_SHELVE_CUTOFF</title> +<anchor id="mref-synth-shelve-cutoff" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_SHELVE_CUTOFF.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_SHELVE_CUTOFF</phrase></textobject> +</mediaobject> + +<para> +Filters out all frequencies over the cutoff frequency. +</para> + +</sect3> + +<sect3 id="mref-synth-brickwall-limiter-sect"> +<title>Synth_BRICKWALL_LIMITER</title> +<anchor id="mref-synth-brickwall-limiter" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_BRICKWALL_LIMITER.png" + format="PNG"/></imageobject> +<textobject><phrase>Synth_BRICKWALL_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_STD_EQUALIZER</title> +<anchor id="mref-synth-std-equalizer" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_STD_EQUALIZER.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_STD_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 > 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_RC</title> +<anchor id="mref-synth-rc" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_RC.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_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_MOOG_VCF</title> +<anchor id="mref-synth-moog-vcf" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_MOOG_VCF.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_MOOG_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_MIDI_TEST</title> +<anchor id="mref-synth-midi-test" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_TEST.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_MIDI_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_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_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_PSCALE (see below). +</para> +</sect3> + +<sect3 id="mref-synth-sequence-freq-sect"> +<title>Synth_SEQUENCE_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_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_PLAY_WAV</title> +<anchor id="mref-synth-play-wav" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_PLAY_WAV.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_PLAY_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_PLAY</title> +<anchor id="mref-synth-play" /> + +<mediaobject> +<imageobject><imagedata fileref="images/Synth_PLAY.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_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_PLAY module, and creating another one will not work. +</para> +</important> + +<para> +The Synth_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_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_AMAN_PLAY module to get something like an output +inside &artsd;. +</para> + +<para> +Note that Synth_PLAY also does the timing of the whole +structure. This means: no Synth_PLAY = no source for timing = no +sound. So you absolutely need (exactly) one Synth_PLAY object. +</para> + +</sect3> + +<sect3 id="mref-synth-record-sect"> +<title>Synth_RECORD</title> +<anchor id="mref-synth-record" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_RECORD.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_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_RECORD module, and creating another one will not work. +</para> +</important> + +<para> +The Synth_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_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_AMAN_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_AMAN_PLAY</title> +<anchor id="mref-synth-aman-play" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_AMAN_PLAY.png" +format="PNG"/></imageobject> +<textobject><phrase>Synth_AMAN_PLAY</phrase></textobject> +</mediaobject> + +<para> +The Synth_AMAN_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_AMAN_RECORD</title> +<anchor id="mref-synth-aman-record" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_AMAN_RECORD.png" format="PNG"/></imageobject> +<textobject><phrase>Synth_AMAN_RECORD</phrase></textobject> +</mediaobject> + +<para> +The Synth_AMAN_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_CAPTURE</title> +<anchor id="mref-synth-capture" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_CAPTURE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_CAPTURE</phrase></textobject> +</mediaobject> + +<para> +The Synth_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_NIL</title> +<anchor id="mref-synth-nil" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_NIL.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_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_DEBUG</title> +<anchor id="mref-synth-debug" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_DEBUG.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_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_MIDI_DEBUG</title> +<anchor id="mref-synth-midi-debug" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_DEBUG.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_MIDI_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_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_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_DATA</title> +<anchor id="mref-synth-data" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_DATA.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_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 & Modulation</title> + +<sect3 id="mref-synth-frequency-sect"> +<title>Synth_FREQUENCY</title> +<anchor id="mref-synth-frequency" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_FREQUENCY.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_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_WAVE_SIN object to the range +0..2*pi. To generate oscillating values from a frequency, a +Synth_FREQUENCY modules is used. +</para> +</sect3> + +<sect3 id="mref-synth-fm-source-sect"> +<title>Synth_FM_SOURCE</title> +<anchor id="mref-synth-fm-source" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_FM_SOURCE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_FM_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_FM_SOURCE (you need to put it to some oscillator +as it only takes the role of Synth_FREQUENCY) and some other +signal to get good results. +</para> + +<para> +Works nicely in combination with Synth_WAVE_SIN +oscillators. +</para> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-waveforms"> +<title>Wave Forms</title> + +<sect3 id="mref-synth-wave-sin-sect"> +<title>Synth_WAVE_SIN</title> +<anchor id="mref-synth-wave-sin" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_SIN.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_SIN</phrase></textobject> +</mediaobject> + +<para> +Sinus oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_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_WAVE_TRI</title> +<anchor id="mref-synth-wave-tri" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_TRI.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_TRI</phrase></textobject> +</mediaobject> + +<para> +Triangle oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_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_NOISE</title> +<anchor id="mref-synth-noise" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_NOISE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_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_WAVE_SQUARE</title> +<anchor id="mref-synth-wave-square" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_WAVE_SQUARE.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_SQUARE</phrase></textobject> +</mediaobject> + +<para> +Square oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_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_WAVE_SOFTSAW</title> +<anchor id="mref-synth-wave-softsaw" /> + +<mediaobject><imageobject><imagedata +fileref="images/Synth_WAVE_SOFTSAW.png" format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_SOFTSAW</phrase></textobject> +</mediaobject> + +<para> +Softened saw wave, similar in look like the Synth_WAVE_TRI +oscillator. Put a pos signal from Synth_FREQUENCY or +Synth_FM_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_WAVE_PULSE</title> +<anchor id="mref-synth-wave-pulse" /> + +<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_PULSE.png" +format="PNG" /></imageobject> +<textobject><phrase>Synth_WAVE_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_FREQUENCY or Synth_FM_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_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> |