From e2de64d6f1beb9e492daf5b886e19933c1fa41dd Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/artsbuilder/modules.docbook | 1336 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 1336 insertions(+) create mode 100644 doc/artsbuilder/modules.docbook (limited to 'doc/artsbuilder/modules.docbook') 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 @@ + + + +&arts; modules + + +Introduction + + +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. + + + +Modules are broken down into two categories. Synthesis modules are used +for implementing the plumbing 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. + + + + + +Synthesis Modules Reference + + + + +Arithmetic + Mixing + + + + + +Synth_ADD + + + + + +Synth_ADD + + + +This adds two signals. + + + + + +Synth_MUL + + + + + +Synth_MUL + + + +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). + + + + + +Synth_DIV + + + + + +Synth_DIV + + + +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. + + + + + +Synth_MULTI_ADD + + + + + +Synth_MULTI_ADD + + + +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. + + + + + +Synth_XFADE + + + + + +Synth_XFADE + + + +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. + + + +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. + + + + +Synth_AUTOPANNER + + + +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. + + + +Connect a LFO, 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 FX. + + + + + + + +Busses + + +Synth_BUS_UPLINK + + + + + +Synth_BUS_UPLINK + + + +An uplink to a bus. Give signals to left and right, and the name of the +bus where the data should go on the bus port. The +combined signal from all uplinks with this name will appear on every +downlink on that bus. + + + + +Synth_BUS_DOWNLINK + + + + + +Synth_BUS_DOWNLINK + + + +Gets (the sum of) all data that is put to a certain bus (with the name +you specify at the bus port). + + + + + + + + +Delays + + + + + +Synth_DELAY + + + + + + +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. + + + +This kind of delay may not be used 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. + + + +Use CDELAYs in that setup, perhaps combine a small constant delay (of +0.001 seconds) with a flexible delay. + + + +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. + + + + + +Synth_CDELAY + + + + +Synth_CDELAY + + + +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. + + + +This saves computing time as no interpolation is done, and is useful for +recursive structures. See description above (Synth_DELAY). + + + + + + + +Envelopes + + + + + +Synth_ENVELOPE_ADSR + + + + +Synth_ENVELOPE_ADSR + + + +This is a classic ADSR envelope which means you +specify: + + + + +active + + +Whether the note is being pressed right now by the user. + + + + + +invalue + + +The input signal. + + + + + +attack + + +The time that should pass between the user presses the note and the signal +reaching it's maximum amplitude (in seconds). + + + + + +decay + + +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). + + + + + +sustain + + +The constant level the signal is held at afterwards, until the user +releases the note. + + + + + +release + + +The time that should pass after the user has released the note until the +signal is scaled down to zero (in seconds). + + + + + + +You'll get the scaled signal at outvalue. If the ASDR +envelope is finished, it will set done to 1. You can use this to provide +the done output of an instrument (which will make the +instrument structure be deleted by the &MIDI; router object once the +release phase is over). + + + + + +Synth_PSCALE + + + + +Synth_PSCALE + + + +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. + + + +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. + + + + + + +Effects + + +Synth_FREEVERB + + + + +Synth_FREEVERB + + + +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. + + + + +This means that it can be used inside an StereoEffectStack as well. + + + + +The input signal should be connected to (inleft, inright), the output +signal will be (outleft, outright). + + + +The parameters which you can configure are: + + + + +roomsize + + +The size of the room which the reverb simulates (range: 0..1, where 1 is +the largest possible room). + + + + + +damp + + +This specifies a filter which will make the simulated room absorb high +frequencies (range 0..1, where 1 means absorb high frequencies quite +aggressive). + + + + + +wet + + +The amount of reverb-signal (that is, the amount of the signal that +should be modified by the filters, resulting in a wet, +that is reverb sound. + + + + + +dry + + +The amount of pure signal passed through, resulting in an echo (or +combined delay) rather than reverb effect (range: 0..1). + + + + + + +width + + +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). + + + + + +mode + + +[ TODO: I think if mode is 1, the reverb holds the current image of the +sound, whereas 0 is normal operation ] + + + + + + + + +Synth_TREMOLO + + + +Synth_TREMOLO + + + +The tremolo module modulates the amplitude according to a +LFO-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. + + + +[ 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 ;). ] + + + + +Synth_FX_CFLANGER + + + +Synth_FX_CFLANGER + + + +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. + + +It has the following ports: + + + +invalue + + +The signal which you want to process. + + + + + +lfo + + +Preferably a sine wave which modulates the delay time inside the +flanger (-1 .. 1). + + + + + +mintime + + +The minimum value for the delay inside the flanger in milliseconds. +Suggested values: try something like 1 ms. Please use values < 1000 +ms. + + + + + +maxtime + + +The minimum value for the delay inside the flanger in milliseconds. +Suggested values: try something like 5 ms. Please use values < 1000 +ms. + + + + + +outvalue + + +The output signal. It is important that you mix that with the +original (unflanged) signal to get the desired effect. + + + + + + + +You can use this as a basis for a chorus effect. + + + + + + + + +Filters + + +Synth_PITCH_SHIFT + + + +Synth_PITCH_SHIFT + + + +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. + + + +The speed 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). + + + +The frequency 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. + + + + + +Synth_SHELVE_CUTOFF + + + +Synth_SHELVE_CUTOFF + + + +Filters out all frequencies over the cutoff frequency. + + + + + +Synth_BRICKWALL_LIMITER + + + +Synth_BRICKWALL_LIMITER + + + +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. + + + + +Synth_STD_EQUALIZER + + + +Synth_STD_EQUALIZER + + + +This is a nice parametric equalizer building block. It's parameters are: + + + + +invalue, outvalue + + +The signal that gets filtered by the equalizer. + + + + + +low + + +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. + + + + + +mid + + +How middle frequencies should be changed by the equalizer in dB (see +low). + + + + + +high + + +How high frequencies should be changed by the equalizer in dB (see low). + + + + + +frequency + + +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. + + + + + +q + + +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. + + + + + + + + +Synth_RC + + + +Synth_RC + + + +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. + + + +Try something like b=5, f=5 or b=10, f=10 or b=15, f=15 though. + + + + + +Synth_MOOG_VCF + + + +Synth_MOOG_VCF + + + +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. + + + + + + + +Midi + Sequencing + + +Synth_MIDI_TEST + + + +Synth_MIDI_TEST + + + +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. + + + + +You can setup something like this more convenient in &artscontrol; than +manually in &arts-builder;. + + + + + + +Synth_SEQUENCE + + + + + +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 +A-3;C-4;E-4;C-4;. 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. + + + +You can give each note an length relative to the speed by using a colon +after the note and then then +length. A-3:2;C-4:0.5;D-4:0.5;E-4; demonstrates +this. As you see, midi composing programs tend to offer more comfort ;) + + + +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). + + + + +Synth_SEQUENCE_FREQ + + + + + +This module works just like Synth_SEQUENCE with the only difference that +you don't write notenames but frequencies. + + + + + + + +Samples + + +Synth_PLAY_WAV + + + + +Synth_PLAY_WAV + + + +This will play a wav 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. + + + +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. + + + + + + + +Sound IO + + +Synth_PLAY + + + + +Synth_PLAY + + + + +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. + + + + +The Synth_PLAY-module will output your audio signal to the +soundcard. The left and right channels should contain the +normalized input for the channels. If your input +is not between -1 and 1, you get clipping. + + + +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;. + + + +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. + + + + + +Synth_RECORD + + + +Synth_RECORD + + + +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. + + + + +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). + + + +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 with full +duplex enabled . + + + + +Synth_AMAN_PLAY + + + +Synth_AMAN_PLAY + + + +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). + + + +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 +title. 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 autoRestoreID, too. + + + + +Synth_AMAN_RECORD + + + +Synth_AMAN_RECORD + + + +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). + + + +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 +title. 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 autoRestoreID, too. + + + + +Synth_CAPTURE + + + +Synth_CAPTURE + + + +The Synth_CAPTURE-module will write an audio signal to a wave +file on your hard disc. The file will always be called +/tmp/mcop-usename/capture.wav + + + + + + +Tests + + +Synth_NIL + + + +Synth_NIL + + + +This just does nothing. It is only useful for test situations. + + + + + +Synth_DEBUG + + + +Synth_DEBUG + + + +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. + + + + +Synth_MIDI_DEBUG + + + +Synth_MIDI_DEBUG + + + +You can use this to debug how your &MIDI; events are actually arriving +in &arts;. + + + +When a MIDI_DEBUG is running &artsserver; will print out a lines +like: + + +201 100753.837585 on 0 42 127 + +202 101323.128355 off 0 42 + + +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 +]. + + + + +Synth_DATA + + + +Synth_DATA + + + +This creates a signal with a constant number. + + + + + + +Oscillation & Modulation + + +Synth_FREQUENCY + + + +Synth_FREQUENCY + + + +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. + + + + +Synth_FM_SOURCE + + + +Synth_FM_SOURCE + + + +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. + + + +Works nicely in combination with Synth_WAVE_SIN +oscillators. + + + + + + +Wave Forms + + +Synth_WAVE_SIN + + + +Synth_WAVE_SIN + + + +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. + + + + + +Synth_WAVE_TRI + + + +Synth_WAVE_TRI + + + +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 +must be in the range 0..1 for the output signal to +produce good results. + + + + +Synth_NOISE + + + +Synth_NOISE + + + +Noise generator. This generates a random signal between -1 and 1. + + + + + +Synth_WAVE_SQUARE + + + +Synth_WAVE_SQUARE + + + +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 +must be in the range 0..1 for the output signal to +produce good results. + + + + +Synth_WAVE_SOFTSAW + + + +Synth_WAVE_SOFTSAW + + + +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 +must be in the range 0..1 for the output signal to +produce good results. + + + + +Synth_WAVE_PULSE + + + +Synth_WAVE_PULSE + + + +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 dutycycle 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 must be in the range 0..1 +for the output signal to produce good results. + + + + +Miscellaneous + + +Synth_COMPRESSOR + + + + + + +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. + + + +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. + + + +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. + + + + + + + +Visual Modules Reference + + +TODO when visual modules are more "finished". + + + + -- cgit v1.2.1