improve effects doc

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)
    *
    */
   [

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} />

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} />