commit 63faaec1e3d61379b860ba1ea010586fc51c6637
parent 842e9db4ee039cdb6f59dbd26d6e76951261bcf7
Author: Johannes Lorenz <[email protected]>
Date: Sun, 7 Apr 2013 20:20:02 +0200
Completed equalizer docs. Fixed some bugs in the other effects.
Diffstat:
| M | doc/effects.txt | | | 266 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------- |
1 file changed, 219 insertions(+), 47 deletions(-)
diff --git a/doc/effects.txt b/doc/effects.txt
@@ -1,16 +1,21 @@
Effects
-------
-Effects are, generally, blackboxes that transform audio signals in a specified way. More exactly, the only input data for an effect in Zynaddsubfx is:
+Effects are, generally, blackboxes that transform audio signals in a
+specified way. More exactly, the only input data for an effect in ZynAddSubFX
+is:
* an array of samples, which is read *on line*
* the current system time (used for LFOs)
The output is the transformed array of samples.
-NOTE: As described, effects have no information about anything else. For example, key presses are not recognized. Therefore, pressing a key does not initiate the LFO. Phase nobs will always be relative to a *global* LFO, which is only dependent on the system time.
+NOTE: As described, effects have no information about anything else. For
+example, key presses are not recognized. Therefore, pressing a key does not
+initiate the LFO. Phase nobs will always be relative to a *global* LFO, which is
+only dependent on the system time.
-ZynAddSubFx has 3 types of effects:
+ZynAddSubFX has 3 types of effects:
* System Effects
* Insertion Effects
@@ -21,31 +26,107 @@ TODO: Describe these 3 types.
General topics
~~~~~~~~~~~~~~
-* *Wetness* determines the mix of the results of the effect and its input. This mix is made the effects output. If an effect is wet, it means that nothing of the input signal is bypassing the effect. If it is dry, then the effect has no effect.
-* *Filter stages* are the number of times that this filter is applied in series. So, if this number is 1, you simply have this one filter. If it is two, the sound first passes the filter, and the results then pass the same filter again. In ZynAddSubFx, the wetness is applied after all stages were passed.
+* *Wetness* determines the mix of the results of the effect and its input. This
+mix is made the effects output. If an effect is wet, it means that nothing of
+the input signal is bypassing the effect. If it is dry, then the effect has no
+effect.
+* *Filter stages* are the number of times that this filter is applied in series.
+So, if this number is 1, you simply have this one filter. If it is two, the
+sound first passes the filter, and the results then pass the same filter again.
+In ZynAddSubFX, the wetness is applied after all stages were passed.
TODO: Can you make a diagram for these two, please?
Equalizer
~~~~~~~~~
-An equalizer is a filter effect that applies different volume to different frequencies of the input signal. http://en.wikipedia.org/wiki/Filter_%28signal_processing%29[Wikipedia] has some information about filters. Also, most of ZynAddSubFx's implementations follow the http://www.harmony-central.com/Computer/Programming/Audio-EQ-Cookbook.txt["Cookbook formulae for audio EQ"] by Robert Bristow-Johnson.
+Introduction
+^^^^^^^^^^^^
-There are different types of filters. The number of poles ... TODO
+An equalizer is a filter effect that applies different volume to
+different frequencies of the input signal. This can, for example, to "filter
+out" unwanted frequencies.
+http://en.wikipedia.org/wiki/Filter_%28signal_processing%29[Wikipedia] has some
+information about filters. Also, most of ZynAddSubFX's implementations follow
+the http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt["Cookbook formulae for
+audio EQ"] by Robert Bristow-Johnson.
-ZynAddSubFx offers the following filters:
+Filter Types
+^^^^^^^^^^^^
-* LPF 1 means Low Pass Filter with one pole. TODO: more description
-* LPF 2 means Low Pass Filter with two poles.
-* HPF 1 means High Pass Filter with one pole.
-* HPF 2 means High Pass Filter with two poles.
-* BPF 2 means Band Pass Filter with two poles.
-* NF 2 means Notch Filter with two poles
-* PK 2 means Peak Filter with two poles.
-* LS 2 Means Low Shelf with two poles.
-* HS 2 means High Shelf with two poles.
+There are different types of filters. The number of poles define what will
+happen at a given frequency. Mathematically, the filters are functions which
+have poles at that frequency. Usually, two poles mean that the function has more
+"steepness", and that you can set the exact value of the function at the poles
+by defining the "resonance value". Filters with two poles are also often
+referenced as http://de.wikipedia.org/wiki/Butterworth-Filter[Butterworth
+Filters].
+
+********************************************************************
+For the interested, functions having poles means that we are given a quotient of
+polynomials. The denominator has degree 1 or 2, depending on the filter having
+one or two poles. In the file _DSP/AnalogFilter.cpp_,
+_AnalogFilter::computefiltercoefs()_ sets the coefficients (depending on the
+filter type), and _AnalogFilter::singlefilterout()_ shows the whole polynomial
+(in a formula where no quotient is needed).
+********************************************************************
-TODO: describe other nobs...
+The term passband (or often just "band") refers to the amount of frequencies
+which are not (or sometimes "not much") attenuated by the filter.
+
+There are different types of filters:
+
+* Low-Pass Filters - they let pass only the frequencies lower than the cutoff
+frequency
+* High-Pass Filters - they let pass only the frequencies higher than the cutoff
+frequency
+* Low Shelf and High shelf filters are special types of LP and HP with less
+passband.
+* Band-Pass Filters - they let pass only the frequencies close to the cutoff
+frequency
+* Peak Filters are Band-Pass Filters with only a small amount of frequencies
+("a peak") being passed
+* Band-Reject Filters - they let pass only frequencies not close to the cutoff
+frequency
+* Notch Filters are Band-Reject Filters with only a small amount of frequencies
+("a notch") being rejected
+
+You can what ZynAddSubFX's filters do in the graphical window. The following
+explains the abbreviations.
+
+* LPF 1: Low-Pass, 1 pole.
+* LPF 2: Low-Pass, 2 poles.
+* HPF 1: High-Pass, 1 pole.
+* HPF 2: High-Pass, 2 poles.
+* BPF 2: Band-Pass, 2 poles.
+* NF 2: Notch, 2 poles.
+* PK 2: Peak, 2 poles.
+* LS 2 Low Shelf, 2 poles.
+* HS 2 High Shelf, 2 poles.
+
+Filter GUI
+^^^^^^^^^^
+
+We describe all parts of the GUI here.
+
+* The gain defines an offset which is added to the complete filter.
+* The graphical window shows you the resulting filter type. This can be very
+helpful to understand how the filters work.
+* *B.* lets you choose the passband number. Multiple passbands define one
+filter. This is important if you want multiple filters to be called after each
+other. Note that filters are commutative.
+* *T.* lets you choose the current filter's type, as described above.
+* *Freq* describes the frequencies where the filter has its poles. For some
+filters, this is called the "cutoff" frequency. Note, however, that a bandpass
+filter has two cutoff frequencies.
+* *Gain* is only active for some filters and sets the amount of a special peak
+these filters have. Note that for those filters, using the predefined gain makes
+them effectless.
+* *Resonance* lets you describe a peak at the given frequency for filters with
+2 poles. This can be compared to real physical objects that have more gain at
+their resonance frequency.
+* *St.* lets you define multiple filter stages. This is equivalent to having
+multiple bands of the same filter.
Chorus
~~~~~~
@@ -53,9 +134,25 @@ Chorus
Introduction
^^^^^^^^^^^^
-In a chorus, there are many people. Even if each of them sings at exactly the same frequency, all their voices usually sound different. We say the have a different timbre. Timbre is the way we perceive sound and makes us differ between different music instruments. This is, physically, achieved by varying both the amplitude envelope and the frequency spectrum. Multiple sounds with slightly different timbre make a sound more shimmering, or powerful. This is the chorus effect.
+In a chorus, there are many people. Even if each of them sings at exactly
+the same frequency, all their voices usually sound different. We say the have a
+different timbre. Timbre is the way we perceive sound and makes us differ
+between different music instruments. This is, physically, achieved by varying
+both the amplitude envelope and the frequency spectrum. Multiple sounds with
+slightly different timbre make a sound more shimmering, or powerful. This is the
+chorus effect.
+
+The chorus effect can be achieved by multiple people singing together. In
+a concert, there are many instruments, resulting in the same effect. When making
+electronic music, we only have an input wave and have to generate these
+different timbres by ourselves. ZynAddSubFx therefore simply plays the sound,
+pitch modulated by an LFO, and adds this to the original sound. This explains
+the diagram below: The multiple pitches are generated by a delayed version of
+the input. This version is being pitched by an LFO. More detailled, this pitch
+is generated by varying the reading speed of the delayed sound by an LFO.
+
+Related effects to Chorus are Flangers.
-The chorus effect can be achieved by multiple people singing together. In a concert, there are many instruments, resulting in the same effect. When making electronic music, we only have an input wave and have to generate these different timbres by ourselves.
Description
^^^^^^^^^^^
@@ -64,12 +161,23 @@ We explain the functionality in a diagram and list the components below.
image::./gen/chorus.png[width="700"]
-We explain it in detail:
-
-* First, crossover is applied. The *LR Mix* wheel lets you set the amount. If you set it to the highest possible value, you will always have a stereo input.
-* ...
-* Next, the singal can be negated, If the *Neg* Checkbox is activated, the amplitude is multiplied by -1.
-* Finally, *Panning* is applied.
+* First, crossover is applied. The *LR Mix* knob lets you set the amount. If
+you set it to 0.0, you will always have a stereo input.
+* The following 4 knobs control the LFO.
+** *Freq* determines the LFO's frequency
+** *Rnd* determines the LFO amplitude's randomness
+** *LFO Type* lets you choose the type of LFO
+** *St.df* lets you determine how much left and right LFO are phase shifted.
+64.0f means stereo, higher values increase the right lfo relatively to the left
+one.
+* *Delay* is the time that the delayed sound is delayed "on average". Note that
+the delay also depends a bit on the current pitch.
+* After the correct element of the sound buffer is found using the LFO, the
+feedback let
+* Next, the singal can be negated, If the *Neg* Checkbox is activated,
+the amplitude is multiplied by -1.
+* Finally, *Panning* is applied. Set it to 0.0 to only hear output on the right
+side.
Distort
~~~~~~~
@@ -77,11 +185,22 @@ Distort
Introduction
^^^^^^^^^^^^
-Distortion means, in general, altering a signal. Natural instruments usually produce sine like waves. A wave is transformed in an unnatural way when distortion is used. The most distorted waves are pulse waves. It is typical for distortion to add overtones to a sound. Distortion often increases the power and the http://en.wikipedia.org/wiki/Loudness[loudness] of a signal, while the db level is not increased.
+Distortion means, in general, altering a signal. Natural instruments
+usually produce sine like waves. A wave is transformed in an unnatural way when
+distortion is used. The most distorted waves are pulse waves. It is typical for
+distortion to add overtones to a sound. Distortion often increases the power and
+the http://en.wikipedia.org/wiki/Loudness[loudness] of a signal, while the db
+level is not increased.
-Distortion can happen in many situations when working with audio. Often, this is not wanted. In classical music, for example, distortion does not occur naturally. However, distortion can also be a wanted effect. It is typical for Rock guitars, but also present in electronic music, mostly in Dubstep and DrumNBass. Distortion is an important topic in the http://en.wikipedia.org/wiki/Loudness_war[Loudness War].
+Distortion can happen in many situations when working with audio. Often, this is
+not wanted. In classical music, for example, distortion does not occur
+naturally. However, distortion can also be a wanted effect. It is typical for
+Rock guitars, but also present in electronic music, mostly in Dubstep and
+DrumNBass. Distortion is an important topic in the
+http://en.wikipedia.org/wiki/Loudness_war[Loudness War].
-NOTE: As distortion increases loudness, distorted music can cause ear damage at lower volume levels. Thus, you might want to use it a bit careful.
+NOTE: As distortion increases loudness, distorted music can cause ear damage
+at lower volume levels. Thus, you might want to use it a bit careful.
Description
^^^^^^^^^^^
@@ -90,32 +209,67 @@ We explain the functionality in a diagram and list the components below.
image::./gen/distort.png[width="700"]
-* Negation is the first thing to happen. If the *Neg* Checkbox is activated, the amplitude is multiplied by -1.
-* Panning is applied. Note, however, that you have to activate the Stereo Checkbox, labeled *St*, before.
-* Pre amplification is done next. The amount can be changed using the *Drive* nob. Indeed, this is the amount of distortion. For example, if you clip a signal, the louder the input gets, the more distortion you will get. This can have different meanings for different types of distortion, as described below.
-* Before applying the waveshape, or afterwards, you can apply Highpass and Lowpass filters. The type is HPF2 or LPF2, meaning butterworth lowpasses. They are labeled *HPF* and *LPF*. Whether this is done before, or after the waveshape, depends on the checkbox labeled *PF*.
-* The next step is the wave shape. This defines how the wave is actually modified. The *Type* ComboBox lets you define how. We will discuss some types below.
-* After the wave shape, we scale the level again. This is called output amplification. You can change the value using the *Level* wheel.
-* Crossover is the last step. This is controlled by the wheel *LR Mix* and means that afterwards, a percentage of the left side is applied to the right side, and, synchronously, the other way round. It is a kind of interpolation between left and right. If you set the LR Mix to the highest possible value, you will always have a stereo output.
+* Negation is the first thing to happen. If the *Neg* Checkbox is activated, the
+amplitude is multiplied by -1.
+* Panning is applied. Note, however, that you have to activate the
+Stereo Checkbox, labeled *St*, before.
+* Pre amplification is done next. The amount can be changed using the
+*Drive* nob. Indeed, this is the amount of distortion. For example, if you clip
+a signal, the louder the input gets, the more distortion you will get. This can
+have different meanings for different types of distortion, as described below.
+* Before applying the waveshape, or afterwards, you can apply Highpass
+and Lowpass filters. The type is HPF2 or LPF2, meaning butterworth lowpasses.
+They are labeled *HPF* and *LPF*. Whether this is done before, or after the
+waveshape, depends on the checkbox labeled *PF*.
+* The next step is the wave shape. This defines how the wave is
+actuallymodified. The *Type* ComboBox lets you define how. We will discuss some
+types below.
+* After the wave shape, we scale the level again. This is called
+output amplification. You can change the value using the *Level* knob.
+* Crossover is the last step. This is controlled by the knob *LR Mix* and
+means that afterwards, a percentage of the left side is applied to the right
+side, and, synchronously, the other way round. It is a kind of interpolation
+between left and right. If you set the LR Mix to 0.0, you will always have a
+stereo output.
********************************************************************
-One practical reason for using filters afterwards is that distortion can lead to waves with undesired high frequency parts. Those can be filtered out using the HPF.
-A reason for using filters before applying is to achieve multiband distortion. ZynAddSubFx has no "real" multiband distortion by now, however.
+One practical reason for using filters afterwards is that distortion can lead to
+waves with undesired high frequency parts. Those can be filtered out using the
+HPF.
+A reason for using filters before applying is to achieve multiband
+distortion. ZynAddSubFX has no "real" multiband distortion by now, however.
********************************************************************
-For a few types of distortion we will make a description below. Please note that you can get a very good impression for this using the *Wsh* ComboBox in the Oscillator editor.
+For a few types of distortion we will make a description below. Please note that
+you can get a very good impression for this using the *Wsh* ComboBox in the
+Oscillator editor.
Atan & Sigmoid
^^^^^^^^^^^^^^
-This is the default setting. It is an easy way to apply loudness to a wave without getting undesired effects. Thus, it can be used both for making instruments that sound like "real" ones, but also for electronic music. The transformation turns, roughly said, every amplitude into a square amplitude. Thus, sine, power, pulse and triangle turn into a usual square wave, while a saw turns into a phased square wave. A chirp wave turns into a kind of phase modulated square wave.
+This is the default setting. It is an easy way to apply loudness to a
+wave without getting undesired effects. Thus, it can be used both for making
+instruments that sound like "real" ones, but also for electronic music. The
+transformation turns, roughly said, every amplitude into a square amplitude.
+Thus, sine, power, pulse and triangle turn into a usual square wave, while a saw
+turns into a phased square wave. A chirp wave turns into a kind of phase
+modulated square wave.
Quants
^^^^^^
-Quantization can be seen as an unnatural effect, which is often used for electronic music. The transformation is similar to building the http://en.wikipedia.org/wiki/Riemann_sum[lower sum] of a wave, mathematically said. This means that the transformation effect turns your "endless high" sampled wave into only a few samples. For more information, read http://en.wikipedia.org/wiki/Quantization_%28sound_processing%29[Wikipedia's article].
+Quantization can be seen as an unnatural effect, which is often used
+for electronic music. The transformation is a bit similar to building the
+http://en.wikipedia.org/wiki/Riemann_sum[lower sum] of a wave, mathematically
+said. This means that the transformation effect turns your "endless high"
+sampled wave into only a few samples. For more information, read
+http://en.wikipedia.org/wiki/Quantization_%28sound_processing%29[Wikipedia's
+article].
-The more distortion you will apply, the less samples will be used. Indeed, this is equivalent to say that more input amplification is used. To see this, here is a small sample of code, where "ws" is the (correctly scaled amount of input amplification, and "n" the number of original samples.
+The more distortion you will apply, the less samples will be used. Indeed,
+this is equivalent to say that more input amplification is used. To see this,
+here is a small sample of code, where "ws" is the (correctly scaled amount of
+input amplification, and "n" the number of original samples.
---------------------------------
for(i = 0; i < n; ++i)
@@ -123,18 +277,36 @@ for(i = 0; i < n; ++i)
---------------------------------
********************************************************************
-This kind of distortion might remind you of gaming console sound. Let's say we have a computer which is not able to play sounds with many samples. Therefore, it can only play sounds with a low sample rate. This leads to exactly this effect.
+This kind of distortion might remind you of gaming console sound. Let's say
+we have a computer which is not able to play sounds with many samples.
+Therefore, it can only play sounds with a low sample rate. This leads to exactly
+this effect.
********************************************************************
-NOTE: If you turn on quantisation very high, you might be confused that, especially high notes, make no sound. The reason is simple: High frequencies are "forgotten" if you sample with only few samples. Also, the sign of an amplitude can be forgotten. This behaviour might make some quantisations a bit unexpected.
+NOTE: If you turn on quantisation very high, you might be confused
+that, especially high notes, make no sound. The reason is simple: High
+frequencies are "forgotten" if you sample with only few samples. Also, the sign
+of an amplitude can be forgotten. This behaviour might make some quantisations a
+bit unexpected.
Limiting & Clipping
^^^^^^^^^^^^^^^^^^^
-Limiting usually means that for a signal, the amplitude is modified because it exceeds its maximum value. Overdrive, as often used for guitars, is often achieved by limiting: It happens because an amplifier "overdrives" the maximum amplitude it can deliver. For more general information, you can try http://en.wikipedia.org/wiki/Limiting[Wikipedia].
-
-ZynAddSubFx has two types of limiting. Soft limiting, here as *Lmt*, means that the sound may not exceed a certain value. If the amplitude does so, it will simply be reduced to the limiting value. Hard limiting, is also called clipping and abbreviated *Clip*. This means that if the maximum is exceeded, instead of being constant at the limiting value, the original signal still has some influence on the output signal. Still, it does not exceed the limiting value. For ZynAddSubFx, a signal exeeding the limiting value will continue to grow "in the negative".
+Limiting usually means that for a signal, the amplitude is modified because
+it exceeds its maximum value. Overdrive, as often used for guitars, is often
+achieved by limiting: It happens because an amplifier "overdrives" the maximum
+amplitude it can deliver. For more general information, you can try
+http://en.wikipedia.org/wiki/Limiting[Wikipedia].
+
+ZynAddSubFX has two types of limiting. Soft limiting, here as *Lmt*, means
+that the sound may not exceed a certain value. If the amplitude does so, it will
+simply be reduced to the limiting value. Hard limiting, is also called clipping
+and abbreviated *Clip*. This means that if the maximum is exceeded, instead of
+being constant at the limiting value, the original signal still has some
+influence on the output signal. Still, it does not exceed the limiting value.
+For ZynAddSubFX, a signal exceeding the limiting value will continue to grow "in
+the negative".
Dynamic Filter
~~~~~~~~~~~~~
