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. Synth_ADD This adds two signals. 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 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 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 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. 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. 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 Gets (the sum of) all data that is put to a certain bus (with the name you specify at the bus port). 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 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). 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 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. 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 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 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. 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 Filters out all frequencies over the cutoff frequency. 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 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 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 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. 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;. 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). This module works just like Synth_SEQUENCE with the only difference that you don't write notenames but frequencies. 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. 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 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 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 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 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 Synth_NIL This just does nothing. It is only useful for test situations. 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 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 This creates a signal with a constant number. 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 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. 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 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 Noise generator. This generates a random signal between -1 and 1. 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 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 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. 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. TODO when visual modules are more "finished".