Merge pull request 'document undocumented things' (#1996) from tyow/localstrudel:jsdocs into main

Reviewed-on: https://codeberg.org/uzu/strudel/pulls/1996
2026-10-11 18:51:34 -04:00 · 2026-10-11 13:26:54 +02:00
parent ee9138b514 5148066b01
commit e78cc85ad7
12 changed files with 1488 additions and 126 deletions
@@ -118,7 +118,7 @@ export const { s, sound } = registerControl(['s', 'n', 'gain'], 'sound');
 * @param {number | Pattern} position Position in the wavetable from 0 to 1
 * @synonyms wavetablePosition
 * @example
- * s("squelch").bank("wt_digital").seg(8).note("F1").wt("0 0.25 0.5 0.75 1")
+ * s("wt_digital").seg(8).note("F1").wt("0 0.25 0.5 0.75 1")
 */
 export const { wt, wavetablePosition } = registerControl('wt', 'wavetablePosition');

@@ -1988,11 +1988,10 @@ export const { spread } = registerControl('spread');
 * Set dryness of reverb. See `room` and `size` for more information about reverb.
 *
 * @name dry
- * @tags superdirt
+ * @tags superdirt, superdough
 * @param {number | Pattern} dry 0 = wet, 1 = dry
 * @example
 * n("[0,3,7](3,8)").s("superpiano").room(.7).dry("<0 .5 .75 1>").osc()
- * @superdirtOnly
 *
 */
 export const { dry } = registerControl('dry');
@@ -2226,7 +2225,7 @@ export const { orbit } = registerControl('orbit', 'o');
 *   otherPat.bmod(..) (to modulate another pattern with the bus)
 *
 * @name bus
- * @tags superdirt
+ * @tags superdough
 * @param {number | Pattern} number
 */
 export const { bus } = registerControl('bus');
@@ -2235,7 +2234,7 @@ export const { bus } = registerControl('bus');
 * Postgain multiplier prior to sending the signal to the audio bus.
 *
 * @name busgain
- * @tags superdirt
+ * @tags superdough
 * @synonyms bgain
 * @param {number | Pattern} number
 */
@@ -2377,7 +2376,7 @@ export const { mode } = registerControl(['mode', 'anchor']);
 *
 * @name room
 * @tags orbit, superdough
- * @param {number | Pattern} level between 0 and 1
+ * @param {number | Pattern} level
 * @example
 * s("bd sd [~ bd] sd").room("<0 .2 .4 .6 .8 1>")
 * @example
@@ -504,10 +504,25 @@ export class Pattern {

  /**
   * Returns a new pattern with the given function applied to the list of haps returned by every query.
+   *
+   * As an end user, you will most likely not need to use this; look at `withContext`, `withHapSpan`, etc. instead.
   * @tags internals
   * @param {Function} func
   * @returns Pattern
   * @noAutocomplete
+   * @example
+   * note("[a b, c d] a b c d").s("gm_piano").withHaps(x=>{
+   *   if (x.length > 1) {
+   *     x = x.map(hap => hap.withValue(val => {
+   *       return {
+   *         n: 1,
+   *         // select gm_piano:1 sample
+   *         ...val
+   *       }
+   *     }));
+   *   }
+   *   return x
+   * })
   */
  withHaps(func) {
    const result = new Pattern((state) => func(this.query(state), state));
@@ -517,10 +532,23 @@ export class Pattern {

  /**
   * As with `withHaps`, but applies the function to every hap, rather than every list of haps.
+   *
+   * As an end user, you will most likely not need to use this; look at `withContext`, `withHapSpan`, etc. instead.
   * @tags internals
   * @param {Function} func
   * @returns Pattern
   * @noAutocomplete
+   * @example
+   * note("c a f e").withHap(x=>{
+   *   if (x.value.note == 'c') {
+   *     x.value.s = 'gm_piano'
+   *   }
+   *   else {
+   *     x.value.s = 'gm_piano'
+   *     x.value.n = 2
+   *   }
+   *   return x
+   * })
   */
  withHap(func) {
    return this.withHaps((haps) => haps.map(func));
@@ -850,6 +878,26 @@ export class Pattern {
    return stack(this, ...pats);
  }

+  stackLeft(...pats) {
+    return stackLeft(this, ...pats);
+  }
+
+  stackRight(...pats) {
+    return stackRight(this, ...pats);
+  }
+
+  stackCenter(...pats) {
+    return stackCenter(this, ...pats);
+  }
+
+  stackCentre(...pats) {
+    return stackCentre(this, ...pats);
+  }
+
+  stackRepeat(...pats) {
+    return stackRepeat(this, ...pats);
+  }
+
  sequence(...pats) {
    return sequence(this, ...pats);
  }
@@ -1074,7 +1122,7 @@ const COMPOSERS = {
   * @param {Pattern} pat
   * @returns {Pattern}
   * @memberof Pattern
-   * @tags internal, combiners
+   * @tags internals, combiners
   * @example
   * // because input pattern has `s` set,
   * // it overrides the "sine" declared earlier
@@ -1099,7 +1147,7 @@ const COMPOSERS = {
   * @param {Pattern} pat
   * @memberof Pattern
   * @returns {Pattern}
-   * @tags internal, combiners
+   * @tags internals, combiners
   * @example
   * // notes, already defined, will stay "c a f e",
   * // while "s", not defined, will be set to "piano"
@@ -1156,24 +1204,163 @@ const COMPOSERS = {
   * @tags math
   */
  div: [numeralArgs((a, b) => a / b)],
+  /**
+   *
+   * Divides each number by the given factor and returns the remainder
+   * @name mod
+   * @memberof Pattern
+   * @tags math
+   */
  mod: [numeralArgs(_mod)],
+  /**
+   *
+   * Raises each number to the power of the given factor
+   * @name pow
+   * @memberof Pattern
+   * @tags math
+   */
  pow: [numeralArgs(Math.pow)],
+  /**
+   *
+   * Performs a bitwise `and` on each number and the given factor
+   * @name band
+   * @memberof Pattern
+   * @tags math
+   */
  band: [numeralArgs((a, b) => a & b)],
+  /**
+   *
+   * Performs a bitwise `or` on each number and the given factor
+   * @name bor
+   * @memberof Pattern
+   * @tags math
+   */
  bor: [numeralArgs((a, b) => a | b)],
+  /**
+   *
+   * Performs a bitwise `xor` on each number and the given factor
+   * @name bxor
+   * @memberof Pattern
+   * @tags math
+   */
  bxor: [numeralArgs((a, b) => a ^ b)],
+  /**
+   *
+   * Performs a bitwise `left shift` on each number by the given factor
+   * @name blshift
+   * @memberof Pattern
+   * @tags math
+   */
  blshift: [numeralArgs((a, b) => a << b)],
+  /**
+   *
+   * Performs a bitwise `right shift` on each number by the given factor
+   * @name brshift
+   * @memberof Pattern
+   * @tags math
+   */
  brshift: [numeralArgs((a, b) => a >> b)],

  // TODO - force numerical comparison if both look like numbers?
+  /**
+   * performs a < b
+   * @name lt
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  lt: [(a, b) => a < b],
+  /**
+   * performs a > b
+   * @name gt
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  gt: [(a, b) => a > b],
+  /**
+   * performs a <= b
+   * @name lte
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  lte: [(a, b) => a <= b],
+  /**
+   * performs a >= b
+   * @name gte
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  gte: [(a, b) => a >= b],
+  /**
+   * performs a == b
+   * @name eq
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  eq: [(a, b) => a == b],
+  /**
+   * performs a === b (strictly equal)
+   * @name eqt
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  eqt: [(a, b) => a === b],
+  /**
+   * performs a != b
+   * @name ne
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  ne: [(a, b) => a != b],
+  /**
+   * performs a !== b (strictly not equal)
+   * @name net
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  net: [(a, b) => a !== b],
+  /**
+   * performs a && b
+   * @name and
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  and: [(a, b) => a && b],
+  /**
+   * performs a || b
+   * @name or
+   * @memberof Pattern
+   * @tags math
+   * @param {any} a
+   * @param {any} b
+   * @returns Pattern with boolean value(s)
+   */
  or: [(a, b) => a || b],

  //  bitwise ops
@@ -1482,6 +1669,18 @@ function _stackWith(func, pats) {
  return stack(...func(steps, pats));
 }

+/**
+ * The input patterns are aligned to the left, with silence padded to the shorter pattern(s) in the final steps if there's a stepcount disparity. See also `stackRight` and `stackCenter/stackCentre`
+ *
+ * @name stackLeft
+ * @tags temporal, stepwise, combiners
+ * @return {Pattern}
+ * @example
+ * stackLeft("0 1 2 3", "3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ * @example
+ * // chainable
+ * "0 1 2 3".stackLeft("3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ */
 export function stackLeft(...pats) {
  return _stackWith(
    (steps, pats) => pats.map((pat) => (pat._steps.eq(steps) ? pat : stepcat(pat, gap(steps.sub(pat._steps))))),
@@ -1489,6 +1688,18 @@ export function stackLeft(...pats) {
  );
 }

+/**
+ * The input patterns are aligned to the right, with silence padded to the shorter pattern(s) in the initial steps if there's a stepcount disparity. See also `stackLeft` and `stackCenter/stackCentre`
+ *
+ * @name stackRight
+ * @tags temporal, stepwise, combiners
+ * @return {Pattern}
+ * @example
+ * stackRight("0 1 2 3", "3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ * @example
+ * // chainable
+ * "0 1 2 3".stackRight("3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ */
 export function stackRight(...pats) {
  return _stackWith(
    (steps, pats) => pats.map((pat) => (pat._steps.eq(steps) ? pat : stepcat(gap(steps.sub(pat._steps)), pat))),
@@ -1496,7 +1707,19 @@ export function stackRight(...pats) {
  );
 }

-export function stackCentre(...pats) {
+/**
+ * The input patterns are aligned to the right, with silence padded to the shorter pattern(s) in the initial steps if there's a stepcount disparity. See also `stackLeft` and `stackRight`
+ * @name stackCenter
+ * @tags temporal, stepwise, combiners
+ * @synonyms stackCentre
+ * @return {Pattern}
+ * @example
+ * stackCenter("0 1 2 3", "3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ * @example
+ * // chainable
+ * "0 1 2 3".stackCenter("3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ */
+export function stackCenter(...pats) {
  return _stackWith(
    (steps, pats) =>
      pats.map((pat) => {
@@ -1510,6 +1733,25 @@ export function stackCentre(...pats) {
  );
 }

+export function stackCentre(...pats) {
+  return stackCenter(...pats);
+}
+
+/**
+ * Shorthand for `pm(patterns).pace(m)` where m is the max step count in the input patterns
+ * @name stackRepeat
+ * @tags temporal, stepwise, combiners
+ * @return {Pattern}
+ * @example
+ * stackRepeat("0 1 2 3", "3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ * @example
+ * // chainable
+ * "0 1 2 3".stackRepeat("3 4", "[4 5 6] 7 8 9 10").scale("c:minor").note()
+ */
+export function stackRepeat(...pats) {
+  return stackBy(reify('repeat'), ...pats);
+}
+
 export function stackBy(by, ...pats) {
  const [left, ...right] = pats.map((pat) => pat._steps);
  const steps = left.maximum(...right);
@@ -1624,10 +1866,10 @@ export function arrange(...sections) {
 * @tags combiners
 * @return {Pattern}
 * @example
-seqPLoop(
-  [0, 2, "bd(3,8)"],
-  [1, 3, "cp(3,8)"]
-).sound()
+ * seqPLoop(
+ * [0, 2, "bd(3,8)"],
+ * [1, 3, "cp(3,8)"]
+ * ).sound()
 */
 export function seqPLoop(...parts) {
  let total = Fraction(0);
@@ -2304,11 +2546,11 @@ export const { zoomArc, zoomarc } = register(['zoomArc', 'zoomarc'], function (a
 * @param {number} slices to play
 * @example
 * note("0 1 2 3 4 5 6 7".scale('c:mixolydian'))
- *.bite(4, "3 2 1 0")
+ * .bite(4, "3 2 1 0")
 * @example
 * sound("bd - bd bd*2, - sd:6 - sd:5 sd:1 - [- sd:2] -, hh [- cp:7]")
-  .bank("RolandTR909").speed(1.2)
-  .bite(4, "0 0 [1 2] <3 2> 0 0 [2 1] 3")
+ * .bank("RolandTR909").speed(1.2)
+ * .bite(4, "0 0 [1 2] <3 2> 0 0 [2 1] 3")
 */
 export const bite = register(
  'bite',
@@ -2431,8 +2673,12 @@ export const off = register('off', function (time_pat, func, pat) {
 * Returns a new pattern where every other cycle is played once, twice as
 * fast, and offset in time by one quarter of a cycle. Creates a kind of
 * breakbeat feel.
+ * @name brak
 * @tags temporal
 * @returns Pattern
+ * @memberof Pattern
+ * @example
+ * s("bd hh!2 rim").brak()
 */
 export const brak = register('brak', function (pat) {
  return pat.when(slowcat(false, true), (x) => fastcat(x, silence)._late(0.25));
@@ -2921,10 +3167,29 @@ export const { ribbon, rib } = register(['ribbon', 'rib'], (offset, cycles, pat)
  pat.early(offset).restart(pure(1).slow(cycles)),
 );

+/**
+ * Sets the pattern's color to the given [hsla](https://www.w3schools.com/htmL/html_colors_hsl.asp)
+ *
+ * @name hsla
+ * @param {Number} hue (0 - 360)
+ * @param {Number} saturation percentage (0 - 100)
+ * @param {Number} lightness percentage (0 - 100)
+ * @param {Number} alpha (transparency) (0.0 - 1.0)
+ * @tags visualization
+ */
 export const hsla = register('hsla', (h, s, l, a, pat) => {
  return pat.color(`hsla(${h}turn,${s * 100}%,${l * 100}%,${a})`);
 });

+/**
+ * Sets the pattern's color to the given [hsl](https://www.w3schools.com/htmL/html_colors_hsl.asp)
+ *
+ * @name hsl
+ * @param {Number} hue (0 - 360)
+ * @param {Number} saturation percentage (0 - 100)
+ * @param {Number} lightness percentage (0 - 100)
+ * @tags visualization
+ */
 export const hsl = register('hsl', (h, s, l, pat) => {
  return pat.color(`hsl(${h}turn,${s * 100}%,${l * 100}%)`);
 });
@@ -3280,7 +3545,7 @@ export const drop = stepRegister('drop', function (i, pat) {
 * @tags stepwise
 * @example
 * stepcat(
- *   sound("bd bd - cp").extend(2),
+ *   sound("bd bd - <cp hh>").extend(2),
 *   sound("bd - sd -")
 * ).pace(8)
 */
@@ -3291,15 +3556,12 @@ export const extend = stepRegister('extend', function (factor, pat) {
 /**
 * *Experimental*
 *
- * `replicate` is similar to `fast` in that it increases its density, but it also increases the step count
- * accordingly. So `stepcat("a b".replicate(2), "c d")` would be the same as `"a b a b c d"`, whereas
- * `stepcat("a b".fast(2), "c d")` would be the same as `"[a b] [a b] c d"`.
+ * `replicate` is similar to `extend`, except that `replicate` will "replicate" the thing being extended. This will only differ from `extend` when the input pattern differs from cycle to cycle.
 *
- * TODO: find out how this function differs from extend
 * @tags stepwise
 * @example
 * stepcat(
- *   sound("bd bd - cp").replicate(2),
+ *   sound("bd bd - <cp hh>").replicate(2),
 *   sound("bd - sd -")
 * ).pace(8)
 */
@@ -3395,8 +3657,8 @@ export const growlist = (amount, pat) => pat.growlist(amount);
 * "tha dhi thom nam".shrink("1 -1").sound().bank("mridangam").pace(4)
 * @example
 * note("0 1 2 3 4 5 6 7".scale("C:ritusen")).sound("folkharp")
-   .shrink("1 -1").pace(8)
-
+ * .shrink("1 -1").pace(8)
+ *
 */

 export const shrink = register(
@@ -3435,7 +3697,7 @@ export const shrink = register(
 * "tha dhi thom nam".grow("1 -1").sound().bank("mridangam").pace(4)
 * @example
 * note("0 1 2 3 4 5 6 7".scale("C:ritusen")).sound("folkharp")
-   .grow("1 -1").pace(8)
+ * .grow("1 -1").pace(8)
 */

 export const grow = register(
@@ -3459,17 +3721,17 @@ export const grow = register(

 /**
 * *Experimental*
- * 
- * Inserts a pattern into a list of patterns. On the first repetition it will be inserted at the end of the list, then moved backwards through the list 
- * on successive repetitions. The patterns are added together stepwise, with all repetitions taking place over a single cycle. Using `pace` to set the 
+ *
+ * Inserts a pattern into a list of patterns. On the first repetition it will be inserted at the end of the list, then moved backwards through the list
+ * on successive repetitions. The patterns are added together stepwise, with all repetitions taking place over a single cycle. Using `pace` to set the
 * number of steps per cycle is therefore usually recommended.
 *
 * @tags stepwise
 * @return {Pattern}
 * @example
 * "[c g]".tour("e f", "e f g", "g f e c").note()
-   .sound("folkharp")
-   .pace(8)
+ * .sound("folkharp")
+ * .pace(8)
 */
 export const tour = function (pat, ...many) {
  return pat.tour(...many);
@@ -3487,16 +3749,16 @@ Pattern.prototype.tour = function (...many) {

 /**
 * *Experimental*
- * 
- * 'zips' together the steps of the provided patterns. This can create a long repetition, taking place over a single, dense cycle. 
+ *
+ * 'zips' together the steps of the provided patterns. This can create a long repetition, taking place over a single, dense cycle.
 * Using `pace` to set the number of steps per cycle is therefore usually recommended.
- * 
+ *
 * @tags stepwise
 * @returns {Pattern}
 * @example
 * zip("e f", "e f g", "g [f e] a f4 c").note()
-   .sound("folkharp")
-   .pace(8)
+ * .sound("folkharp")
+ * .pace(8)
 */
 export const zip = function (...pats) {
  pats = pats.filter((pat) => pat.hasSteps);
@@ -104,6 +104,8 @@ export const pickmodF = register('pickmodF', function (pickPattern, lookup, pat)
 * @param {Pattern} pat
 * @param {*} xs
 * @returns {Pattern}
+ * @example
+ * note("<0*4 1 2*2 3*3>".pickOut(["g a", "e f", "f g f g" , "g c d"]))
 */
 export const pickOut = register('pickOut', function (lookup, pat) {
  return _pick(lookup, pat, false).outerJoin();
@@ -9,6 +9,12 @@ let cpsFunc;
 let pattern;
 let triggerFunc;
 let isStarted;
+
+/**
+ * @name getTime
+ * @tags internals
+ * @returns {Number} the current cycle time as a number
+ */
 export function getTime() {
  if (!time) {
    throw new Error('no time set! use setTime to define a time source');
@@ -24,6 +30,11 @@ export function setCpsFunc(func) {
  cpsFunc = func;
 }

+/**
+ * @name getCps
+ * @tags internals
+ * @returns {Number} the current cycles per second
+ */
 export function getCps() {
  return cpsFunc?.();
 }
@@ -5,7 +5,7 @@ This program is free software: you can redistribute it and/or modify it under th
 */

 import { Hap } from './hap.mjs';
-import { Pattern, fastcat, pure, register, reify, silence, stack, sequenceP } from './pattern.mjs';
+import { Pattern, fastcat, pure, register, reify, silence, stack, sequenceP, isPattern } from './pattern.mjs';
 import { _mod } from './util.mjs';
 import Fraction from './fraction.mjs';

@@ -16,6 +16,24 @@ export function steady(value) {
  return new Pattern((state) => [new Hap(undefined, state.span, value)]);
 }

+/**
+ * Creates a signal given by the input function
+ *
+ * @name signal
+ * @param {*} func
+ * @returns {Pattern} signal
+ * @tags generators
+ * @example
+ * // sawtooth signal definition
+ * signal(t=>t%1).segment(16).range(30,40).note()
+ * @example
+ * signal(t=>Math.pow(t,2)%1).range(40, 60).add(5).segment(16)
+ * .off(0, x=>x.add(7))
+ * .note()
+ * .s("gm_electric_guitar_jazz,gm_epiano")
+ *   .gain(1.7)
+ * .pianoroll()
+ */
 export const signal = (func) => {
  const query = (state) => [new Hap(undefined, state.span, func(state.span.begin, state.controls))];
  return new Pattern(query);
@@ -189,6 +207,7 @@ export const time = signal(id);
 /**
 *  The mouse's x position value ranges from 0 to 1.
 * @name mousex
+ * @synonyms mouseX
 * @return {Pattern}
 * @tags external_io
 * @example
@@ -199,6 +218,7 @@ export const time = signal(id);
 /**
 *  The mouse's y position value ranges from 0 to 1.
 * @name mousey
+ * @synonyms mouseY
 * @return {Pattern}
 * @tags external_io
 * @example
@@ -559,6 +579,9 @@ export const __chooseWith = (pat, xs) => {
 * @returns {Pattern}
 * @example
 * note("c2 g2!2 d2 f1").s(chooseWith(sine.fast(2), ["sawtooth", "triangle", "bd:6"]))
+ * @example
+ * // Compare with chooseInWith
+ * note(chooseWith("<0 0.5 1>*3", ["c3", "b3", "d3"]))
 */
 export const chooseWith = (pat, xs) => {
  return __chooseWith(pat, xs).outerJoin();
@@ -570,6 +593,13 @@ export const chooseWith = (pat, xs) => {
 * @tags temporal
 * @param {Pattern} pat
 * @param {*} xs
+ * @example
+ * // Because the structure comes from the chosen values (the notes, here)
+ * // The choosing pattern will only advance once per cycle (not 3 times per cycle)
+ * note(chooseInWith("<0 0.5 1>*3", ["c3", "b3", "d3"]))
+ * @example
+ * // Here, the chosen values have a structure such that the choosing pattern will advance 3 times per cycle
+ * note(chooseInWith("<0 0.5 1>*3", ["c3*3", "b3*3", "d3*3"]))
 * @returns {Pattern}
 */
 export const chooseInWith = (pat, xs) => {
@@ -586,9 +616,7 @@ export const chooseInWith = (pat, xs) => {
 */
 export const choose = (...xs) => chooseWith(rand, xs);

-// todo: doc
 export const chooseIn = (...xs) => chooseInWith(rand, xs);
-export const chooseOut = choose;

 /**
 * Chooses from the given list of values (or patterns of values), according
@@ -734,12 +762,30 @@ export const perlin = signal((t, controls) => _perlin(t, controls.randSeed));
 */
 export const berlin = signal((t, controls) => _berlin(t, controls.randSeed));

-export const degradeByWith = register(
-  'degradeByWith',
-  (withPat, x, pat) => pat.fmap((a) => (_) => a).appLeft(withPat.filterValues((v) => v > x)),
-  true,
-  true,
-);
+/**
+ * `degradeByWith` is like `degradeBy`, but with control over the random or other signal used to filter out the events.
+ *
+ * `degradeBy(x)` is essentially `degradeByWith(rand, x)`
+ *
+ * This allows you to do things other than with `rand`, see examples below
+ *
+ * @name degradeByWith
+ * @param {Pattern|number} test
+ * @param {Pattern|number} testAgainst
+ * @memberof Pattern
+ * @tags temporal
+ * @returns {Pattern}
+ * @example
+ * note("c a f e").degradeByWith(sine, .1)
+ * @example
+ * note("c a f e").degradeByWith(perlin, .5)
+ * @example
+ * note("c a f e").degradeByWith(sine, cosine)
+ */
+export const degradeByWith = register('degradeByWith', (withPat, x, pat) => {
+  if (!isPattern(withPat)) withPat = pure(withPat);
+  return pat.fmap((a) => (_) => a).appLeft(withPat.filterValues((v) => v > x));
+});

 /**
 * Randomly removes events from the pattern by a given amount.
@@ -58,7 +58,7 @@ import {
  arp,
 } from '../index.mjs';

-import { log, logValues } from '../pattern.mjs';
+import { log, logValues, stackCenter } from '../pattern.mjs';

 import { steady } from '../signal.mjs';

@@ -1215,6 +1215,7 @@ describe('Pattern', () => {
      expect(stackRight(fastcat(0, 1, 2), fastcat(3, 4))._steps).toStrictEqual(Fraction(3));
      // maybe this should double when they are either all even or all odd
      expect(stackCentre(fastcat(0, 1, 2), fastcat(3, 4))._steps).toStrictEqual(Fraction(3));
+      expect(stackCenter(fastcat(0, 1, 2), fastcat(3, 4))._steps).toStrictEqual(Fraction(3));
      expect(fastcat(0, 1).ply(3)._steps).toStrictEqual(Fraction(6));
      expect(fastcat(0, 1).setSteps(undefined).ply(3)._steps).toStrictEqual(undefined);
      expect(fastcat(0, 1).fast(3)._steps).toStrictEqual(Fraction(2));
@@ -70,17 +70,6 @@ export const getEventOffsetMs = (targetTimeSeconds, currentTimeSeconds) => {
  return (targetTimeSeconds - currentTimeSeconds) * 1000;
 };

-/**
- * @deprecated does not appear to be referenced or invoked anywhere in the codebase
- * @noAutocomplete
- */
-export const getFreq = (noteOrMidi) => {
-  if (typeof noteOrMidi === 'number') {
-    return midiToFreq(noteOrMidi);
-  }
-  return midiToFreq(noteToMidi(noteOrMidi));
-};
-
 const pcs = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'];
 /**
 * @deprecated only used in workshop (first-notes)
@@ -130,8 +119,31 @@ export const getPlayableNoteValue = (hap) => {
  return note;
 };

+/**
+ * Given a hap, returns the frequency of the note or freq, if defined
+ *
+ * Given a note, returns the frequency of that note
+ * `getFreq('c3')`
+ *
+ * Given a midi note number, returns the frequency of that midi note
+ * `getFreq('c3')`
+ *
+ * @name getFrequency
+ * @tags pitch
+ * @synonyms getFreq
+ * @param {Hap | note | number} input
+ * @returns {Number}
+ * @example
+ * i("4 8 9 10 - - 5 7 9 11 - -").tune("tranh3")
+ * .mul(getFreq('c3'))
+ * .freq().clip(.5).room(1)
+ */
 export const getFrequency = (hap) => {
-  let { value, context } = hap;
+  let { value, context } =
+    typeof hap == 'object'
+      ? hap
+      : // default: interpret value as midi note.
+        { value: hap, context: { type: 'note' } };
  // if value is number => interpret as midi number as long as its not marked as frequency
  if (typeof value === 'object') {
    if (value.freq) {
@@ -140,15 +152,17 @@ export const getFrequency = (hap) => {
    return getFreq(value.note ?? value.n ?? value.value);
  }
  if (typeof value === 'number' && context.type !== 'frequency') {
-    value = midiToFreq(hap.value);
+    value = midiToFreq(value);
  } else if (typeof value === 'string' && isNote(value)) {
-    value = midiToFreq(noteToMidi(hap.value));
+    value = midiToFreq(noteToMidi(value));
  } else if (typeof value !== 'number') {
    throw new Error('not a note or frequency: ' + value);
  }
  return value;
 };

+export const getFreq = (hap) => getFrequency(hap);
+
 // rotate array by n steps (to the left)
 export const rotate = (arr, n) => arr.slice(n).concat(arr.slice(0, n));

@@ -46,7 +46,6 @@ lib[':'] = tail;
 lib['..'] = range;
 lib['def'] = () => silence;
 lib['or'] = (...children) => chooseIn(...children); // always has structure but is cyclewise.. e.g. "s oh*8.dec[.04 | .5]"
-//lib['or'] = (...children) => chooseOut(...children); // "s oh*8.dec[.04 | .5]" is better but "dec[.04 | .5].s oh*8" has no struct

 function evaluator(node, scope) {
  const { type } = node;
@@ -36,8 +36,9 @@ function humanFileSize(bytes, si) {
 *
 * Note: `must` be called with await, otherwise you'll get a pending Promise object.
 *
- * @name getDuration,getDur
- * @tag samples
+ * @name getDuration
+ * @synonym getDur
+ * @tags samples
 * @param {string} sampleName
 * @param {number} (optional) n
 *
@@ -55,6 +55,14 @@ There is also `saw2`, `sine2`, `cosine2`, `tri2`, `square2` and `rand2` which ha

 <JsDoc client:idle name="brandBy" h={0} />

+## time
+
+<JsDoc client:idle name="time" h={0} />
+
+## creating your own signal
+
+<JsDoc client:idle name="signal" h={0} />
+
 ## mouseX

 <JsDoc client:idle name="mousex" h={0} />
@@ -8,7 +8,7 @@ import { JsDoc } from '../../docs/JsDoc';

 # Patterns

-Patterns are the essence of Tidal. Its patterns are abstract entities that represent flows of time as functions, adapting a technique called pure functional reactive programming. Taking a time span as its input, a Pattern can output a set of events that happen within that time span. It depends on the structure of the Pattern how the events are located in time.
+Patterns are the essence of Uzu languages such as Strudel and Tidal. Its patterns are abstract entities that represent flows of time as functions, adapting a technique called pure functional reactive programming. Taking a time span as its input, a Pattern can output a set of events that happen within that time span. It depends on the structure of the Pattern how the events are located in time.
 From now on, this process of generating events from a time span will be called **querying**.
 Example: