commit b1d12c22154b517a1c347c385b2e5c2fd8d8c195
parent c82807df1d1650cad617d9149d34bd2fc97e89d6
Author: Johannes Lorenz <johannes89@mailueberfall.de>
Date: Sat, 10 Aug 2013 18:03:46 +0200
Docs: Cleaned up a lot of the Effect docs. Finished partly: AlienWah and Phaser.
Diffstat:
4 files changed, 247 insertions(+), 161 deletions(-)
diff --git a/doc/Makefile b/doc/Makefile
@@ -4,11 +4,12 @@
all: gen-files man xhtml chunked pdf
gen-files:
- cd gen; make
+# cd gen; make
xhtml: zynaddsubfx.txt envelope.txt intro.txt lfo.txt
asciidoc -a numbered -a toc -b html5 \
+ -a latexmath \
zynaddsubfx.txt
chunked:
diff --git a/doc/adsynth.txt b/doc/adsynth.txt
@@ -74,7 +74,75 @@ oscillators
Oscillator
~~~~~~~~~~
-NOTE: TODO show waveforms, talk about distortions somewhere, etc
+The oscillator is lets you choose the basic waveform, which oscillates while
+the sound is playing and is then further modified.
.Oscillator Window
image::images/uioscil.png[]
+
+[[adsynth::oscilllator::types_of_waveshaping, Types of Waveshaping]]
+Types of Waveshaping
+^^^^^^^^^^^^^^^^^^^^
+
+Waveshaping can be done using the *Wsh* area in the Oscillator editor.
+
+The type of distortion has much influence on how the overtones are being placed.
+Sometimes, you get a "fat" bass, and sometimes, high frequencies are added,
+makeing the sound "crystal clear".
+
+Atan & Sigmoid
+++++++++++++++
+
+This is the default setting. It is an easy way to apply loudness to a
+wave without getting undesired high overtones. 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
+++++++
+
+http://en.wikipedia.org/wiki/Quantization_%28sound_processing%29[Quantization]
+adds high overtones early. It 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. 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)
+ smps[i] = floor(smps[i] / ws + 0.5f) * ws;
+---------------------------------
+
+NOTE: If you turn on quantisation very high, you might be confused
+that, especially high notes, make no sound. The reason: 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
++++++++++++++++++++
+
+http://en.wikipedia.org/wiki/Limiting[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.
+
+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. The overtones are generated in the
+lower frequencies first.
+
+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". This leads to overtones being
+generated on the full frequency band.
+\ No newline at end of file
diff --git a/doc/effects.txt b/doc/effects.txt
@@ -21,21 +21,40 @@ ZynAddSubFX has 3 types of effects:
* Insertion Effects
* Instrument Effects
-TODO: Describe these 3 types.
+TODO: Describe these 3 types (their differences).
+[[effects::general_topics, General Topics]]
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.
+effect. TODO: Difference between Volume and D/W?
+* *Pan* lets you apply panning, which means that the sound source can move to
+the right or left. Set it to 0.0 to only hear output on the right side, or to
+the maximum value to only hear output on the left side.
+* *LRc.* or *L/R* let you apply crossover.
* *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?
+* *LFOs* are, as the name says, oscillators with, compared to the frequency of
+the sound, low frequency. They often appear in order to control the effect.
+They can have some of the following controls:
+** *LFO Type* determines the shape of the LFO. If not present, the LFO is a
+sine wave.
+** *Freq* determines the LFO's frequency.
+** *Dpth* is a multiplier to the LFO. Thus, it determines the LFOs amplitude
+and its influence.
+** *Rnd* is the LFO amplitude's randomness
+** *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.
+********************************************************************
+Hint: Keep in mind that Effects that can be controlled by LFO can also be
+controlled arbitrary: Set the LFO depth to zero and manipulate the phase knob.
+********************************************************************
Equalizer
~~~~~~~~~
@@ -45,72 +64,25 @@ Introduction
An http://en.wikipedia.org/wiki/Filter_%28signal_processing%29[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.
-Note that ZynAddSubFX's implementations follow the
+input signal. This can, for example, be used to "filter out" unwanted
+frequencies.
+ZynAddSubFX's implementations follow the
http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt["Cookbook formulae for
audio EQ"] by Robert Bristow-Johnson.
Filter Types
^^^^^^^^^^^^
-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 that correspond to 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).
-********************************************************************
-
-The term passband (or often just "band") refers to the amount of frequencies
-which are not significantly 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 of a frequency
-band 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.
+This topic is completely discussed in <<filters, the Filters section>>.
Usage
^^^^^
-We describe all parts of the GUI here.
+We describe all parts of the GUI here. The term passband (or often just "band")
+refers to the amount of frequencies which are not significantly attenuated by
+the filter.
-* 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.
+* *Gain* (on the left) defines an offset which is added to the complete filter.
* *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.
@@ -166,17 +138,10 @@ them more "character".
Usage
^^^^^
-* First, crossover is applied. The *L/R* 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* is the LFO amplitude's randomness
-** *LFO Type* determines the shape of the 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.
-* *Dpth* determines how much influence the LFO has on the delay. If the depth
-is set to zero, the pitch will not be changed at all.
+* First, crossover is applied.
+* The following 5 knobs (*Freq*, *Rnd*, *LFO Type*, *St.df*, *Depth*) control
+the LFO for the pitch. If the depth is set to zero, the pitch will not be
+changed at all.
* *Delay* is the time that the delayed sound is delayed "on average". Note that
the delay also depends on the current pitch.
* After the correct element of the sound buffer is found using the LFO, the
@@ -184,8 +149,7 @@ the delay also depends on the current pitch.
the *D/W* knob, but we have not applied panning and substraction yet.
* Next, the singal can be negated. If the *Substract* Checkbox is activated,
the amplitude is multiplied by -1.
-* Finally, *Pan* lets you apply panning. Set it to 0.0 to only hear
-output on the right side.
+* Finally, *Pan* lets you apply panning.
Distortion
~~~~~~~~~~
@@ -195,10 +159,10 @@ 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. This is an important topic in the
+distortion is used. The most distorted waves are usually 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. This 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
@@ -234,69 +198,13 @@ however.
Types of Distortion
^^^^^^^^^^^^^^^^^^^
-The type of distortion has much influence on how the overtones are being placed.
-Sometimes, you get a "fat" bass, and sometimes, high frequencies are added,
-makeing the sound "crystal clear". 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 high overtones. 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
-++++++
-
-http://en.wikipedia.org/wiki/Quantization_%28sound_processing%29[Quantization]
-adds high overtones early. It 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. 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)
- smps[i] = floor(smps[i] / ws + 0.5f) * ws;
----------------------------------
-
-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
-+++++++++++++++++++
-
-http://en.wikipedia.org/wiki/Limiting[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.
-
-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. The overtones are generated in the
-lower frequencies first.
-
-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". This leads to overtones being
-generated on the full frequency band.
+This topic is completely discussed in
+<<adsynth::oscilllator::types_of_waveshaping, the Oscillator Section>>. Note
+that you can use the
+Oscillator editor in order to find out what your distortion effect does. Also
+note that while the Oscillator editor's distortion is limited to some
+oscillators you can produce in the Oscillator editor, the distortion effect can
+be used on every wave that you can generate with ZynAddSubFX.
Function
^^^^^^^^
@@ -351,7 +259,7 @@ give the filter its basic settings.
The filter basically works like this. The input signal is passed through a
filter which dynamically changes its frequency. The frequency is an additive of:
-* the filter's bass frequency
+* the filter's base frequency
* an LFO from the effect parameters
* the "amplitude" of the input wave
@@ -373,16 +281,10 @@ this into account, depending on the smoothness.
Usage
^^^^^
-* The following 4 knobs control the LFO.
-** *Freq* determines the LFO's frequency
-** *Rnd* is the LFO amplitude's randomness
-** *LFO Type* determines the shape of the 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.
+* The following 4 knobs (*Freq*, *Rnd*, *LFO Type*, *St.df*) control the LFO.
* These knobs let you control the way how the RMS value of the amplitudes is
measured.
-** *A.M* sets the Amplitude Smoothness.
+** *A.M* sets the Amplitude Smoothness (this is described below).
** *A.Inv.*, if being set, negates the (absolute) RMS value. This will lower
the filter frequency instead of increasing it.
* The following controls defined the Mix of the LFO and the amplitude.
@@ -390,7 +292,7 @@ the filter frequency instead of increasing it.
** *LfoD* sets the LFO depth
* The filter button lets you choose the filter type.
* After the input signal has passed through the filter, *Pan* can apply
-panning. Set it to 0.0 to only hear output on the right side.
+panning.
Echo
~~~~
@@ -404,6 +306,9 @@ the natural reflection of a sound. The listener can hear the sound multiple
times, usually decreasing in volume. Echos can be useful to fill empty parts of
your songs with.
+Function
+^^^^^^^^
+
In ZynAddSubFX, the echo is basically implemented as the addition of the
current sound and a delayed version of it. The delay is implemented as in the
picture below. First, to the effect input, we add the delayed signal. Then,
@@ -437,15 +342,13 @@ infinite looping for d=1 is impossible.
Description
^^^^^^^^^^^
-* *Pan* lets you apply panning of the input. Set it to 0.0 to only pan
-the input to the right side.
+* *Pan* lets you apply panning of the input.
* *Delay* sets the time for one delay.
* *LRdl.* means Left-Right-Delay. If it is set to the middle, then both sides
are delayed equally. If not, then the left echo comes earlier and the right
echo comes (the same amount) later than the average echo; or the other way
round. Set the knob to 0 to hear on the right first.
-* *LRc.* applies crossover. Set it to 1.0 to completely switch left and right
-input, to 0.5 to mix both as stereo, or to 0.0 to have no crossing effect.
+* *LRc.* applies crossover.
* Feedback describes how much of the delay is added back to the input. Set
*Fb.* to the maximum to hear an infinite echo.
* The *Damp* value lets the LP1 reject higher frequencies earlier if
@@ -468,7 +371,10 @@ used to emulate sounds like in live concerts. This is useful for voices, pads,
and hand claps. A small room size can simulate the sound board of string
instruments, like guitars or pianos.
-As mentioned, a reverb consists of permanent echo. The reverb in ZynAddSubFx is
+Function
+^^^^^^^^
+
+As mentioned, a reverb consists of permanent echo. The reverb in ZynAddSubFX is
more complex than the echo. After the delaying, comb filters and then allpass
filters are being applied. These make the resulting sound more realistic. The
parameters for these filters depend on the roomsize. For details, consider the
@@ -496,18 +402,28 @@ delayed sound is added to the input.
the comb filters.
* The dampening control (*Damp*) currently only allows to damp low frequencies.
Its parameters are being used by the comb and allpass filters.
-* *Pan* lets you apply panning. This is the last thing to happen. Set it to 0.0
-to only hear output on the right side.
+* *Pan* lets you apply panning. This is the last thing to happen.
Phaser
~~~~~~
-The Phaser is a special dynamic filter. The result is a sweeping sound, which is
+Introduction
+^^^^^^^^^^^^
+
+The http://en.wikipedia.org/wiki/Phaser_%28effect%29[Phaser] is a special
+dynamic filter. The result is a sweeping
+sound, which is
often used on instruments with a large frequency band, like guitars or strings.
This makes it typical for genres like rock or funk, where it is often modulated
-with a pedal, or for giving strings a warm, relaxing character. In ZynAddSubFX,
-the phaser can currently only be modulated with an LFO.
+with a pedal, or for giving strings a warm, relaxing character.
+
+In ZynAddSubFX, the phaser can currently be modulated with an LFO. However, you
+can also turn the LFO depth to zero and instead control the phase. This can be
+done with the phase knob, or MIDI's NRPNs.
+
+Function
+^^^^^^^^
The audio signal is split into two paths. One path remains unchanged. The other
one is sent to a delay line. The delay time (the so called *phase*) is made
@@ -526,3 +442,83 @@ This random effect results in white noise between the clear blue structures.
image::./images/phaser-spectrogram.jpg[width="700", title="Spectrogram of an
8-stage phaser modulated by a sine LFO applied to white noise."]
+
+Phaser Types
+^^^^^^^^^^^^
+
+ZynAddSubFX offers different types of phasers:
+* Analog and "normal" phasers. Analog phasers are more complicated. They sound
+punchier, while normal phasers sound more fluently. However, analog filters
+usually need more filter stages to reach a characteristic sound.
+* Sine and triangle filters. Note that an analog triangle filter with many poles
+is a barber pole filter and can be used to generate
+http://en.wikipedia.org/wiki/Shepard_tone[Shepard Tones],
+i.e. tones that seem to increase or decrease with time, but do not really.
+* The LFO function can be squared. This converts the triangle wave into a hyper
+sine wave. The sine squared is simply a faster sine wave.
+* TODO: Barber is deactivated, since PLFOtype is only 0 or 1?
+
+Description
+^^^^^^^^^^^
+
+For the normal phaser, first, the LFO is generated:
+* There are 4 controls (*Freq*,*Rnd*,*LFO tpye*,*St.df*) that define the
+LFO.
+* *Phase* and *Depth* are applied afterwards in the usual way (TODO: I don't
+understand the code here for the normal phase...). For the analog phaser,
+*Phase* is not implemented, yet.
+** If *hyp* is being set, then the LFO function is being squared.
+Next, the input is being used.
+* *Analog* decides whether the phaser is analog or "normal".
+* First, *Pan* applies panning to the original input in every loop (TODO: ask
+to optimize this).
+* Next, barber pole phasing is being applied (Analog only)
+* *Fb* applies feedback. The last sound buffer element is (after
+phasing) multiplied by this value and then added to the current one. For normal
+filter, the value is added before, for analog after the first phasing stage.
+* Now, *Stages* phasing stages are being applied. *dist* sets the distortion
+for when applying the phasing stages. This has only effect for analog phasers.
+* The feedback is taken now.
+* In the end, *Substract* inverts the signal, multiplying it by -1.
+
+Alienwah
+~~~~~~~~
+
+Introduction
+^^^^^^^^^^^^
+
+The AlienWah effect is a special, dynamic
+http://en.wikipedia.org/wiki/Formant[formant] filter (TODO: is this true?).
+Paul Nasca named it AlienWah because it sounded "a bit like wahwah, but more
+strange". The result of the filter is a sound varying between the
+vocals "Ahhhhh" (or "Uhhhhh") and "Eeeeee".
+
+Function
+^^^^^^^^
+
+The way that the filter moves between the two vocals is mainly
+described by an LFO. A bit easified, Paul Nasca has stated the formula (for
+latexmath:[$i^2=-1; R<1$]) as
+
+latexmath:[$fb=R*(\cos(\alpha)+i*\sin(\alpha))$]
+
+latexmath:[$y_n=y_{n-delay}*R*(\cos(\alpha)+i*\sin(\alpha))+x_n*(1-R)$].
+
+The input latexmath:[$x_n$] has the real part of the samples from the wavefile
+and the imaginary part is zero. The output of this effect is the real part of
+latexmath:[$y_n$]. latexmath:[$\alpha$] is the phase.
+
+Description
+^^^^^^^^^^^
+
+* *Pan*
+* The following 5 controls (*Freq*,*Rnd*,*LFO tpye*,*St.df*, *Dpth*) define the
+LFO.
+** *Fb*
+
+** *Delay* If this value is low, the sound is turned more into a
+"wah-wah"-effect.
+** *Phase* See latexmath:[$\alpha$] in the above formula. This lets you set
+where the vocal is between "Ahhhhh" and "Eeeeee".
+** *L/R* applies crossover in the end of every stage. This is currently not
+implemented for the Analog Phaser.
diff --git a/doc/filter.txt b/doc/filter.txt
@@ -1,3 +1,4 @@
+[[filters]]
Filters
-------
:Author: Mark McCurry
@@ -44,6 +45,25 @@ need several hundred filter stages to produce a given note.
image:images/filter2.png[]
+
+
+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 that correspond to 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).
+********************************************************************
+
User Interface
~~~~~~~~~~~~~~
