From ebb1bbc9668be587414b2eee84ce21b822a62bd9 Mon Sep 17 00:00:00 2001
From: Felix Roos <flix91@gmail.com>
Date: Fri, 6 Jan 2023 21:14:19 +0100
Subject: [PATCH] improve effects doc

---
 packages/core/controls.mjs          | 43 +++++++++++++++++-----
 website/src/pages/learn/effects.mdx | 57 ++++++++++++++++++++++-------
 website/src/pages/learn/samples.mdx |  8 +++-
 3 files changed, 84 insertions(+), 24 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 22e30f33..8682f0e1 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -269,7 +269,7 @@ const generic_params = [
    * @name cut
    * @param {number | Pattern} group cut group number
    * @example
-   * s("bd sax").cut(1).osc()
+   * s("rd*4").cut(1)
    *
    */
   [
@@ -341,17 +341,36 @@ const generic_params = [
   ['f', 'djf', 'DJ filter, below 0.5 is low pass filter, above is high pass filter.'],
   // ['f', 'cutoffegint', ''],
   // TODO: does not seem to work
-  /*
+  /**
    * Sets the level of the delay signal.
    *
    * @name delay
    * @param {number | Pattern} level between 0 and 1
    * @example
-   * s("bd").delay("<0 .5 .75 1>").osc()
+   * s("bd").delay("<0 .25 .5 1>")
    *
    */
   ['f', 'delay', 'a pattern of numbers from 0 to 1. Sets the level of the delay signal.'],
+  /**
+   * Sets the level of the signal that is fed back into the delay.
+   * Caution: Values >= 1 will result in a signal that gets louder and louder! Don't do it
+   *
+   * @name delayfeedback
+   * @param {number | Pattern} feedback between 0 and 1
+   * @example
+   * s("bd").delay(.25).delayfeedback("<.25 .5 .75 1>").slow(2)
+   *
+   */
   ['f', 'delayfeedback', 'a pattern of numbers from 0 to 1. Sets the amount of delay feedback.'],
+  /**
+   * Sets the time of the delay effect.
+   *
+   * @name delaytime
+   * @param {number | Pattern} seconds between 0 and Infinity
+   * @example
+   * s("bd").delay(.25).delaytime("<.125 .25 .5 1>").slow(2)
+   *
+   */
   ['f', 'delaytime', 'a pattern of numbers from 0 to 1. Sets the length of the delay.'],
   /* // TODO: test
    * Specifies whether delaytime is calculated relative to cps.
@@ -504,11 +523,15 @@ const generic_params = [
   // ['f', 'ophatdecay', ''],
   // TODO: example
   /**
-   * a pattern of numbers. An `orbit` is a global parameter context for patterns. Patterns with the same orbit will share hardware output bus offset and global effects, e.g. reverb and delay. The maximum number of orbits is specified in the superdirt startup, numbers higher than maximum will wrap around.
+   * An `orbit` is a global parameter context for patterns. Patterns with the same orbit will share the same global effects.
    *
    * @name orbit
    * @param {number | Pattern} number
-   *
+   * @example
+   * stack(
+   *   s("hh*3").delay(.5).delaytime(.25).orbit(1),
+   *   s("~ sd").delay(.5).delaytime(.125).orbit(2)
+   * )
    */
   [
     'i',
@@ -590,7 +613,7 @@ const generic_params = [
    * @name room
    * @param {number | Pattern} level between 0 and 1
    * @example
-   * s("bd sd").room("<0 .2 .4 .6 .8 1>").osc()
+   * s("bd sd").room("<0 .2 .4 .6 .8 1>")
    *
    */
   ['f', 'room', 'a pattern of numbers from 0 to 1. Sets the level of reverb.'],
@@ -598,9 +621,9 @@ const generic_params = [
    * Sets the room size of the reverb, see {@link room}.
    *
    * @name size
-   * @param {number | Pattern} size between 0 and 1
+   * @param {number | Pattern} size between 0 and 10
    * @example
-   * s("bd sd").room(.8).size("<0 .2 .4 .6 .8 1>").osc()
+   * s("bd sd").room(.8).size("<0 1 2 4 8>")
    *
    */
   // TODO: find out why :
@@ -640,9 +663,9 @@ const generic_params = [
    * @name speed
    * @param {number | Pattern} speed -inf to inf, negative numbers play the sample backwards.
    * @example
-   * s("bd").speed("<1 2 4 1 -2 -4>").osc()
+   * s("bd").speed("<1 2 4 1 -2 -4>")
    * @example
-   * speed("1 1.5*2 [2 1.1]").s("sax").cut(1).osc()
+   * speed("1 1.5*2 [2 1.1]").s("piano").clip(1)
    *
    */
   [
diff --git a/website/src/pages/learn/effects.mdx b/website/src/pages/learn/effects.mdx
index a73e140a..5310a50a 100644
--- a/website/src/pages/learn/effects.mdx
+++ b/website/src/pages/learn/effects.mdx
@@ -12,54 +12,85 @@ 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
+## bandf
 
 <JsDoc client:idle name="bandf" h={0} />
 
-# bandq
+## bandq
 
 <JsDoc client:idle name="bandq" h={0} />
 
-# coarse
+## coarse
 
 <JsDoc client:idle name="coarse" h={0} />
 
-# crush
+## crush
 
 <JsDoc client:idle name="crush" h={0} />
 
-# cutoff
+## cutoff
 
 <JsDoc client:idle name="cutoff" h={0} />
 
-# gain
+## gain
 
 <JsDoc client:idle name="gain" h={0} />
 
-# hcutoff
+## hcutoff
 
 <JsDoc client:idle name="hcutoff" h={0} />
 
-# hresonance
+## hresonance
 
 <JsDoc client:idle name="hresonance" h={0} />
 
-# pan
+## pan
 
 <JsDoc client:idle name="pan" h={0} />
 
-# resonance
+## resonance
 
 <JsDoc client:idle name="resonance" h={0} />
 
-# shape
+## shape
 
 <JsDoc client:idle name="shape" h={0} />
 
-# velocity
+## velocity
 
 <JsDoc client:idle name="velocity" h={0} />
 
-# vowel
+## vowel
 
 <JsDoc client:idle name="vowel" h={0} />
+
+# Global Effects
+
+## Local vs Global Effects
+
+While the above listed "local" effects will always create a separate effects chain for each event,
+global effects use the same chain for all events of the same orbit:
+
+## orbit
+
+<JsDoc client:idle name="orbit" h={0} />
+
+## delay
+
+<JsDoc client:idle name="delay" h={0} />
+
+## delaytime
+
+<JsDoc client:idle name="delaytime" h={0} />
+
+## delayfeedback
+
+<JsDoc client:idle name="delayfeedback" h={0} />
+
+## room
+
+<JsDoc client:idle name="room" h={0} />
+
+## size / roomsize
+
+<JsDoc client:idle name="size" h={0} />
diff --git a/website/src/pages/learn/samples.mdx b/website/src/pages/learn/samples.mdx
index 7804ffe8..3b5b56ae 100644
--- a/website/src/pages/learn/samples.mdx
+++ b/website/src/pages/learn/samples.mdx
@@ -217,6 +217,10 @@ Almost everything in Tidal can be patterned using strings!
 
 <JsDoc client:idle name="Pattern.end" h={0} />
 
+### `cut`
+
+<JsDoc client:idle name="cut" h={0} />
+
 ### `loopAt`
 
 <JsDoc client:idle name="Pattern.loopAt" h={0} />
@@ -225,4 +229,6 @@ Almost everything in Tidal can be patterned using strings!
 
 <JsDoc client:idle name="Pattern.chop" h={0} />
 
-<br />
+### `speed`
+
+<JsDoc client:idle name="speed" h={0} />