1
<!-- <?xml version="1.0" ?>
2
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd">
3
To validate or process this file as a standalone document, uncomment
4
this prolog. Be sure to comment it out again when you are done -->
6
<chapter id="arts-modules">
7
<title>&arts; modules</title>
9
<sect1 id="modules-introduction">
10
<title>Introduction</title>
13
This chapter describes all of the standard &arts; modules. One of the
14
most powerful features of &arts;, modules can be connected together into
15
structures to implement new functions such as effects and instruments.
19
Modules are broken down into two categories. Synthesis modules are used
20
for implementing the <quote>plumbing</quote> that manipulates multimedia
21
data streams to implement new effects, instruments, mixers, and
22
applications. Visual modules allow you to provide a graphical user
23
interface to control the sound structures that are built up with the
29
<sect1 id="synth-modules-reference">
30
<title>Synthesis Modules Reference</title>
34
<sect2 id="mcat-synth-arithmetic-mixing">
35
<title>Arithmetic + Mixing</title>
40
<sect3 id="mref-synth-add-sect">
41
<title>Synth_ADD</title>
42
<anchor id="mref-synth-add" />
46
<imagedata fileref="images/Synth_ADD.png" format="PNG"/></imageobject>
47
<textobject><phrase>Synth_ADD</phrase></textobject>
51
This adds two signals.
56
<sect3 id="mref-synth-mul-sect">
57
<title>Synth_MUL</title>
58
<anchor id="mref-synth-mul"/>
62
<imagedata fileref="images/Synth_MUL.png" format="PNG"/></imageobject>
63
<textobject><phrase>Synth_MUL</phrase></textobject>
67
This multiplies a signal by a factor. You can use this to scale signals
68
down (0 < factor < 1) or up (factor > 1) or invert signals
69
(factor < 0). Note that the factor may be a signal and don't has to
70
be constant (⪚ envelope or real signal).
75
<sect3 id="mref-synth-multi-add-sect">
76
<title>Synth_MULTI_ADD</title>
77
<anchor id="mref-synth-multi-add" />
81
<imagedata fileref="images/Synth_MULTI_ADD.png"
82
format="PNG"/></imageobject>
83
<textobject><phrase>Synth_MULTI_ADD</phrase></textobject>
87
This adds an arbitary number of signals. If you need to sum up the
88
waveforms produces by four different oscillators, you for instance can
89
connect all their outputs to one Synth_MULTI_ADD
90
module. This is more efficient than using three Synth_ADD
96
<sect3 id="mref-synth-xfade-sect">
97
<title>Synth_XFADE</title>
98
<anchor id="mref-synth-xfade" />
101
<imageobject><imagedata fileref="images/Synth_XFADE.png" format="PNG"/>
103
<textobject><phrase>Synth_XFADE</phrase></textobject>
107
This crossfades two signals. If the percentage input is -1, only the
108
left signal is heard, if it is 1, only the right signal is heard. When
109
it is 0, both signals a heard with the same volume.
113
This allows you to ensure that your signal stays in a well defined
114
range. If you had two signals that were between -1 and 1 before
115
crossfading, they will be in the same range after crossfading.
119
<sect3 id="mref-synth-autopanner-sect">
120
<title>Synth_AUTOPANNER</title>
121
<anchor id="mref-synth-autopanner" />
124
The opposite of a crossfader. This takes a mono signal and splits it
125
into a stereo signal: It is used to automatically pan the input signal
126
between the left and the right output. This makes mixes more lively. A
127
standard application would be a guitar or lead sound.
131
Connect a <acronym>LFO</acronym>, a sine or saw wave for example to
132
inlfo. and select a frequency between 0.1 and 5Hz for a traditional
133
effect or even more for Special <acronym>FX</acronym>.
140
<sect2 id="mcat-synth-busses">
141
<title>Busses</title>
146
<sect3 id="mref-synth-bus-uplink-sect">
147
<title>Synth_BUS_UPLINK</title>
148
<anchor id="mref-synth-bus-uplink" />
151
<imageobject><imagedata fileref="images/Synth_BUS_UPLINK.png"
154
<textobject><phrase>Synth_BUS_UPLINK</phrase></textobject>
158
An uplink to a bus. Give signals to left and right, and the name of the
159
bus where the data should go on the <quote>bus</quote> port. The
160
combined signal from all uplinks with this name will appear on every
161
downlink on that <quote>bus</quote>.
165
<sect3 id="mref-synth-bus-downlink-sect">
166
<title>Synth_BUS_DOWNLINK</title>
167
<anchor id="mref-synth-bus-downlink" />
171
<imagedata fileref="images/Synth_BUS_DOWNLINK.png"
172
format="PNG"/></imageobject>
173
<textobject><phrase>Synth_BUS_DOWNLINK</phrase></textobject>
177
Gets (the sum of) all data that is put to a certain bus (with the name
178
you specify at the <quote>bus</quote> port).
184
<!-- TODO AFTER KDE2.1: move freeverb into delays, and rename category to
185
Delays & reverbs -->
187
<sect2 id="mcat-synth-delays">
188
<title>Delays</title>
193
<sect3 id="mref-synth-delay-sect">
194
<title>Synth_DELAY</title>
195
<anchor id="mref-synth-delay" />
198
<imageobject><imagedata fileref="images/Synth_DELAY.png"
199
format="PNG"/></imageobject></mediaobject>
202
This delays the input signal for an amount of time. The time
203
specification must be between 0 and 1 for a delay between 0 seconds and
208
This kind of delay <emphasis>may not be used</emphasis> in feedback
209
structures. This is because it's a variable delay. You can modify it's
210
length while it is running, and even set it down to zero. But since in a
211
feedback structure the own output is needed to calculate the next
212
samples, a delay whose value could drop to zero during synthesis could
213
lead to a stall situation.
217
Use CDELAYs in that setup, perhaps combine a small constant delay (of
218
0.001 seconds) with a flexible delay.
222
You can also combine a CDELAY and a DELAY to achieve a variable length
223
delay with a minimum value in a feedback loop. Just make sure that you
224
have a CDELAY involved.
229
<sect3 id="mref-synth-cdelay-sect">
230
<title>Synth_CDELAY</title>
231
<anchor id="mref-synth-cdelay" />
234
<imageobject><imagedata fileref="images/Synth_CDELAY.png"
235
format="PNG"/></imageobject>
236
<textobject><phrase>Synth_CDELAY</phrase></textobject>
240
This delays the input signal for an amount of time. The time
241
specification must be between 0 and 1 for a delay between 0 seconds and
242
1 second. The delay is constant during the calculation, that means it
247
This saves computing time as no interpolation is done, and is useful for
248
recursive structures. See description above (Synth_DELAY).
255
<sect2 id="mcat-synth-envelopes">
256
<title>Envelopes</title>
261
<sect3 id="mref-synth-envelope-adsr-sect">
262
<title>Synth_ENVELOPE_ADSR</title>
263
<anchor id="mref-synth-envelope-adsr" />
266
<imageobject><imagedata fileref="images/Synth_ENVELOPE_ADSR.png"
267
format="PNG"/></imageobject>
268
<textobject><phrase>Synth_ENVELOPE_ADSR</phrase></textobject>
272
This is a classic <acronym>ADSR</acronym> envelope which means you
281
Whether the note is being pressed right now by the user.
299
The time that should pass between the user presses the note and the signal
300
reaching it's maximum amplitude (in seconds).
309
The time that should pass between the the signal reaching it's maximum
310
amplitude and the signal going back to some constant level (in seconds).
319
The constant level the signal is held at afterwards, until the user
329
The time that should pass after the user has released the note until the
330
signal is scaled down to zero (in seconds).
337
You'll get the scaled signal at outvalue. If the <acronym>ASDR</acronym>
338
envelope is finished, it will set done to 1. You can use this to provide
339
the <quote>done</quote> output of an instrument (which will make the
340
instrument structure be deleted by the &MIDI; router object once the
341
release phase is over).
346
<sect3 id="mref-synth-pscale-sect">
347
<title>Synth_PSCALE</title>
348
<anchor id="mref-synth-pscale" />
351
<imageobject><imagedata fileref="images/Synth_PSCALE.png"
352
format="PNG"/></imageobject>
353
<textobject><phrase>Synth_PSCALE</phrase></textobject>
357
The Synth_PSCALE module will scale the audio stream that is
358
directed through it from a volume 0 (silent) to 1 (original loudness)
359
back to 0 (silent). According to the position (get the position from
360
Synth_SEQUENCE). The position where the peak should occur can be
365
Example: Setting top to 0.1 means that after 10% of the note has
366
been played, the volume has reached its maximum, and starts decaying
373
<sect2 id="mcat-synth-effects">
374
<title>Effects</title>
376
<sect3 id="mref-synth-freeverb-sect">
377
<title>Synth_FREEVERB</title>
378
<anchor id="mref-synth-freeverb" />
381
<imageobject><imagedata fileref="images/Synth_FREEVERB.png"
382
format="PNG"/></imageobject>
383
<textobject><phrase>Synth_FREEVERB</phrase></textobject>
387
This is a reverb effect. In the current implementation, it is thought to
388
pass a stereo signal through the reverb, and it will -add- it's reverb
389
effect to the signal.
394
This means that it can be used inside an StereoEffectStack as well.
399
The input signal should be connected to (inleft, inright), the output
400
signal will be (outleft, outright).
404
The parameters which you can configure are:
409
<term>roomsize</term>
412
The size of the room which the reverb simulates (range: 0..1, where 1 is
413
the largest possible room).
422
This specifies a filter which will make the simulated room absorb high
423
frequencies (range 0..1, where 1 means absorb high frequencies quite
433
The amount of reverb-signal (that is, the amount of the signal that
434
should be modified by the filters, resulting in a <quote>wet</quote>,
435
that is <quote>reverb sound</quote>.
444
The amount of pure signal passed through, resulting in an echo (or
445
combined delay) rather than reverb effect (range: 0..1).
447
<!-- TODO: do some measurements to show that this documentation -is- correct,
448
I am not sure if it is echo, or really pure (non-delayed), or multiple delay
457
The amount of stereo-magic the reverb algorithm adds to the reverb
458
effect, making the reverb sound wider in the stereo panorama (range:
468
[ TODO: I think if mode is 1, the reverb holds the current image of the
469
sound, whereas 0 is normal operation ]
477
<sect3 id="mref-synth-tremolo-sect">
478
<title>Synth_TREMOLO</title>
479
<anchor id="mref-synth-tremolo" />
481
<mediaobject><imageobject><imagedata fileref="images/Synth_TREMOLO.png"
482
format="PNG" /></imageobject>
483
<textobject><phrase>Synth_TREMOLO</phrase></textobject>
487
The tremolo module modulates the amplitude according to a
488
<acronym>LFO</acronym>-Wave. Traditionally you would use a sine wave
489
but why limit yourself? What you get is a very intense effect that cuts
490
through most arrangements because of its high dynamic range. The
491
tremolo effect is still one of guitarists favourite effects although
492
it's not as popular as in the 1960's.
496
[ TODO: currently this is implemented as invalue + abs(inlfo) - maybe it
497
would make more sense to implement it as invalue * (1+inlfo*depth),
498
where depth would be a parameter between 0..1 - decide this after &kde;2.1
499
; if you have a comment, send a mail to the &arts; list ;). ]
503
<sect3 id="mref-synth-fx-cflanger-sect">
504
<title>Synth_FX_CFLANGER</title>
505
<anchor id="mref-synth-fx-cflanger" />
507
<mediaobject><imageobject><imagedata
508
fileref="images/Synth_FX_CFLANGER.png" format="PNG" /></imageobject>
509
<textobject><phrase>Synth_FX_CFLANGER</phrase></textobject>
513
A flanger is a time-varying delay effect. To make development of complex
514
flanger effects simpler, this module is provided, which contains the
515
core of a one-channel flanger.
518
<para>It has the following ports:</para>
525
The signal which you want to process.
534
Preferably a sine wave which modulates the delay time inside the
544
The minimum value for the delay inside the flanger in milliseconds.
545
Suggested values: try something like 1 ms. Please use values < 1000
555
The minimum value for the delay inside the flanger in milliseconds.
556
Suggested values: try something like 5 ms. Please use values < 1000
563
<term>outvalue</term>
566
The output signal. It is important that you mix that with the
567
original (unflanged) signal to get the desired effect.
575
You can use this as a basis for a chorus effect.
583
<sect2 id="mcat-synth-filters">
584
<title>Filters</title>
586
<sect3 id="mref-synth-pitch-shift-sect">
587
<title>Synth_PITCH_SHIFT</title>
588
<anchor id="mref-synth-pitch-shift" />
590
<mediaobject><imageobject><imagedata
591
fileref="images/Synth_PITCH_SHIFT.png" format="PNG"/></imageobject>
592
<textobject><phrase>Synth_PITCH_SHIFT</phrase></textobject>
596
This pitch shifting effect changes the frequency of the input signal
597
without affecting the speed. An application for this is for instance
598
changing the pitch of your voice while you record (and replay) it in
603
The <emphasis>speed</emphasis> parameter is the relative speed with
604
which the signal will be replayed. So a speed of two would make it sound
605
twice as high (&ie; an input frequency of 440 Hz would result in an
606
output frequency of 880 Hz).
610
The <emphasis>frequency</emphasis> parameter is used internally to
611
switch between different grains of the signal. It is tunable, and
612
depending on your choice, the pitch shifting will sound more or less
613
realistic for your use case. A good value to start with is something
619
<sect3 id="mref-synth-shelve-cutoff-sect">
620
<title>Synth_SHELVE_CUTOFF</title>
621
<anchor id="mref-synth-shelve-cutoff" />
623
<mediaobject><imageobject><imagedata
624
fileref="images/Synth_SHELVE_CUTOFF.png" format="PNG"/></imageobject>
625
<textobject><phrase>Synth_SHELVE_CUTOFF</phrase></textobject>
629
Filters out all frequencies over the cutoff frequency.
634
<sect3 id="mref-synth-brickwall-limiter-sect">
635
<title>Synth_BRICKWALL_LIMITER</title>
636
<anchor id="mref-synth-brickwall-limiter" />
638
<mediaobject><imageobject><imagedata
639
fileref="images/Synth_BRICKWALL_LIMITER.png"
640
format="PNG"/></imageobject>
641
<textobject><phrase>Synth_BRICKWALL_LIMITER</phrase></textobject>
645
This modules clips a signal to make it fit into the range of [-1;1]. It
646
doesn't do anything to prevent the distortion that happens when clipping
647
loud signals. You can use this as effect (for instance to create a
648
slightly clipped sine wave). However, it's probably a good idea to run
649
the signal through a lowpass filter afterwards if you do so, to make it
650
sound less agressive.
654
<sect3 id="mref-synth-std-equalizer-sect">
655
<title>Synth_STD_EQUALIZER</title>
656
<anchor id="mref-synth-std-equalizer" />
658
<mediaobject><imageobject><imagedata
659
fileref="images/Synth_STD_EQUALIZER.png" format="PNG" /></imageobject>
660
<textobject><phrase>Synth_STD_EQUALIZER</phrase></textobject>
664
This is a nice parametric equalizer building block. It's parameters are:
669
<term>invalue, outvalue</term>
672
The signal that gets filtered by the equalizer.
681
How low frequencies should be changed. The value is in dB, while 0 means
682
don't change low frequencies, -6 would mean take them out by 6dB, and +6
683
mean boost them by 6dB.
692
How middle frequencies should be changed by the equalizer in dB (see
702
How high frequencies should be changed by the equalizer in dB (see low).
708
<term>frequency</term>
711
This is the center frequency of the equalizer in Hz, the mid frequencies
712
are around that spectrum, the low and high frequencies below and above.
713
Note that the frequency may not be higher than half the sampling rate,
714
usually that is 22050 Hz, and not lower than 1 Hz.
723
This influences how broad the mid spectrum is. It must be be a positive
724
number > 0. A value of one is reasonable, higher values of q mean a
725
narrower spectrum of middle frequencies. Lower values than one mean a
734
<sect3 id="mref-synth-rc-sect">
735
<title>Synth_RC</title>
736
<anchor id="mref-synth-rc" />
738
<mediaobject><imageobject><imagedata fileref="images/Synth_RC.png"
739
format="PNG"/></imageobject>
740
<textobject><phrase>Synth_RC</phrase></textobject>
744
A damped resonator filter filtering all frequencies around some peak
745
value. There is no useful way of specifying middle frequency (that
746
won't be cut), since the input are two strange constants f and b. The
747
code is very old, from the first days of the synthesizer, and will
748
probably replaced by a new filter which will have a frequency and a
749
resonance value as parameters.
753
Try something like b=5, f=5 or b=10, f=10 or b=15, f=15 though.
758
<sect3 id="mref-synth-moog-vcf-sect">
759
<title>Synth_MOOG_VCF</title>
760
<anchor id="mref-synth-moog-vcf" />
762
<mediaobject><imageobject><imagedata fileref="images/Synth_MOOG_VCF.png"
763
format="PNG" /></imageobject>
764
<textobject><phrase>Synth_MOOG_VCF</phrase></textobject>
768
Filters out all frequencies over the cutoff frequency (it's a 24db 4pole
769
filter, which filters -24db per octave above the cutoff frequency), but
770
offers an additional parameter for tuning the filter resonance, while 0
771
means no resonance and 4 means self oscillation.
778
<sect2 id="mcat-synth-midi-sequencing">
779
<title>Midi + Sequencing</title>
784
<sect3 id="mref-synth-midi-test-sect">
785
<title>Synth_MIDI_TEST</title>
786
<anchor id="mref-synth-midi-test" />
788
<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_TEST.png"
789
format="PNG" /></imageobject>
790
<textobject><phrase>Synth_MIDI_TEST</phrase></textobject>
794
This modules loads an instrument structure from a file, and registers
795
itself as midi output with the &arts; &MIDI; manager. Notes sent to this
796
output will result in instrument voices being created.
801
You can setup something like this more convenient in &artscontrol; than
802
manually in &artsbuilder;.
808
<sect3 id="mref-synth-sequence-sect">
809
<title>Synth_SEQUENCE</title>
810
<anchor id="mref-synth-sequence" />
812
<mediaobject><imageobject><imagedata fileref="images/Synth_SEQUENCE.png"
813
format="PNG" /></imageobject></mediaobject>
816
Will play a sequence of notes over and over again. The notes are given
817
in tracker notation, and are seperated by semicolons. An example is
818
<literal>A-3;C-4;E-4;C-4;</literal>. The speed is given as seconds per
819
note, so if you want to get 120 bpm, you will probably specify 0.5
820
seconds/note, as 60 seconds/0.5 seconds per note=120 bpm.
824
You can give each note an length relative to the speed by using a colon
825
after the note and then then
826
length. <literal>A-3:2;C-4:0.5;D-4:0.5;E-4;</literal> demonstrates
827
this. As you see, midi composing programs tend to offer more comfort ;)
831
The Synth_SEQUENCE gives additional information about the
832
position of the note it is playing right now, while 0 means just started
833
and 1 means finished. This information you can use with
834
Synth_PSCALE (see below).
840
<sect2 id="mcat-synth-samples">
841
<title>Samples</title>
843
<sect3 id="mref-synth-play-wav-sect">
844
<title>Synth_PLAY_WAV</title>
845
<anchor id="mref-synth-play-wav" />
848
<imageobject><imagedata fileref="images/Synth_PLAY_WAV.png"
849
format="PNG"/></imageobject>
850
<textobject><phrase>Synth_PLAY_WAV</phrase></textobject>
854
This will play a <literal role="extension">wav</literal> file. It will
855
only be present if you have libaudiofile on your computer. The wave file
856
will start as soon as the module gets created.
860
It will stop as soon as it's over, then finished will be set to 1. The
861
speed parameter can be used to replay the file faster or slower, where
862
1.0 is the normal (recorded) speed.
864
<!-- TODO: KDE2.2: check that this really works together in instruments with
865
the done parameter things ;) -->
870
<sect2 id="mcat-synth-soundio">
871
<title>Sound IO</title>
873
<sect3 id="mref-synth-play-sect">
874
<title>Synth_PLAY</title>
875
<anchor id="mref-synth-play" />
878
<imageobject><imagedata fileref="images/Synth_PLAY.png"
879
format="PNG"/></imageobject>
880
<textobject><phrase>Synth_PLAY</phrase></textobject>
885
You will normally not need this module, unless you are writing
886
standalone applications. Inside &artsd;, there normally is already a
887
Synth_PLAY module, and creating another one will not work.
892
The Synth_PLAY-module will output your audio signal to the
893
soundcard. The left and right channels should contain the
894
<emphasis>normalized</emphasis> input for the channels. If your input
895
is not between -1 and 1, you get clipping.
899
As already mentioned, there may only be one Synth_PLAY module
900
used, as this one directly accesses your soundcard. Use busses if you
901
want to mix more than one audio stream together before playing. Use the
902
Synth_AMAN_PLAY module to get something like an output
907
Note that Synth_PLAY also does the timing of the whole
908
structure. This means: no Synth_PLAY = no source for timing = no
909
sound. So you absolutely need (exactly) one Synth_PLAY object.
914
<sect3 id="mref-synth-record-sect">
915
<title>Synth_RECORD</title>
916
<anchor id="mref-synth-record" />
918
<mediaobject><imageobject><imagedata fileref="images/Synth_RECORD.png"
919
format="PNG"/></imageobject>
920
<textobject><phrase>Synth_RECORD</phrase></textobject>
924
<para>You will normally not need this module, unless you are writing
925
standalone applications. Inside artsd, there normally is already a
926
Synth_RECORD module, and creating another one will not work.
931
The Synth_RECORD-module will record a signal from the soundcard.
932
The left and right channels will contain the input for the channels
937
As already mentioned, there may only be one Synth_RECORD module
938
used, as this one directly accesses your soundcard. Use busses if you
939
want to use the recorded audio stream in more than one place. Use the
940
Synth_AMAN_RECORD module to get something like an input
941
inside artsd. For this to work, &artsd; must run <emphasis>with full
942
duplex enabled </emphasis>.
946
<sect3 id="mref-synth-aman-play-sect">
947
<title>Synth_AMAN_PLAY</title>
948
<anchor id="mref-synth-aman-play" />
950
<mediaobject><imageobject><imagedata fileref="images/Synth_AMAN_PLAY.png"
951
format="PNG"/></imageobject>
952
<textobject><phrase>Synth_AMAN_PLAY</phrase></textobject>
956
The Synth_AMAN_PLAY-module will output your audio signal.
957
It is nice (but not necessary) if you output a normalized signal
962
This module will use the audio manager to assign where the signal will
963
be played. The audio manager can be controlled through &artscontrol;. To
964
make it more intuitive to use, it is good to give the signal you play a
965
name. This can be achieved through setting
966
<emphasis>title</emphasis>. Another feature of the audio manager is to
967
be able to remember where you played a signal the last time. To do so it
968
needs to be able to distinguish signals. That is why you should assign
969
something unique to <emphasis>autoRestoreID</emphasis>, too.
973
<sect3 id="mref-synth-aman-record-sect">
974
<title>Synth_AMAN_RECORD</title>
975
<anchor id="mref-synth-aman-record" />
977
<mediaobject><imageobject><imagedata
978
fileref="images/Synth_AMAN_RECORD.png" format="PNG"/></imageobject>
979
<textobject><phrase>Synth_AMAN_RECORD</phrase></textobject>
983
The Synth_AMAN_RECORD-module will record an audio signal
984
from an external source (&ie;. line in/microphone) within &artsd;. The
985
output will be a normalized signal (between -1 and 1).
989
This module will use the audio manager to assign where the signal will
990
be played. The audio manager can be controlled through artscontrol. To
991
make it more intuitive to use, it is good to give the signal you record
992
a name. This can be achieved through setting
993
<emphasis>title</emphasis>. Another feature of the audio manager is to
994
be able to remember where you recorded a signal the last time. To do so
995
it needs to be able to distinguish signals. That is why you should
996
assign something unique to <emphasis>autoRestoreID</emphasis>, too.
1000
<sect3 id="mref-synth-capture-sect">
1001
<title>Synth_CAPTURE</title>
1002
<anchor id="mref-synth-capture" />
1004
<mediaobject><imageobject><imagedata fileref="images/Synth_CAPTURE.png"
1005
format="PNG" /></imageobject>
1006
<textobject><phrase>Synth_CAPTURE</phrase></textobject>
1010
The Synth_CAPTURE-module will write an audio signal to a wave
1011
file on your hard disc. The file will always be called
1012
<filename>/tmp/mcop-<replaceable>usename</replaceable>/capture.wav</filename>
1018
<sect2 id="mcat-synth-tests">
1019
<title>Tests</title>
1021
<sect3 id="mref-synth-nil-sect">
1022
<title>Synth_NIL</title>
1023
<anchor id="mref-synth-nil" />
1025
<mediaobject><imageobject><imagedata fileref="images/Synth_NIL.png"
1026
format="PNG" /></imageobject>
1027
<textobject><phrase>Synth_NIL</phrase></textobject>
1031
This just does nothing. It is only useful for test situations.
1036
<sect3 id="mref-synth-debug-sect">
1037
<title>Synth_DEBUG</title>
1038
<anchor id="mref-synth-debug" />
1040
<mediaobject><imageobject><imagedata fileref="images/Synth_DEBUG.png"
1041
format="PNG" /></imageobject>
1042
<textobject><phrase>Synth_DEBUG</phrase></textobject>
1046
You can use this for debugging. It will print out the value of the
1047
signal at invalue in regular intervals (ca. 1 second), combined with the
1048
comment you have specified. That way you can find out if some signals
1049
stay in certain ranges, or if they are there at all.
1053
<sect3 id="mref-synth-midi-debug-sect">
1054
<title>Synth_MIDI_DEBUG</title>
1055
<anchor id="mref-synth-midi-debug" />
1057
<mediaobject><imageobject><imagedata fileref="images/Synth_MIDI_DEBUG.png"
1058
format="PNG" /></imageobject>
1059
<textobject><phrase>Synth_MIDI_DEBUG</phrase></textobject>
1063
You can use this to debug how your &MIDI; events are actually arriving
1068
When a MIDI_DEBUG is running &artsserver; will print out a lines
1072
<screen><computeroutput>201 100753.837585 on 0 42 127</computeroutput></screen>
1074
<screen><computeroutput>202 101323.128355 off 0 42</computeroutput></screen>
1077
While the first line would be telling you that 100753ms (that is 100
1078
seconds) after the MIDI_DEBUG started, a &MIDI; on event arrived
1079
on channel 0. This midi on event had the velocity (volume) of 127, the
1080
loudest possible. The next line shows the midi release event. [ TODO:
1081
this does not work currently, make it work, and do it via &MIDI; manager
1086
<sect3 id="mref-synth-data-sect">
1087
<title>Synth_DATA</title>
1088
<anchor id="mref-synth-data" />
1090
<mediaobject><imageobject><imagedata fileref="images/Synth_DATA.png"
1091
format="PNG" /></imageobject>
1092
<textobject><phrase>Synth_DATA</phrase></textobject>
1096
This creates a signal with a constant number.
1098
<!-- TODO: this doesn't really belong in test, does it? -->
1102
<sect2 id="mcat-synth-osc-mod">
1103
<title>Oscillation & Modulation</title>
1105
<sect3 id="mref-synth-frequency-sect">
1106
<title>Synth_FREQUENCY</title>
1107
<anchor id="mref-synth-frequency" />
1109
<mediaobject><imageobject><imagedata fileref="images/Synth_FREQUENCY.png"
1110
format="PNG" /></imageobject>
1111
<textobject><phrase>Synth_FREQUENCY</phrase></textobject>
1115
All oscillators in &arts; don't require a frequency as input, but a
1116
position in the wave. The position should be between 0 and 1, which maps
1117
for a standard Synth_WAVE_SIN object to the range
1118
0..2*pi. To generate oscillating values from a frequency, a
1119
Synth_FREQUENCY modules is used.
1123
<sect3 id="mref-synth-fm-source-sect">
1124
<title>Synth_FM_SOURCE</title>
1125
<anchor id="mref-synth-fm-source" />
1127
<mediaobject><imageobject><imagedata fileref="images/Synth_FM_SOURCE.png"
1128
format="PNG" /></imageobject>
1129
<textobject><phrase>Synth_FM_SOURCE</phrase></textobject>
1133
This is used for frequency modulation. Put your frequency to the
1134
frequency input and put another signal on the modulator input. Then set
1135
modlevel to something, say 0.3. The frequency will be modulated with
1136
modulator then. Just try it. Works nice when you put a feedback in
1137
there, that means take a combination of the delayed output signal from
1138
the Synth_FM_SOURCE (you need to put it to some oscillator
1139
as it only takes the role of Synth_FREQUENCY) and some other
1140
signal to get good results.
1144
Works nicely in combination with Synth_WAVE_SIN
1151
<sect2 id="mcat-synth-waveforms">
1152
<title>Wave Forms</title>
1154
<sect3 id="mref-synth-wave-sin-sect">
1155
<title>Synth_WAVE_SIN</title>
1156
<anchor id="mref-synth-wave-sin" />
1158
<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_SIN.png"
1159
format="PNG" /></imageobject>
1160
<textobject><phrase>Synth_WAVE_SIN</phrase></textobject>
1164
Sinus oscillator. Put a pos signal from Synth_FREQUENCY or
1165
Synth_FM_SOURCE at the input. And get a sinus wave as
1166
output. The pos signal specifies the position in the wave, the range
1167
0..1 is mapped to 0..2*pi internally.
1172
<sect3 id="mref-synth-wave-tri-sect">
1173
<title>Synth_WAVE_TRI</title>
1174
<anchor id="mref-synth-wave-tri" />
1176
<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_TRI.png"
1177
format="PNG" /></imageobject>
1178
<textobject><phrase>Synth_WAVE_TRI</phrase></textobject>
1182
Triangle oscillator. Put a pos signal from Synth_FREQUENCY or
1183
Synth_FM_SOURCE at the input. And get a triangle wave as
1184
output. The pos signal specifies the position in the wave, the range
1185
0..1 is mapped to 0..2*pi internally. Be careful. The input signal
1186
<emphasis>must</emphasis> be in the range 0..1 for the output signal to
1187
produce good results.
1191
<sect3 id="mref-synth-noise-sect">
1192
<title>Synth_NOISE</title>
1193
<anchor id="mref-synth-noise" />
1195
<mediaobject><imageobject><imagedata fileref="images/Synth_NOISE.png"
1196
format="PNG" /></imageobject>
1197
<textobject><phrase>Synth_NOISE</phrase></textobject>
1201
Noise generator. This generates a random signal between -1 and 1.
1206
<sect3 id="mref-synth-wave-square-sect">
1207
<title>Synth_WAVE_SQUARE</title>
1208
<anchor id="mref-synth-wave-square" />
1210
<mediaobject><imageobject><imagedata
1211
fileref="images/Synth_WAVE_SQUARE.png" format="PNG" /></imageobject>
1212
<textobject><phrase>Synth_WAVE_SQUARE</phrase></textobject>
1216
Square oscillator. Put a pos signal from Synth_FREQUENCY or
1217
Synth_FM_SOURCE at the input. And get a square wave as
1218
output. The pos signal specifies the position in the wave, the range
1219
0..1 is mapped to 0..2*pi internally. Be careful. The input signal
1220
<emphasis>must</emphasis> be in the range 0..1 for the output signal to
1221
produce good results.
1225
<sect3 id="mref-synth-wave-softsaw-sect">
1226
<title>Synth_WAVE_SOFTSAW</title>
1227
<anchor id="mref-synth-wave-softsaw" />
1229
<mediaobject><imageobject><imagedata
1230
fileref="images/Synth_WAVE_SOFTSAW.png" format="PNG" /></imageobject>
1231
<textobject><phrase>Synth_WAVE_SOFTSAW</phrase></textobject>
1235
Softened saw wave, similar in look like the Synth_WAVE_TRI
1236
oscillator. Put a pos signal from Synth_FREQUENCY or
1237
Synth_FM_SOURCE at the input. You'll get a softened saw
1238
wave as output. The pos signal specifies the position in the wave, the
1239
range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal
1240
<emphasis>must</emphasis> be in the range 0..1 for the output signal to
1241
produce good results.
1245
<sect3 id="mref-synth-wave-pulse-sect">
1246
<title>Synth_WAVE_PULSE</title>
1247
<anchor id="mref-synth-wave-pulse" />
1249
<mediaobject><imageobject><imagedata fileref="images/Synth_WAVE_PULSE.png"
1250
format="PNG" /></imageobject>
1251
<textobject><phrase>Synth_WAVE_PULSE</phrase></textobject>
1255
Pulse oscillator - this module is similar in spirit like the rectangular
1256
oscillator (Synth_WAVE_RECT), but it provides a configurable up/down
1257
ratio, through the <emphasis>dutycycle</emphasis> parameter. Put a pos
1258
signal from Synth_FREQUENCY or Synth_FM_SOURCE at
1259
the input. Get a pulse wave as output. The pos signal specifies the
1260
position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be
1261
careful. The input signal <emphasis>must</emphasis> be in the range 0..1
1262
for the output signal to produce good results.
1268
<sect1 id="visual-modules-reference">
1269
<title>Visual Modules Reference</title>
1272
TODO when visual modules are more "finished".
added
removed
doc/artsbuilder/modules.docbook
