categorize effects + add envelope doc

+ use short, more logical filter params as default

packages/core/controls.mjs

@@ -83,8 +83,7 @@ const generic_params = [
    */
   ['f', 'amp', 'like @gain@, but linear.'],
   /**
-   * A pattern of numbers to specify the attack time of an envelope applied to each sample.
+   * Amplitude envelope attack time: Specifies how long it takes for the sound to reach its peak value, relative to the onset.
-   * [More info about envelopes](/learn/synths-samples-effects/#envelope)
    *
    * @name attack
    * @param {number | Pattern} attack time in seconds.
@@ -92,11 +91,7 @@ const generic_params = [
    * note("c3 e3").attack("<0 .1 .5>")
    *
    */
-  [
+  ['f', 'attack'],
-    'f',
-    'attack',
-    'a pattern of numbers to specify the attack time (in seconds) of an envelope applied to each sample.',
-  ],
 
   /**
    * Select the sound bank to use. To be used together with `s`. The bank name (+ "_") will be prepended to the value of `s`.
@@ -110,8 +105,8 @@ const generic_params = [
   ['f', 'bank', 'selects sound bank to use'],
 
   /**
-   * Gain envelope decay time = the time it takes after the attack time to reach the sustain level.
+   * Amplitude envelope decay time: the time it takes after the attack time to reach the sustain level.
-   * [More info about envelopes](/learn/synths-samples-effects/#envelope)
+   * Note that the decay is only audible if the sustain value is lower than 1.
    *
    * @name decay
    * @param {number | Pattern} time decay time in seconds
@@ -121,7 +116,7 @@ const generic_params = [
    */
   ['f', 'decay', ''],
   /**
-   * Gain envelope sustain level. [More info about envelopes](/learn/synths-samples-effects/#envelope)
+   * Amplitude envelope sustain level: The level which is reached after attack / decay, being sustained until the offset.
    *
    * @name sustain
    * @param {number | Pattern} gain sustain level between 0 and 1
@@ -131,7 +126,7 @@ const generic_params = [
    */
   ['f', 'sustain', ''],
   /**
-   * Gain envelope release time. [More info about envelopes](/learn/synths-samples-effects/#envelope)
+   * Amplitude envelope release time: The time it takes after the offset to go from sustain level to zero.
    *
    * @name release
    * @param {number | Pattern} time release time in seconds
@@ -151,30 +146,30 @@ const generic_params = [
   ],
   // TODO: in tidal, it seems to be normalized
   /**
-   * Sets the center frequency of the band-pass filter.
+   * Sets the center frequency of the **b**and-**p**ass **f**ilter.
    *
-   * @name bandf
+   * @name bpf
    * @param {number | Pattern} frequency center frequency
-   * @synonyms bpf
+   * @synonyms bandf
    * @example
-   * s("bd sd,hh*3").bandf("<1000 2000 4000 8000>")
+   * s("bd sd,hh*3").bpf("<1000 2000 4000 8000>")
    *
    */
-  ['f', 'bandf', 'A pattern of numbers from 0 to 1. Sets the center frequency of the band-pass filter.'],
   ['f', 'bpf', ''],
+  ['f', 'bandf', 'A pattern of numbers from 0 to 1. Sets the center frequency of the band-pass filter.'],
   // TODO: in tidal, it seems to be normalized
   /**
-   * Sets the q-factor of the band-pass filter
+   * Sets the **b**and-**p**ass **q**-factor (resonance)
    *
-   * @name bandq
+   * @name bpq
    * @param {number | Pattern} q q factor
-   * @synonyms bpq
+   * @synonyms bandq
    * @example
-   * s("bd sd").bandf(500).bandq("<0 1 2 3>")
+   * s("bd sd").bpf(500).bpq("<0 1 2 3>")
    *
    */
-  ['f', 'bandq', 'a pattern of anumbers from 0 to 1. Sets the q-factor of the band-pass filter.'],
   ['f', 'bpq', ''],
+  ['f', 'bandq', 'a pattern of anumbers from 0 to 1. Sets the q-factor of the band-pass filter.'],
   /**
    * a pattern of numbers from 0 to 1. Skips the beginning of each sample, e.g. `0.25` to cut off the first quarter from each sample.
    *
@@ -284,46 +279,46 @@ const generic_params = [
   /**
    * Applies the cutoff frequency of the low-pass filter.
    *
-   * @name cutoff
+   * @name lpf
    * @param {number | Pattern} frequency audible between 0 and 20000
-   * @synonyms lpf
+   * @synonyms cutoff
    * @example
    * s("bd sd,hh*3").cutoff("<4000 2000 1000 500 200 100>")
    *
    */
-  ['f', 'cutoff', 'a pattern of numbers from 0 to 1. Applies the cutoff frequency of the low-pass filter.'],
   ['f', 'lpf'],
+  ['f', 'cutoff', 'a pattern of numbers from 0 to 1. Applies the cutoff frequency of the low-pass filter.'],
   /**
    * Applies the cutoff frequency of the high-pass filter.
    *
-   * @name hcutoff
+   * @name hpf
    * @param {number | Pattern} frequency audible between 0 and 20000
-   * @synonyms hpf
+   * @synonyms hcutoff
    * @example
    * s("bd sd,hh*4").hcutoff("<4000 2000 1000 500 200 100>")
    *
    */
-  ['f', 'hcutoff', ''],
   ['f', 'hpf', ''],
+  ['f', 'hcutoff', ''],
   /**
    * Applies the resonance of the high-pass filter.
    *
-   * @name hresonance
+   * @name hpq
    * @param {number | Pattern} q resonance factor between 0 and 50
-   * @synonyms hpq
+   * @synonyms hresonance
    * @example
    * s("bd sd,hh*4").hcutoff(2000).hresonance("<0 10 20 30>")
    *
    */
-  ['f', 'hpq', ''],
   ['f', 'hresonance', ''],
+  ['f', 'hpq', ''],
   // TODO: add hpq synonym
   /**
    * Applies the cutoff frequency of the low-pass filter.
    *
-   * @name resonance
+   * @name lpq
    * @param {number | Pattern} q resonance factor between 0 and 50
-   * @synonyms lpq
+   * @synonyms resonance
    * @example
    * s("bd sd,hh*4").cutoff(2000).resonance("<0 10 20 30>")
    *

website/src/pages/learn/effects.mdx

@@ -12,13 +12,96 @@ import { JsDoc } from '../../docs/JsDoc';
 Wether you're using a synth or a sample, you can apply any of the following built-in audio effects.
 As you might suspect, the effects can be chained together, and they accept a pattern string as their argument.
 
-## bandf
+# Filters
 
-<JsDoc client:idle name="bandf" h={0} />
+Filters are an essential building block of [subtractive synthesis](https://en.wikipedia.org/wiki/Subtractive_synthesis).
+Strudel comes with 3 types of filters:
 
-## bandq
+- low-pass filter: low frequencies may _pass_, high frequencies are cut off
+- high-pass filter: high frequencies may _pass_, low frequencies are cut off
+- band-pass filters: only a frequency band may _pass_, low and high frequencies around are cut off
 
-<JsDoc client:idle name="bandq" h={0} />
+Each filter has 2 parameters:
+
+- cutoff: the frequency at which the filter starts to work. e.g. a low-pass filter with a cutoff of 1000Hz allows frequencies below 1000Hz to pass.
+- q-value: Controls the resonance of the filter. Higher values sound more aggressive. Also see [Q-Factor](https://en.wikipedia.org/wiki/Q_factor)
+
+## lpf
+
+<JsDoc client:idle name="lpf" h={0} />
+
+## lpq
+
+<JsDoc client:idle name="lpq" h={0} />
+
+## hpf
+
+<JsDoc client:idle name="hpf" h={0} />
+
+## hpq
+
+<JsDoc client:idle name="hpq" h={0} />
+
+## bpf
+
+<JsDoc client:idle name="bpf" h={0} />
+
+## bpq
+
+<JsDoc client:idle name="bpq" h={0} />
+
+## vowel
+
+<JsDoc client:idle name="vowel" h={0} />
+
+# Amplitude Envelope
+
+The amplitude [envelope](<https://en.wikipedia.org/wiki/Envelope_(music)>) controls the dynamic contour of a sound.
+Strudel uses ADSR envelopes, which are probably the most common way to describe an envelope:
+
+![ADSR](https://upload.wikimedia.org/wikipedia/commons/thumb/e/ea/ADSR_parameter.svg/1920px-ADSR_parameter.svg.png)
+
+## attack
+
+<JsDoc client:idle name="attack" h={0} />
+
+## decay
+
+<JsDoc client:idle name="decay" h={0} />
+
+## sustain
+
+<JsDoc client:idle name="sustain" h={0} />
+
+## release
+
+<JsDoc client:idle name="release" h={0} />
+
+# Dynamics
+
+## gain
+
+<JsDoc client:idle name="gain" h={0} />
+
+## velocity
+
+<JsDoc client:idle name="velocity" h={0} />
+
+# Panning
+
+## jux
+
+<JsDoc client:idle name="jux" h={0} />
+
+## juxBy
+
+<JsDoc client:idle name="juxBy" h={0} />
+
+## pan
+
+<JsDoc client:idle name="pan" h={0} />
+
+# Waveshaping
 
 ## coarse
 
@@ -28,50 +111,10 @@ As you might suspect, the effects can be chained together, and they accept a pat
 
 <JsDoc client:idle name="crush" h={0} />
 
-## cutoff
-
-<JsDoc client:idle name="cutoff" h={0} />
-
-## gain
-
-<JsDoc client:idle name="gain" h={0} />
-
-## hcutoff
-
-<JsDoc client:idle name="hcutoff" h={0} />
-
-## hresonance
-
-<JsDoc client:idle name="hresonance" h={0} />
-
-## pan
-
-<JsDoc client:idle name="pan" h={0} />
-
-## resonance
-
-<JsDoc client:idle name="resonance" h={0} />
-
 ## shape
 
 <JsDoc client:idle name="shape" h={0} />
 
-## velocity
-
-<JsDoc client:idle name="velocity" h={0} />
-
-## vowel
-
-<JsDoc client:idle name="vowel" h={0} />
-
-## jux
-
-<JsDoc client:idle name="jux" h={0} />
-
-## juxBy
-
-<JsDoc client:idle name="juxBy" h={0} />
-
 # Global Effects
 
 ## Local vs Global Effects