# &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&lowbar;ADD

Synth&lowbar;ADD

This adds two signals.

#### Synth&lowbar;MUL

Synth&lowbar;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 (e.g. envelope or real signal).

#### Synth&lowbar;MULTI&lowbar;ADD

Synth&lowbar;MULTI&lowbar;ADD

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

#### Synth&lowbar;XFADE

Synth&lowbar;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&lowbar;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&lowbar;BUS&lowbar;UPLINK

Synth&lowbar;BUS&lowbar;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&lowbar;BUS&lowbar;DOWNLINK

Synth&lowbar;BUS&lowbar;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&lowbar;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&lowbar;CDELAY

Synth&lowbar;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&lowbar;DELAY).

### Envelopes

#### Synth&lowbar;ENVELOPE&lowbar;ADSR

Synth&lowbar;ENVELOPE&lowbar;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&lowbar;PSCALE

Synth&lowbar;PSCALE

The Synth&lowbar;PSCALE module will scale the audio stream that is directed through it from a volume 0 (silent) to 1 (original loudness) back to 0 (silent). According to the position (get the position from Synth&lowbar;SEQUENCE). The position where the peak should occur can be given as pos.

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

### Effects

#### Synth&lowbar;FREEVERB

Synth&lowbar;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 agressive).

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&lowbar;TREMOLO

Synth&lowbar;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 favourite 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&lowbar;FX&lowbar;CFLANGER

Synth&lowbar;FX&lowbar;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&lowbar;PITCH&lowbar;SHIFT

Synth&lowbar;PITCH&lowbar;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 (i.e. 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&lowbar;SHELVE&lowbar;CUTOFF

Synth&lowbar;SHELVE&lowbar;CUTOFF

Filters out all frequencies over the cutoff frequency.

#### Synth&lowbar;BRICKWALL&lowbar;LIMITER

Synth&lowbar;BRICKWALL&lowbar;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 agressive.

#### Synth&lowbar;STD&lowbar;EQUALIZER

Synth&lowbar;STD&lowbar;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 sprectrum.

#### Synth&lowbar;RC

Synth&lowbar;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&lowbar;MOOG&lowbar;VCF

Synth&lowbar;MOOG&lowbar;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&lowbar;MIDI&lowbar;TEST

Synth&lowbar;MIDI&lowbar;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 &artsbuilder;.

#### Synth&lowbar;SEQUENCE

Will play a sequence of notes over and over again. The notes are given in tracker notation, and are seperated 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&lowbar;SEQUENCE gives additional information about the position of the note it is playing right now, while 0 means just started and 1 means finished. This information you can use with Synth&lowbar;PSCALE (see below).

### Samples

#### Synth&lowbar;PLAY&lowbar;WAV

Synth&lowbar;PLAY&lowbar;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&lowbar;PLAY

Synth&lowbar;PLAY

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

The Synth&lowbar;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&lowbar;PLAY module used, as this one directly accesses your soundcard. Use busses if you want to mix more than one audio stream together before playing. Use the Synth&lowbar;AMAN&lowbar;PLAY module to get something like an output inside &artsd;.

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

#### Synth&lowbar;RECORD

Synth&lowbar;RECORD

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

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

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

#### Synth&lowbar;AMAN&lowbar;PLAY

Synth&lowbar;AMAN&lowbar;PLAY

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

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&lowbar;AMAN&lowbar;RECORD

Synth&lowbar;AMAN&lowbar;RECORD

The Synth&lowbar;AMAN&lowbar;RECORD-module will record an audio signal from an external source (i.e.. 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&lowbar;CAPTURE

Synth&lowbar;CAPTURE

The Synth&lowbar;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&lowbar;NIL

Synth&lowbar;NIL

This just does nothing. It is only useful for test situations.

#### Synth&lowbar;DEBUG

Synth&lowbar;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&lowbar;MIDI&lowbar;DEBUG

Synth&lowbar;MIDI&lowbar;DEBUG

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

When a MIDI&lowbar;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&lowbar;DEBUG started, a &MIDI; on event arrived on channel 0. This midi on event had the velocity (volume) of 127, the loudest possible. The next line shows the midi release event. [ TODO: this does not work currently, make it work, and do it via &MIDI; manager ].

#### Synth&lowbar;DATA

Synth&lowbar;DATA

This creates a signal with a constant number.

### Oscillation & Modulation

#### Synth&lowbar;FREQUENCY

Synth&lowbar;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&lowbar;WAVE&lowbar;SIN object to the range 0..2*pi. To generate oscillating values from a frequency, a Synth&lowbar;FREQUENCY modules is used.

#### Synth&lowbar;FM&lowbar;SOURCE

Synth&lowbar;FM&lowbar;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&lowbar;FM&lowbar;SOURCE (you need to put it to some oscillator as it only takes the role of Synth&lowbar;FREQUENCY) and some other signal to get good results.

Works nicely in combination with Synth&lowbar;WAVE&lowbar;SIN oscillators.

### Wave Forms

#### Synth&lowbar;WAVE&lowbar;SIN

Synth&lowbar;WAVE&lowbar;SIN

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

#### Synth&lowbar;WAVE&lowbar;TRI

Synth&lowbar;WAVE&lowbar;TRI

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

#### Synth&lowbar;NOISE

Synth&lowbar;NOISE

Noise generator. This generates a random signal between -1 and 1.

#### Synth&lowbar;WAVE&lowbar;SQUARE

Synth&lowbar;WAVE&lowbar;SQUARE

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

#### Synth&lowbar;WAVE&lowbar;SOFTSAW

Synth&lowbar;WAVE&lowbar;SOFTSAW

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

#### Synth&lowbar;WAVE&lowbar;PULSE

Synth&lowbar;WAVE&lowbar;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&lowbar;FREQUENCY or Synth&lowbar;FM&lowbar;SOURCE at the input. Get a pulse wave as output. The pos signal specifies the position in the wave, the range 0..1 is mapped to 0..2*pi internally. Be careful. The input signal must be in the range 0..1 for the output signal to produce good results.

### Miscellaneous

#### Synth&lowbar;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".