Merge branch 'main' into space-shell/helix-keybindings

2026-07-13 14:26:58 -04:00 · 2025-12-15 13:48:44 +01:00
parent a6b3b9ef5e 2748189f18
commit a409149dae
21 changed files with 790 additions and 123 deletions
@@ -1,6 +1,9 @@
 name: Build and Deploy to beta (warm.strudel.cc)

-on: [workflow_dispatch]
+on:
+  push:
+    branches:
+      - main

 # Allow one concurrent deployment
 concurrency:
@@ -4,20 +4,13 @@ Thanks for wanting to contribute!!! There are many ways you can add value to thi

 ## Move to codeberg

-We are currently in the process of moving from github to codeberg -- not everything is working, please bear with us.
-
-To update your local clone, you can run this command:
-
-```
-git remote set-url origin git@codeberg.org:uzu/strudel.git
-```
-
+Along with many other live coding projects, we have moved from Microsoft's Github platform to Codeberg for ethical reasons. Please don't fork the project back to github.

 ## Communication Channels

-To get in touch with the contributors, either
+To get in touch with the community, either

- [join the Tidal Discord Channel](https://discord.com/invite/HGEdXmRkzT) and go to the #strudel channel
+- [join the Uzulang Discord Server](https://discord.com/invite/HGEdXmRkzT) and go to the strudel channels (Uzulangs are a family of live coding languages inspired by each other, including TidalCycles as well as Strudel)
 - Find related discussions on the [tidal club forum](https://club.tidalcycles.org/)

 ## Ask a Question
@@ -36,22 +29,35 @@ Use one of the Communication Channels listed above and drop us a line or two!
 ## Share Music

 If you made some music with strudel, you can give back some love and share what you've done!
-Your creation could also be part of the random selection in the REPL if you want.
 Use one of the Communication Channels listed above.
+(There used to be a random selection of contributed patterns in the REPL, but that is unfortunately disabled for now due to abuse)

 ## Improve the Docs

-If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/),
-you can edit each file directly on codeburg. (we are currently fixing the "Edit this page" links in the right sidebar)
+If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/), you can edit each file directly on codeberg. There are "Edit this page" links in the right sidebar that take you to the right place.

 ## Propose a Feature

-If you want a specific feature that is not part of strudel yet, feel free to use one of the communication channels above.
-Maybe you even want to help with the implementation of that feature!
+If you want a specific feature that is not part of strudel yet, feel free to use one of the communication channels above. Please bear in mind that this is a free/open source project, oriented around collaborative discussion. Maybe you even want to help with the implementation of that feature!
+
+## Contribute a feature
+
+Pull requests welcome! Consider starting with discussion or proof-of-concept first, rather than do loads of work on something and then find it doesn't fit the collective goals of the project, or something like that.
+
+At the time of writing we have a PR backlog, and generally prioritise bugfixes and contributions that have arisen through community discussion.
+
+### AI/LLM policy
+
+Strudel is a project handmade by humans, with thought and nuance. 
+
+If you have used LLMs (so called 'AI'), please detail that in the pull request. We are still developing our response to the onslaught of LLM technology, but for practical and legal reasons are currently not accepting wholly LLM-generated code. We are also not accepting PRs that add LLM features to strudel itself.
+
+There are #llm-chat and #llm-share channels on our discord. Please do not discuss or share LLM-related things outside of those channels.

 ## Report a Bug

 If you've found a bug, or some behaviour that does not seem right, you are welcome to file an [issue](https://codeberg.org/uzu/strudel/issues).
+
 Please check that it has not been reported before.

 ## Fix a Bug
@@ -118,8 +124,7 @@ There are also eslint extensions / plugins for most editors.

 ## Running all CI Checks

-When opening a PR, the CI runner will automatically check the code style and eslint, as well as run all tests.
-You can run the same check with `pnpm check`
+When opening a PR, the CI runner will (once approved by a human) check the code style and eslint, as well as run all tests. You can run the same check with `pnpm check`.

 ## Package Workflow

@@ -0,0 +1,49 @@
+import { describe, bench } from 'vitest';
+
+import { calculateSteps, rand, useRNG } from '../index.mjs';
+
+const testingResolution = 128;
+
+const _generateRandomPattern = () => rand.iter(testingResolution).fast(testingResolution).firstCycle();
+
+describe('old random', () => {
+  calculateSteps(true);
+  bench(
+    '+tactus',
+    () => {
+      useRNG('legacy');
+      _generateRandomPattern();
+    },
+    {
+      time: 1000,
+      teardown() {
+        useRNG('legacy');
+      },
+    },
+  );
+
+  calculateSteps(false);
+  bench(
+    '-tactus',
+    () => {
+      useRNG('precise');
+      _generateRandomPattern();
+    },
+    {
+      time: 1000,
+      teardown() {
+        useRNG('legacy');
+      },
+    },
+  );
+});
+
+describe('random', () => {
+  calculateSteps(true);
+  bench('+tactus', _generateRandomPattern, { time: 1000 });
+
+  calculateSteps(false);
+  bench('-tactus', _generateRandomPattern, { time: 1000 });
+});
+
+calculateSteps(true);
@@ -2753,8 +2753,13 @@ export const as = register('as', (mapping, pat) => {
  mapping = Array.isArray(mapping) ? mapping : [mapping];
  return pat.fmap((v) => {
    v = Array.isArray(v) ? v : [v];
-    v = Object.fromEntries(mapping.map((prop, i) => [getControlName(prop), v[i]]));
-    return v;
+    const entries = [];
+    for (let i = 0; i < mapping.length; ++i) {
+      if (v[i] !== undefined) {
+        entries.push([getControlName(mapping[i]), v[i]]);
+      }
+    }
+    return Object.fromEntries(entries);
  });
 });

@@ -0,0 +1,90 @@
+/*
+stateful.mjs - File of shame for stateful, impure and otherwise illegal pattern methods
+Copyright (C) 2025 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs>
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import { register, reify, Pattern } from './pattern.mjs';
+
+let timelines = {};
+
+export const reset_state = function () {
+  reset_timelines();
+};
+
+export const reset_timelines = function () {
+  timelines = {};
+};
+
+/***
+ * Allows you to switch a pattern between different 'timelines'. This is particularly useful when
+ * live coding, for example when you want to cue a pattern up to play from its start.
+ *
+ * Timelines are specified by number, so that if you had a pattern like
+ * `n("<0 1 2 3>").s("num").timeline(1)` playing, then changed the '1'
+ * to '2', it would always align '0' to the nearest cycle. You will likely want to trigger
+ * an evaluation a little bit before the cycle starts, to avoid missing events.
+ *
+ * After the first use, a timeline will continue with the same 'offset'. That is, if you change
+ * a pattern without changing its timeline number, it will stay on that timeline without resetting.
+ *
+ * Rather than incrementing a timeline to reset it, it's easier to negate it, e.g. by switching between `-2`
+ * and `2`. This is because when you negate a timeline it will always reset.
+ *
+ * You can also pattern the timeline if you want, to create strange resetting patterns.
+ * @param {number | Pattern} timeline The timeline that the pattern should play on.
+ * @example
+ * n("<0 1 2 3>(3,8)")
+ *   .sound("num")
+ *   // resets the timeline every two cycles, by negating the timeline.
+ *   // in a lot of cases this will be edited by a human live coder
+ *   // rather than patterned!
+ *   .timeline("<2 -2>".slow(2))
+ */
+
+export const timeline = register(
+  'timeline',
+  function (tpat, pat) {
+    tpat = reify(tpat);
+    const f = function (state) {
+      // Is this called from the scheduler? (rather than from e.g. the visualiser)
+      const scheduler = !!state.controls.cyclist;
+      const timehaps = tpat.query(state);
+      const result = [];
+      for (const timehap of timehaps) {
+        const tlid = timehap.value;
+        let offset;
+        if (tlid === 0) {
+          offset = 0;
+        } else if (tlid in timelines) {
+          offset = timelines[tlid];
+        } else {
+          const timearc = timehap.wholeOrPart();
+          if (!scheduler || state.span.begin.lt(timearc.midpoint())) {
+            offset = timearc.begin;
+          } else {
+            // Sync to end of timearc if we first see it over halfway into its
+            // timespan. Allows 'cuing up' next timeline when live coding.
+            offset = timearc.end;
+          }
+        }
+        if (scheduler) {
+          // update state
+          timelines[tlid] = offset;
+          if (tlid !== 0) {
+            delete timelines[-tlid];
+          }
+        }
+
+        const pathaps = pat
+          .late(offset)
+          .query(state.setSpan(timehap.part))
+          .map((h) => h.setContext(h.combineContext(timehap)));
+        result.push(...pathaps);
+      }
+      return result;
+    };
+    return new Pattern(f, pat._steps);
+  },
+  false,
+);
@@ -1,6 +1,6 @@
 /*
 index.mjs - <short description TODO>
-Copyright (C) 2022 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs>
+Copyright (C) 2025 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs>
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

@@ -11,20 +11,21 @@ import createClock from './zyklus.mjs';
 import { logger } from './logger.mjs';
 export { Fraction, controls, createClock };
 export * from './controls.mjs';
-export * from './hap.mjs';
-export * from './pattern.mjs';
-export * from './signal.mjs';
-export * from './pick.mjs';
-export * from './state.mjs';
-export * from './timespan.mjs';
-export * from './util.mjs';
-export * from './speak.mjs';
-export * from './evaluate.mjs';
-export * from './repl.mjs';
 export * from './cyclist.mjs';
+export * from './evaluate.mjs';
+export * from './hap.mjs';
+export * from './impure.mjs';
 export * from './logger.mjs';
+export * from './pattern.mjs';
+export * from './pick.mjs';
+export * from './repl.mjs';
+export * from './signal.mjs';
+export * from './speak.mjs';
+export * from './state.mjs';
 export * from './time.mjs';
+export * from './timespan.mjs';
 export * from './ui.mjs';
+export * from './util.mjs';
 export { default as drawLine } from './drawLine.mjs';
 // below won't work with runtime.mjs (json import fails)
 /* import * as p from './package.json';
@@ -5,6 +5,7 @@ import { errorLogger, logger } from './logger.mjs';
 import { setTime } from './time.mjs';
 import { evalScope } from './evaluate.mjs';
 import { register, Pattern, isPattern, silence, stack } from './pattern.mjs';
+import { reset_state } from './impure.mjs';

 export function repl({
  defaultOutput,
@@ -52,6 +53,9 @@ export function repl({
    onToggle: (started) => {
      updateState({ started });
      onToggle?.(started);
+      if (!started) {
+        reset_state();
+      }
    },
    setInterval,
    clearInterval,
@@ -16,7 +16,7 @@ export function steady(value) {
 }

 export const signal = (func) => {
-  const query = (state) => [new Hap(undefined, state.span, func(state.span.begin))];
+  const query = (state) => [new Hap(undefined, state.span, func(state.span.begin, state.controls))];
  return new Pattern(query);
 };

@@ -186,38 +186,97 @@ export const mouseY = signal(() => _mouseY);
 export const mousex = signal(() => _mouseX);
 export const mouseX = signal(() => _mouseX);

-// random signals
+// Random number generators

-const xorwise = (x) => {
+// Produce "Avalanche effect" where flipping a single bit of x
+// results in all output bits flipping with probability 0.5
+// See e.g. https://github.com/aappleby/smhasher/blob/0ff96f7835817a27d0487325b6c16033e2992eb5/src/MurmurHash3.cpp#L68-L77
+const _murmurHashFinalizer = (x) => {
+  x |= 0;
+  x ^= x >>> 16;
+  x = Math.imul(x, 0x85ebca6b);
+  x ^= x >>> 13;
+  x = Math.imul(x, 0xc2b2ae35);
+  x ^= x >>> 16;
+  return x >>> 0; // unsigned
+};
+
+// Convert t to a 32 bit integer, preserving temporal resolution down to 1/2^29
+const _tToT = (t) => {
+  return Math.floor(t * 536870912);
+};
+
+// Used to decorrelate nearby T, i, and seed prior to hashing
+const _decorrelate = (T, i = 0, seed = 0) => {
+  const lowBits = (T >>> 0) >>> 0;
+  const highBits = Math.floor(T / 4294967296) >>> 0; // 2^32
+  let key = lowBits ^ Math.imul(highBits ^ 0x85ebca6b, 0xc2b2ae35);
+  key ^= Math.imul(i ^ 0x7f4a7c15, 0x9e3779b9);
+  key ^= Math.imul(seed ^ 0x165667b1, 0x27d4eb2d);
+  return key >>> 0;
+};
+
+const randAt = (T, i = 0, seed = 0) => {
+  return _murmurHashFinalizer(_decorrelate(T, i, seed)) / 4294967296; // 2^32
+};
+
+// n samples at time t
+const timeToRands = (t, n, seed = 0) => {
+  const T = _tToT(t);
+  if (n === 1) {
+    return randAt(T, 0, seed);
+  }
+  const out = new Array(n);
+  for (let i = 0; i < n; i++) out[i] = randAt(T, i, seed);
+  return out;
+};
+
+// Old random signals. Currently the default, but can also be chosen via
+// `useRNG('legacy')`
+
+// stretch 300 cycles over the range of [0,2**29 == 536870912) then apply the xorshift algorithm
+const __xorwise = (x) => {
  const a = (x << 13) ^ x;
  const b = (a >> 17) ^ a;
  return (b << 5) ^ b;
 };
-
-// stretch 300 cycles over the range of [0,2**29 == 536870912) then apply the xorshift algorithm
-const _frac = (x) => x - Math.trunc(x);
-
-const timeToIntSeed = (x) => xorwise(Math.trunc(_frac(x / 300) * 536870912));
-
-const intSeedToRand = (x) => (x % 536870912) / 536870912;
-
-const timeToRand = (x) => Math.abs(intSeedToRand(timeToIntSeed(x)));
-
-const timeToRandsPrime = (seed, n) => {
+const __frac = (x) => x - Math.trunc(x);
+const __timeToIntSeed = (x) => __xorwise(Math.trunc(__frac(x / 300) * 536870912));
+const __intSeedToRand = (x) => (x % 536870912) / 536870912;
+const __timeToRandsPrime = (seed, n) => {
+  if (n === 1) {
+    return Math.abs(__intSeedToRand(seed));
+  }
  const result = [];
-  // eslint-disable-next-line
-  for (let i = 0; i < n; ++i) {
-    result.push(intSeedToRand(seed));
-    seed = xorwise(seed);
+  for (let i = 0; i < n; i++) {
+    result.push(__intSeedToRand(seed));
+    seed = __xorwise(seed);
  }
  return result;
 };
+const __timeToRands = (t, n) => __timeToRandsPrime(__timeToIntSeed(t), n);

-const timeToRands = (t, n) => timeToRandsPrime(timeToIntSeed(t), n);
+// End old random
+
+let RNG_MODE = 'legacy';
+export const getRandsAtTime = (t, n = 1, seed = 0) => {
+  return RNG_MODE === 'legacy' ? __timeToRands(t + seed, n) : timeToRands(t, n, seed);
+};

 /**
+ * Sets which random number generator to use. Historically Strudel would
+ * use `useRNG('legacy')`, which remains the default. To use a new more statistically
+ * precise RNG, try `useRNG('precise')`.
 *
+ * @name useRNG
+ * @param {string} mod - Mode. One of 'legacy', 'precise'
+ * @example
+ * useRNG('legacy')
+ * // Repeats every 300 cycles
+ * $: n(irand(50)).seg(16).scale("C:minor").ribbon(88, 32)
+ * $: n(irand(50)).seg(16).scale("C:minor").ribbon(388, 32)
 */
+export const useRNG = (mode = 'legacy') => (RNG_MODE = mode);

 /**
 * A discrete pattern of numbers from 0 to n-1
@@ -300,13 +359,13 @@ export const binaryNL = (n, nBits = 16) => {
 *   .partials(randL(8))
 */
 export const randL = (n) => {
-  return signal((t) => (nVal) => timeToRands(t, nVal).map(Math.abs)).appLeft(reify(n));
+  return signal((t) => (nVal) => getRandsAtTime(t, nVal).map(Math.abs)).appLeft(reify(n));
 };

 export const randrun = (n) => {
-  return signal((t) => {
+  return signal((t, controls) => {
    // Without adding 0.5, the first cycle is always 0,1,2,3,...
-    const rands = timeToRands(t.floor().add(0.5), n);
+    const rands = getRandsAtTime(t.floor().add(0.5), n, controls.randSeed);
    const nums = rands
      .map((n, i) => [n, i])
      .sort((a, b) => (a[0] > b[0]) - (a[0] < b[0]))
@@ -347,6 +406,37 @@ export const scramble = register('scramble', (n, pat) => {
  return _rearrangeWith(_irand(n)._segment(n), n, pat);
 });

+/**
+ * Modify a pattern by applying a function to the `randomSeed` control if present
+ *
+ * @param {Function} func Function from seed (or undefined) to seed (or undefined)
+ * @param {Pattern} pat Pattern to update
+ * @returns Pattern
+ */
+export const withSeed = (func, pat) => {
+  return new Pattern((state) => {
+    let { randSeed, ...controls } = state.controls;
+    randSeed = func(randSeed);
+    return pat.query(state.setControls({ ...controls, randSeed }));
+  }, pat._steps);
+};
+
+/**
+ * Change the seed for random signals. Normally, random signals depend on time,
+ * so two patterns at the same time will have the same random values. Specifying
+ * a new seed changes the signal output by `rand`. This also affects other functions
+ * that use randomness, like `shuffle` and `sometimes`.
+ *
+ * @name seed
+ * @param {number} n A new seed. Can be any number.
+ * @example
+ * $: s("hh*4").degrade();
+ * $: s("bd*4").degrade().seed(1); // Will degrade different events from the hi-hat
+ */
+export const seed = register('seed', (n, pat) => {
+  return withSeed(() => n, pat);
+});
+
 /**
 * A continuous pattern of random numbers, between 0 and 1.
 *
@@ -356,7 +446,7 @@ export const scramble = register('scramble', (n, pat) => {
 * s("bd*4,hh*8").cutoff(rand.range(500,8000))
 *
 */
-export const rand = signal(timeToRand);
+export const rand = signal((t, controls) => getRandsAtTime(t, 1, controls.randSeed));
 /**
 * A continuous pattern of random numbers, between -1 and 1
 */
@@ -533,36 +623,32 @@ export const wchooseCycles = (...pairs) => _wchooseWith(rand.segment(1), ...pair

 export const wrandcat = wchooseCycles;

-function _perlin(t) {
+function _perlin(t, seed = 0) {
  let ta = Math.floor(t);
  let tb = ta + 1;
  const smootherStep = (x) => 6.0 * x ** 5 - 15.0 * x ** 4 + 10.0 * x ** 3;
  const interp = (x) => (a) => (b) => a + smootherStep(x) * (b - a);
-  const v = interp(t - ta)(timeToRand(ta))(timeToRand(tb));
+  const ra = getRandsAtTime(ta, 1, seed);
+  const rb = getRandsAtTime(tb, 1, seed);
+  const v = interp(t - ta)(ra)(rb);
  return v;
 }
-export const perlinWith = (tpat) => {
-  return tpat.fmap(_perlin);
-};

-function _berlin(t) {
+function _berlin(t, seed = 0) {
  const prevRidgeStartIndex = Math.floor(t);
  const nextRidgeStartIndex = prevRidgeStartIndex + 1;

-  const prevRidgeBottomPoint = timeToRand(prevRidgeStartIndex);
-  const nextRidgeTopPoint = timeToRand(nextRidgeStartIndex) + prevRidgeBottomPoint;
+  const prevRidgeBottomPoint = getRandsAtTime(prevRidgeStartIndex, 1, seed);
+  const height = getRandsAtTime(nextRidgeStartIndex, 1, seed);
+  const nextRidgeTopPoint = prevRidgeBottomPoint + height;

  const currentPercent = (t - prevRidgeStartIndex) / (nextRidgeStartIndex - prevRidgeStartIndex);
  const interp = (a, b, t) => {
-    return a + (b - a) * t;
+    return a + t * (b - a);
  };
  return interp(prevRidgeBottomPoint, nextRidgeTopPoint, currentPercent) / 2;
 }

-export const berlinWith = (tpat) => {
-  return tpat.fmap(_berlin);
-};
-
 /**
 * Generates a continuous pattern of [perlin noise](https://en.wikipedia.org/wiki/Perlin_noise), in the range 0..1.
 *
@@ -572,7 +658,7 @@ export const berlinWith = (tpat) => {
 * s("bd*4,hh*8").cutoff(perlin.range(500,8000))
 *
 */
-export const perlin = perlinWith(time.fmap((v) => Number(v)));
+export const perlin = signal((t, controls) => _perlin(t, controls.randSeed));

 /**
 * Generates a continuous pattern of [berlin noise](conceived by Jame Coyne and Jade Rowland as a joke but turned out to be surprisingly cool and useful,
@@ -584,7 +670,7 @@ export const perlin = perlinWith(time.fmap((v) => Number(v)));
 * n("0!16".add(berlin.fast(4).mul(14))).scale("d:minor")
 *
 */
-export const berlin = berlinWith(time.fmap((v) => Number(v)));
+export const berlin = signal((t, controls) => _berlin(t, controls.randSeed));

 export const degradeByWith = register(
  'degradeByWith',
@@ -882,3 +968,50 @@ export const whenKey = register('whenKey', function (input, func, pat) {
 export const keyDown = register('keyDown', function (pat) {
  return pat.fmap(_keyDown);
 });
+
+/**
+ * A pattern measuring the duration of events,
+ * in cycles per event. `cyclesPer` doesn't have structure itself, but takes structure, and therefore
+ * event durations, from the pattern that it is combined with.
+ * For example `cyclesPer.struct("1 1 [1 1] 1")` would give the same as `"0.25 0.25 [0.125 0.125] 0.25"`.
+ * See also its reciprocal, `per`, also known as `perCycle`.
+ * @example
+ * // Shorter events are lower in pitch
+ * sound("saw saw [saw saw] saw")
+ *   .note(cyclesPer.range(50, 100))
+ * @example
+ * sound("bd sd [bd bd] sd*4 [- sd] [bd [bd bd]]")
+ *   .note(cyclesPer.add(20))
+ */
+export const cyclesPer = new Pattern(function (state) {
+  return [new Hap(undefined, state.span, state.span.duration)];
+});
+
+/**
+ * A pattern measuring the 'shortness' of events, or in other words, the duration of pattern events,
+ * in events per cycle. `per` doesn't have structure itself, but takes structure, and therefore
+ * event durations, from the pattern that it is combined with.
+ * For example `per.struct("1 1 [1 1] 1")` would give the same as `"4 4 [8 8] 4"`.
+ * See also its reciprocal, `cyclesPer`.
+ * @synonyms perCycle
+ * @example
+ * // Shorter events are more distorted
+ * n("0 0*2 0 0*2 0 [0 0 0]@2").sound("bd")
+ *  .distort(per.div(2))
+ */
+export const per = new Pattern(function (state) {
+  return [new Hap(undefined, state.span, Fraction(1).div(state.span.duration))];
+});
+
+export const perCycle = per;
+
+/**
+ * Like `per` but measures the shortness of events according to an exponential curve. In
+ * particular, where the event duration halves, the
+ * returned value increases by one. `perx.struct("1 1 [1 [1 1]] 1")` would therefore be
+ * the same as `"3 3 [4 [5 5]] 3"`.
+ */
+export const perx = new Pattern(function (state) {
+  const n = Fraction(1).div(state.span.duration);
+  return [new Hap(undefined, state.span, Math.log(n) / Math.log(2) + 1)];
+});
@@ -740,20 +740,6 @@ describe('Pattern', () => {
      );
    });
  });
-  describe('signal()', () => {
-    it('Can make saw/saw2', () => {
-      expect(saw.struct(true, true, true, true).firstCycle()).toStrictEqual(
-        sequence(0, 1 / 4, 1 / 2, 3 / 4).firstCycle(),
-      );
-
-      expect(saw2.struct(true, true, true, true).firstCycle()).toStrictEqual(sequence(-1, -0.5, 0, 0.5).firstCycle());
-    });
-    it('Can make isaw/isaw2', () => {
-      expect(isaw.struct(true, true, true, true).firstCycle()).toStrictEqual(sequence(1, 0.75, 0.5, 0.25).firstCycle());
-
-      expect(isaw2.struct(true, true, true, true).firstCycle()).toStrictEqual(sequence(1, 0.5, 0, -0.5).firstCycle());
-    });
-  });
  describe('_setContext()', () => {
    it('Can set the hap context', () => {
      expect(
@@ -0,0 +1,61 @@
+/*
+signal.test.mjs - <short description TODO>
+Copyright (C) 2022 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/test/pattern.test.mjs>
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+
+import Fraction from 'fraction.js';
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { saw, saw2, isaw, isaw2, per, perx, cyclesPer } from '../signal.mjs';
+import { fastcat, sequence, State, TimeSpan, Hap } from '../index.mjs';
+
+const st = (begin, end) => new State(ts(begin, end));
+const ts = (begin, end) => new TimeSpan(Fraction(begin), Fraction(end));
+const hap = (whole, part, value, context = {}) => new Hap(whole, part, value, context);
+
+const third = Fraction(1, 3);
+const twothirds = Fraction(2, 3);
+
+const sameFirst = (a, b) => {
+  return expect(a.sortHapsByPart().firstCycle()).toStrictEqual(b.sortHapsByPart().firstCycle());
+};
+
+describe('signal()', () => {
+  it('Can make saw/saw2', () => {
+    expect(saw.struct(true, true, true, true).firstCycle()).toStrictEqual(
+      sequence(0, 1 / 4, 1 / 2, 3 / 4).firstCycle(),
+    );
+
+    expect(saw2.struct(true, true, true, true).firstCycle()).toStrictEqual(sequence(-1, -0.5, 0, 0.5).firstCycle());
+  });
+  it('Can make isaw/isaw2', () => {
+    expect(isaw.struct(true, true, true, true).firstCycle()).toStrictEqual(sequence(1, 0.75, 0.5, 0.25).firstCycle());
+
+    expect(isaw2.struct(true, true, true, true).firstCycle()).toStrictEqual(sequence(1, 0.5, 0, -0.5).firstCycle());
+  });
+});
+
+describe('cyclesPer', () => {
+  it('gives cycles per hap', () => {
+    sameFirst(
+      cyclesPer.struct(true, true, true, fastcat(true, true)),
+      sequence(0.25, 0.25, 0.25, fastcat(0.125, 0.125)).fmap(Fraction),
+    );
+  });
+});
+describe('per', () => {
+  it('gives haps per cycle', () => {
+    sameFirst(per.struct(true, true, true, fastcat(true, true)), sequence(4, 4, 4, fastcat(8, 8)).fmap(Fraction));
+  });
+});
+
+describe('perx', () => {
+  it('gives exponential haps per cycle', () => {
+    sameFirst(
+      perx.struct(true, true, true, fastcat(true, fastcat(true, true))),
+      sequence(3, 3, 3, fastcat(4, fastcat(5, 5))),
+    );
+  });
+});
@@ -7,6 +7,7 @@ import {
  getPitchEnvelope,
  getVibratoOscillator,
  onceEnded,
+  releaseAudioNode,
 } from '@strudel/webaudio';
 import gm from './gm.mjs';

@@ -172,9 +173,8 @@ export function registerSoundfonts() {
        bufferSource.stop(envEnd);
        const stop = (releaseTime) => {};
        onceEnded(bufferSource, () => {
-          bufferSource.disconnect();
-          vibratoOscillator?.stop();
-          node.disconnect();
+          releaseAudioNode(bufferSource);
+          releaseAudioNode(vibratoOscillator);
          onended();
        });
        return { node, stop };
@@ -189,7 +189,7 @@ export function applyParameterModulators(audioContext, param, start, end, envelo
    getParamADSR(param, attack, decay, sustain, release, min, max, start, holdEnd, curve);
  }
  const lfo = getParamLfo(audioContext, param, start, end, lfoValues);
-  return { lfo, disconnect: () => lfo?.disconnect() };
+  return lfo;
 }
 export function createFilter(context, start, end, params, cps, cycle) {
  let {
@@ -283,9 +283,12 @@ export function drywet(dry, wet, wetAmount = 0) {
  wet_gain.connect(mix);
  return {
    node: mix,
-    onended: () => {
-      dry_gain.disconnect(mix);
-      wet_gain.disconnect(mix);
+    teardown: () => {
+      releaseAudioNode(dry_gain);
+      releaseAudioNode(wet_gain);
+      // it is not the responsability of drywet
+      // to call `releaseAudioNode` on
+      // the 2 external args dry and wet
      dry.disconnect(dry_gain);
      wet.disconnect(wet_gain);
    },
@@ -324,10 +327,10 @@ export function getVibratoOscillator(param, value, t) {
    gain.gain.value = vibmod * 100;
    vibratoOscillator.connect(gain);
    gain.connect(param);
-    vibratoOscillator.onended = () => {
-      gain.disconnect(param);
-      vibratoOscillator.disconnect(gain);
-    };
+    onceEnded(vibratoOscillator, () => {
+      releaseAudioNode(gain);
+      releaseAudioNode(vibratoOscillator);
+    });
    vibratoOscillator.start(t);
    return vibratoOscillator;
  }
@@ -590,7 +593,7 @@ export const releaseAudioNode = (node) => {
  // make sure all AudioScheduledSourceNodes are in a stopped state
  // https://developer.mozilla.org/en-US/docs/Web/API/AudioScheduledSourceNode
  if (node instanceof AudioScheduledSourceNode) {
-    if (node.onended && node.onended.name !== 'cleanup') {
+    if (process.env.NODE_ENV === 'development' && node.onended && node.onended.name !== 'cleanup') {
      logger(
        `[superdough] Deprecation warning: it seems your code path is setting 'node.onended = callback' instead of using the onceEnded helper`,
      );
@@ -613,6 +616,8 @@ export const releaseAudioNode = (node) => {
  // returns true and either its active source flag is true or
  // any AudioNode connected to one of its inputs is actively processing.
  if (node instanceof AudioWorkletNode) {
+    // while `end` is not native to the web audio API, it is common practice in superdough
+    // to use that param in the worklets to trigger returning false from the processor
    node.parameters.get('end')?.setValueAtTime(0, 0);
  }
 };
@@ -1,4 +1,4 @@
-import { drywet } from './helpers.mjs';
+import { drywet, onceEnded, releaseAudioNode } from './helpers.mjs';
 import { getAudioContext } from './audioContext.mjs';

 let noiseCache = {};
@@ -65,9 +65,12 @@ export function getNoiseOscillator(type = 'white', t, density = 0.02) {
 export function getNoiseMix(inputNode, wet, t) {
  const noiseOscillator = getNoiseOscillator('pink', t);
  const noiseMix = drywet(inputNode, noiseOscillator.node, wet);
-  noiseOscillator.node.onended = () => noiseMix.onended();
+  onceEnded(noiseOscillator.node, () => {
+    releaseAudioNode(noiseOscillator.node);
+  });
  return {
    node: noiseMix.node,
    stop: (time) => noiseOscillator?.stop(time),
+    teardown: noiseMix.teardown,
  };
 }
@@ -323,10 +323,10 @@ export async function onTriggerSample(t, value, onended, bank, resolveUrl) {
  const out = ac.createGain(); // we need a separate gain for the cutgroups because firefox...
  node.connect(out);
  onceEnded(bufferSource, function () {
-    bufferSource.disconnect();
-    vibratoOscillator?.stop();
-    node.disconnect();
-    out.disconnect();
+    releaseAudioNode(bufferSource);
+    releaseAudioNode(vibratoOscillator);
+    releaseAudioNode(node);
+    releaseAudioNode(out);
    onended();
  });
  let envEnd = holdEnd + release + 0.01;
@@ -9,7 +9,16 @@ import './reverb.mjs';
 import './vowel.mjs';
 import { nanFallback, _mod, cycleToSeconds, pickAndRename } from './util.mjs';
 import workletsUrl from './worklets.mjs?audioworklet';
-import { createFilter, gainNode, getCompressor, getDistortion, getLfo, getWorklet, effectSend } from './helpers.mjs';
+import {
+  createFilter,
+  gainNode,
+  getCompressor,
+  getDistortion,
+  getLfo,
+  getWorklet,
+  effectSend,
+  releaseAudioNode,
+} from './helpers.mjs';
 import { map } from 'nanostores';
 import { logger } from './logger.mjs';
 import { loadBuffer } from './sampler.mjs';
@@ -21,6 +30,17 @@ const DEFAULT_AUDIO_DEVICE_NAME = 'System Standard';

 let maxPolyphony = DEFAULT_MAX_POLYPHONY;

+/**
+ * Set the max polyphony. If notes are ringing out via `release` then they will
+ * start to die out in first-in-first-out order once the max polyphony has been hit
+ *
+ * @name setMaxPolyphony
+ * @param {number} Max polyphony. Defaults to 128
+ * @example
+ * setMaxPolyphony(4)
+ * n(irand(24).seg(8)).scale("C#3:minor").room(1).release(4).gain(0.5)
+ *
+ */
 export function setMaxPolyphony(polyphony) {
  maxPolyphony = parseInt(polyphony) ?? DEFAULT_MAX_POLYPHONY;
 }
@@ -43,6 +63,17 @@ export function applyGainCurve(val) {
  return gainCurveFunc(val);
 }

+/**
+ * Apply a function to all gains provided in patterns. Can be used to rescale gain to be
+ * quadratic, exponential, etc. rather than linear
+ *
+ * @name setGainCurve
+ * @param {Function} function to apply to all gain values
+ * @example
+ * setGainCurve((x) => x * x) // quadratic gain
+ * s("bd*4").gain(0.5) // equivalent to 0.25 gain normally
+ *
+ */
 export function setGainCurve(newGainCurveFunc) {
  gainCurveFunc = newGainCurveFunc;
 }
@@ -505,7 +536,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
  } else if (getSound(s)) {
    const { onTrigger } = getSound(s);
    const onEnded = () => {
-      audioNodes.forEach((n) => n?.disconnect());
+      audioNodes.forEach((n) => releaseAudioNode(n));
      activeSoundSources.delete(chainID);
    };
    const soundHandle = await onTrigger(t, value, onEnded, cps);
@@ -12,6 +12,7 @@ import {
  getVibratoOscillator,
  getWorklet,
  noises,
+  onceEnded,
  releaseAudioNode,
  webAudioTimeout,
 } from './helpers.mjs';
@@ -52,7 +53,7 @@ export function registerSynthSounds() {
        const g = gainNode(0.3);

        let sound = getOscillator(s, t, value, () => {
-          g.disconnect();
+          releaseAudioNode(g);
          onended();
        });

@@ -110,15 +111,15 @@ export function registerSynthSounds() {

      const mix = gainNode(mixGain);

-      o.onended = () => {
-        o.disconnect();
-        g.disconnect();
-        sat.disconnect();
-        noise.node.disconnect();
-        noiseGain.disconnect();
-        mix.disconnect();
+      onceEnded(o, () => {
+        releaseAudioNode(o);
+        releaseAudioNode(g);
+        releaseAudioNode(sat);
+        releaseAudioNode(noise.node);
+        releaseAudioNode(noiseGain);
+        releaseAudioNode(mix);
        onended();
-      };
+      });

      const node = o.connect(sat).connect(g).connect(mix);
      noise.node.connect(noiseGain).connect(mix);
@@ -384,11 +385,11 @@ export function registerSynthSounds() {

        const { duration } = value;

-        o.onended = () => {
-          o.disconnect();
-          g.disconnect();
+        onceEnded(o, () => {
+          releaseAudioNode(o);
+          releaseAudioNode(g);
          onended();
-        };
+        });

        const envGain = gainNode(1);
        let node = o.connect(g).connect(envGain);
@@ -489,11 +490,12 @@ export function getOscillator(s, t, value, onended) {
    noiseMix = getNoiseMix(o, noise, t);
  }

-  o.onended = () => {
-    noiseMix || o.disconnect();
-    noiseMix?.node.disconnect();
+  onceEnded(o, () => {
+    noiseMix?.teardown();
+    releaseAudioNode(o);
+    releaseAudioNode(noiseMix?.node);
    onended();
-  };
+  });
  o.start(t);

  return {
@@ -320,10 +320,10 @@ export async function onTriggerSynth(t, value, onended, tables, cps, frameLen) {
    ac,
    () => {
      releaseAudioNode(source);
-      vibratoOscillator?.stop();
+      releaseAudioNode(vibratoOscillator);
      fm?.stop();
-      wtPosModulators?.disconnect();
-      wtWarpModulators?.disconnect();
+      releaseAudioNode(wtPosModulators);
+      releaseAudioNode(wtWarpModulators);
      onended();
    },
    t,
@@ -2539,6 +2539,84 @@ exports[`runs examples > example "cut" example index 0 1`] = `
 ]
 `;

+exports[`runs examples > example "cyclesPer" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | s:saw note:62.5 ]",
+  "[ 1/4 → 1/2 | s:saw note:62.5 ]",
+  "[ 1/2 → 5/8 | s:saw note:56.25 ]",
+  "[ 5/8 → 3/4 | s:saw note:56.25 ]",
+  "[ 3/4 → 1/1 | s:saw note:62.5 ]",
+  "[ 1/1 → 5/4 | s:saw note:62.5 ]",
+  "[ 5/4 → 3/2 | s:saw note:62.5 ]",
+  "[ 3/2 → 13/8 | s:saw note:56.25 ]",
+  "[ 13/8 → 7/4 | s:saw note:56.25 ]",
+  "[ 7/4 → 2/1 | s:saw note:62.5 ]",
+  "[ 2/1 → 9/4 | s:saw note:62.5 ]",
+  "[ 9/4 → 5/2 | s:saw note:62.5 ]",
+  "[ 5/2 → 21/8 | s:saw note:56.25 ]",
+  "[ 21/8 → 11/4 | s:saw note:56.25 ]",
+  "[ 11/4 → 3/1 | s:saw note:62.5 ]",
+  "[ 3/1 → 13/4 | s:saw note:62.5 ]",
+  "[ 13/4 → 7/2 | s:saw note:62.5 ]",
+  "[ 7/2 → 29/8 | s:saw note:56.25 ]",
+  "[ 29/8 → 15/4 | s:saw note:56.25 ]",
+  "[ 15/4 → 4/1 | s:saw note:62.5 ]",
+]
+`;
+
+exports[`runs examples > example "cyclesPer" example index 1 1`] = `
+[
+  "[ 0/1 → 1/6 | s:bd note:20.166666666666668 ]",
+  "[ 1/6 → 1/3 | s:sd note:20.166666666666668 ]",
+  "[ 1/3 → 5/12 | s:bd note:20.083333333333332 ]",
+  "[ 5/12 → 1/2 | s:bd note:20.083333333333332 ]",
+  "[ 1/2 → 13/24 | s:sd note:20.041666666666668 ]",
+  "[ 13/24 → 7/12 | s:sd note:20.041666666666668 ]",
+  "[ 7/12 → 5/8 | s:sd note:20.041666666666668 ]",
+  "[ 5/8 → 2/3 | s:sd note:20.041666666666668 ]",
+  "[ 3/4 → 5/6 | s:sd note:20.083333333333332 ]",
+  "[ 5/6 → 11/12 | s:bd note:20.083333333333332 ]",
+  "[ 11/12 → 23/24 | s:bd note:20.041666666666668 ]",
+  "[ 23/24 → 1/1 | s:bd note:20.041666666666668 ]",
+  "[ 1/1 → 7/6 | s:bd note:20.166666666666668 ]",
+  "[ 7/6 → 4/3 | s:sd note:20.166666666666668 ]",
+  "[ 4/3 → 17/12 | s:bd note:20.083333333333332 ]",
+  "[ 17/12 → 3/2 | s:bd note:20.083333333333332 ]",
+  "[ 3/2 → 37/24 | s:sd note:20.041666666666668 ]",
+  "[ 37/24 → 19/12 | s:sd note:20.041666666666668 ]",
+  "[ 19/12 → 13/8 | s:sd note:20.041666666666668 ]",
+  "[ 13/8 → 5/3 | s:sd note:20.041666666666668 ]",
+  "[ 7/4 → 11/6 | s:sd note:20.083333333333332 ]",
+  "[ 11/6 → 23/12 | s:bd note:20.083333333333332 ]",
+  "[ 23/12 → 47/24 | s:bd note:20.041666666666668 ]",
+  "[ 47/24 → 2/1 | s:bd note:20.041666666666668 ]",
+  "[ 2/1 → 13/6 | s:bd note:20.166666666666668 ]",
+  "[ 13/6 → 7/3 | s:sd note:20.166666666666668 ]",
+  "[ 7/3 → 29/12 | s:bd note:20.083333333333332 ]",
+  "[ 29/12 → 5/2 | s:bd note:20.083333333333332 ]",
+  "[ 5/2 → 61/24 | s:sd note:20.041666666666668 ]",
+  "[ 61/24 → 31/12 | s:sd note:20.041666666666668 ]",
+  "[ 31/12 → 21/8 | s:sd note:20.041666666666668 ]",
+  "[ 21/8 → 8/3 | s:sd note:20.041666666666668 ]",
+  "[ 11/4 → 17/6 | s:sd note:20.083333333333332 ]",
+  "[ 17/6 → 35/12 | s:bd note:20.083333333333332 ]",
+  "[ 35/12 → 71/24 | s:bd note:20.041666666666668 ]",
+  "[ 71/24 → 3/1 | s:bd note:20.041666666666668 ]",
+  "[ 3/1 → 19/6 | s:bd note:20.166666666666668 ]",
+  "[ 19/6 → 10/3 | s:sd note:20.166666666666668 ]",
+  "[ 10/3 → 41/12 | s:bd note:20.083333333333332 ]",
+  "[ 41/12 → 7/2 | s:bd note:20.083333333333332 ]",
+  "[ 7/2 → 85/24 | s:sd note:20.041666666666668 ]",
+  "[ 85/24 → 43/12 | s:sd note:20.041666666666668 ]",
+  "[ 43/12 → 29/8 | s:sd note:20.041666666666668 ]",
+  "[ 29/8 → 11/3 | s:sd note:20.041666666666668 ]",
+  "[ 15/4 → 23/6 | s:sd note:20.083333333333332 ]",
+  "[ 23/6 → 47/12 | s:bd note:20.083333333333332 ]",
+  "[ 47/12 → 95/24 | s:bd note:20.041666666666668 ]",
+  "[ 95/24 → 4/1 | s:bd note:20.041666666666668 ]",
+]
+`;
+
 exports[`runs examples > example "decay" example index 0 1`] = `
 [
  "[ 0/1 → 1/4 | note:c3 decay:0.1 sustain:0 ]",
@@ -7913,6 +7991,51 @@ exports[`runs examples > example "penv" example index 0 1`] = `
 ]
 `;

+exports[`runs examples > example "per" example index 0 1`] = `
+[
+  "[ 0/1 → 1/7 | n:0 s:bd distort:3.5 ]",
+  "[ 1/7 → 3/14 | n:0 s:bd distort:7 ]",
+  "[ 3/14 → 2/7 | n:0 s:bd distort:7 ]",
+  "[ 2/7 → 3/7 | n:0 s:bd distort:3.5 ]",
+  "[ 3/7 → 1/2 | n:0 s:bd distort:7 ]",
+  "[ 1/2 → 4/7 | n:0 s:bd distort:7 ]",
+  "[ 4/7 → 5/7 | n:0 s:bd distort:3.5 ]",
+  "[ 5/7 → 17/21 | n:0 s:bd distort:5.25 ]",
+  "[ 17/21 → 19/21 | n:0 s:bd distort:5.25 ]",
+  "[ 19/21 → 1/1 | n:0 s:bd distort:5.25 ]",
+  "[ 1/1 → 8/7 | n:0 s:bd distort:3.5 ]",
+  "[ 8/7 → 17/14 | n:0 s:bd distort:7 ]",
+  "[ 17/14 → 9/7 | n:0 s:bd distort:7 ]",
+  "[ 9/7 → 10/7 | n:0 s:bd distort:3.5 ]",
+  "[ 10/7 → 3/2 | n:0 s:bd distort:7 ]",
+  "[ 3/2 → 11/7 | n:0 s:bd distort:7 ]",
+  "[ 11/7 → 12/7 | n:0 s:bd distort:3.5 ]",
+  "[ 12/7 → 38/21 | n:0 s:bd distort:5.25 ]",
+  "[ 38/21 → 40/21 | n:0 s:bd distort:5.25 ]",
+  "[ 40/21 → 2/1 | n:0 s:bd distort:5.25 ]",
+  "[ 2/1 → 15/7 | n:0 s:bd distort:3.5 ]",
+  "[ 15/7 → 31/14 | n:0 s:bd distort:7 ]",
+  "[ 31/14 → 16/7 | n:0 s:bd distort:7 ]",
+  "[ 16/7 → 17/7 | n:0 s:bd distort:3.5 ]",
+  "[ 17/7 → 5/2 | n:0 s:bd distort:7 ]",
+  "[ 5/2 → 18/7 | n:0 s:bd distort:7 ]",
+  "[ 18/7 → 19/7 | n:0 s:bd distort:3.5 ]",
+  "[ 19/7 → 59/21 | n:0 s:bd distort:5.25 ]",
+  "[ 59/21 → 61/21 | n:0 s:bd distort:5.25 ]",
+  "[ 61/21 → 3/1 | n:0 s:bd distort:5.25 ]",
+  "[ 3/1 → 22/7 | n:0 s:bd distort:3.5 ]",
+  "[ 22/7 → 45/14 | n:0 s:bd distort:7 ]",
+  "[ 45/14 → 23/7 | n:0 s:bd distort:7 ]",
+  "[ 23/7 → 24/7 | n:0 s:bd distort:3.5 ]",
+  "[ 24/7 → 7/2 | n:0 s:bd distort:7 ]",
+  "[ 7/2 → 25/7 | n:0 s:bd distort:7 ]",
+  "[ 25/7 → 26/7 | n:0 s:bd distort:3.5 ]",
+  "[ 26/7 → 80/21 | n:0 s:bd distort:5.25 ]",
+  "[ 80/21 → 82/21 | n:0 s:bd distort:5.25 ]",
+  "[ 82/21 → 4/1 | n:0 s:bd distort:5.25 ]",
+]
+`;
+
 exports[`runs examples > example "perlin" example index 0 1`] = `
 [
  "[ 0/1 → 1/8 | s:hh cutoff:500 ]",
@@ -10290,6 +10413,18 @@ exports[`runs examples > example "scrub" example index 1 1`] = `
 ]
 `;

+exports[`runs examples > example "seed" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | s:bd ]",
+  "[ 1/4 → 1/2 | s:bd ]",
+  "[ 1/2 → 3/4 | s:bd ]",
+  "[ 1/1 → 5/4 | s:bd ]",
+  "[ 7/4 → 2/1 | s:bd ]",
+  "[ 9/4 → 5/2 | s:bd ]",
+  "[ 11/4 → 3/1 | s:bd ]",
+]
+`;
+
 exports[`runs examples > example "segment" example index 0 1`] = `
 [
  "[ 0/1 → 1/24 | note:40 ]",
@@ -10473,6 +10608,64 @@ exports[`runs examples > example "seqPLoop" example index 0 1`] = `
 ]
 `;

+exports[`runs examples > example "setGainCurve" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | s:bd gain:0.5 ]",
+  "[ 1/4 → 1/2 | s:bd gain:0.5 ]",
+  "[ 1/2 → 3/4 | s:bd gain:0.5 ]",
+  "[ 3/4 → 1/1 | s:bd gain:0.5 ]",
+  "[ 1/1 → 5/4 | s:bd gain:0.5 ]",
+  "[ 5/4 → 3/2 | s:bd gain:0.5 ]",
+  "[ 3/2 → 7/4 | s:bd gain:0.5 ]",
+  "[ 7/4 → 2/1 | s:bd gain:0.5 ]",
+  "[ 2/1 → 9/4 | s:bd gain:0.5 ]",
+  "[ 9/4 → 5/2 | s:bd gain:0.5 ]",
+  "[ 5/2 → 11/4 | s:bd gain:0.5 ]",
+  "[ 11/4 → 3/1 | s:bd gain:0.5 ]",
+  "[ 3/1 → 13/4 | s:bd gain:0.5 ]",
+  "[ 13/4 → 7/2 | s:bd gain:0.5 ]",
+  "[ 7/2 → 15/4 | s:bd gain:0.5 ]",
+  "[ 15/4 → 4/1 | s:bd gain:0.5 ]",
+]
+`;
+
+exports[`runs examples > example "setMaxPolyphony" example index 0 1`] = `
+[
+  "[ 0/1 → 1/8 | note:C#3 room:1 release:4 gain:0.5 ]",
+  "[ 1/8 → 1/4 | note:E5 room:1 release:4 gain:0.5 ]",
+  "[ 1/4 → 3/8 | note:D#4 room:1 release:4 gain:0.5 ]",
+  "[ 3/8 → 1/2 | note:E4 room:1 release:4 gain:0.5 ]",
+  "[ 1/2 → 5/8 | note:B3 room:1 release:4 gain:0.5 ]",
+  "[ 5/8 → 3/4 | note:F#3 room:1 release:4 gain:0.5 ]",
+  "[ 3/4 → 7/8 | note:G#3 room:1 release:4 gain:0.5 ]",
+  "[ 7/8 → 1/1 | note:E4 room:1 release:4 gain:0.5 ]",
+  "[ 1/1 → 9/8 | note:A4 room:1 release:4 gain:0.5 ]",
+  "[ 9/8 → 5/4 | note:E5 room:1 release:4 gain:0.5 ]",
+  "[ 5/4 → 11/8 | note:F#5 room:1 release:4 gain:0.5 ]",
+  "[ 11/8 → 3/2 | note:G#3 room:1 release:4 gain:0.5 ]",
+  "[ 3/2 → 13/8 | note:C#5 room:1 release:4 gain:0.5 ]",
+  "[ 13/8 → 7/4 | note:G#4 room:1 release:4 gain:0.5 ]",
+  "[ 7/4 → 15/8 | note:G#3 room:1 release:4 gain:0.5 ]",
+  "[ 15/8 → 2/1 | note:C#5 room:1 release:4 gain:0.5 ]",
+  "[ 2/1 → 17/8 | note:E6 room:1 release:4 gain:0.5 ]",
+  "[ 17/8 → 9/4 | note:C#6 room:1 release:4 gain:0.5 ]",
+  "[ 9/4 → 19/8 | note:D#4 room:1 release:4 gain:0.5 ]",
+  "[ 19/8 → 5/2 | note:B5 room:1 release:4 gain:0.5 ]",
+  "[ 5/2 → 21/8 | note:G#4 room:1 release:4 gain:0.5 ]",
+  "[ 21/8 → 11/4 | note:F#3 room:1 release:4 gain:0.5 ]",
+  "[ 11/4 → 23/8 | note:D#5 room:1 release:4 gain:0.5 ]",
+  "[ 23/8 → 3/1 | note:C#3 room:1 release:4 gain:0.5 ]",
+  "[ 3/1 → 25/8 | note:A3 room:1 release:4 gain:0.5 ]",
+  "[ 25/8 → 13/4 | note:D#4 room:1 release:4 gain:0.5 ]",
+  "[ 13/4 → 27/8 | note:E6 room:1 release:4 gain:0.5 ]",
+  "[ 27/8 → 7/2 | note:E4 room:1 release:4 gain:0.5 ]",
+  "[ 7/2 → 29/8 | note:E4 room:1 release:4 gain:0.5 ]",
+  "[ 29/8 → 15/4 | note:D#6 room:1 release:4 gain:0.5 ]",
+  "[ 15/4 → 31/8 | note:A5 room:1 release:4 gain:0.5 ]",
+  "[ 31/8 → 4/1 | note:F#5 room:1 release:4 gain:0.5 ]",
+]
+`;
+
 exports[`runs examples > example "setcpm" example index 0 1`] = `
 [
  "[ 0/1 → 1/4 | s:bd bank:tr707 ]",
@@ -12818,6 +13011,75 @@ exports[`runs examples > example "unit" example index 0 1`] = `
 ]
 `;

+exports[`runs examples > example "useRNG" example index 0 1`] = `
+[
+  "[ 0/1 → 1/16 | note:D8 ]",
+  "[ 1/16 → 1/8 | note:Bb7 ]",
+  "[ 1/8 → 3/16 | note:Ab6 ]",
+  "[ 3/16 → 1/4 | note:D5 ]",
+  "[ 1/4 → 5/16 | note:Ab9 ]",
+  "[ 5/16 → 3/8 | note:D3 ]",
+  "[ 3/8 → 7/16 | note:G5 ]",
+  "[ 7/16 → 1/2 | note:G3 ]",
+  "[ 1/2 → 9/16 | note:Ab3 ]",
+  "[ 9/16 → 5/8 | note:Eb6 ]",
+  "[ 5/8 → 11/16 | note:Eb6 ]",
+  "[ 11/16 → 3/4 | note:Eb5 ]",
+  "[ 3/4 → 13/16 | note:G7 ]",
+  "[ 13/16 → 7/8 | note:Bb5 ]",
+  "[ 7/8 → 15/16 | note:D3 ]",
+  "[ 15/16 → 1/1 | note:Eb7 ]",
+  "[ 1/1 → 17/16 | note:Eb9 ]",
+  "[ 17/16 → 9/8 | note:G8 ]",
+  "[ 9/8 → 19/16 | note:Ab3 ]",
+  "[ 19/16 → 5/4 | note:Ab5 ]",
+  "[ 5/4 → 21/16 | note:C10 ]",
+  "[ 21/16 → 11/8 | note:C7 ]",
+  "[ 11/8 → 23/16 | note:G5 ]",
+  "[ 23/16 → 3/2 | note:Ab7 ]",
+  "[ 3/2 → 25/16 | note:G6 ]",
+  "[ 25/16 → 13/8 | note:Bb6 ]",
+  "[ 13/8 → 27/16 | note:Eb9 ]",
+  "[ 27/16 → 7/4 | note:G9 ]",
+  "[ 7/4 → 29/16 | note:G7 ]",
+  "[ 29/16 → 15/8 | note:C10 ]",
+  "[ 15/8 → 31/16 | note:Eb3 ]",
+  "[ 31/16 → 2/1 | note:Ab7 ]",
+  "[ 2/1 → 33/16 | note:F6 ]",
+  "[ 33/16 → 17/8 | note:C5 ]",
+  "[ 17/8 → 35/16 | note:Ab4 ]",
+  "[ 35/16 → 9/4 | note:G5 ]",
+  "[ 9/4 → 37/16 | note:C9 ]",
+  "[ 37/16 → 19/8 | note:Eb6 ]",
+  "[ 19/8 → 39/16 | note:C9 ]",
+  "[ 39/16 → 5/2 | note:Eb9 ]",
+  "[ 5/2 → 41/16 | note:D5 ]",
+  "[ 41/16 → 21/8 | note:F5 ]",
+  "[ 21/8 → 43/16 | note:F9 ]",
+  "[ 43/16 → 11/4 | note:Bb7 ]",
+  "[ 11/4 → 45/16 | note:Ab6 ]",
+  "[ 45/16 → 23/8 | note:Bb9 ]",
+  "[ 23/8 → 47/16 | note:C8 ]",
+  "[ 47/16 → 3/1 | note:Eb5 ]",
+  "[ 3/1 → 49/16 | note:F3 ]",
+  "[ 49/16 → 25/8 | note:G4 ]",
+  "[ 25/8 → 51/16 | note:D7 ]",
+  "[ 51/16 → 13/4 | note:D4 ]",
+  "[ 13/4 → 53/16 | note:F8 ]",
+  "[ 53/16 → 27/8 | note:C7 ]",
+  "[ 27/8 → 55/16 | note:Ab5 ]",
+  "[ 55/16 → 7/2 | note:Ab3 ]",
+  "[ 7/2 → 57/16 | note:F9 ]",
+  "[ 57/16 → 29/8 | note:D8 ]",
+  "[ 29/8 → 59/16 | note:F5 ]",
+  "[ 59/16 → 15/4 | note:Eb9 ]",
+  "[ 15/4 → 61/16 | note:Bb4 ]",
+  "[ 61/16 → 31/8 | note:C6 ]",
+  "[ 31/8 → 63/16 | note:C4 ]",
+  "[ 63/16 → 4/1 | note:G8 ]",
+]
+`;
+
 exports[`runs examples > example "velocity" example index 0 1`] = `
 [
  "[ 0/1 → 1/8 | s:hh gain:0.4 velocity:0.4 ]",
@@ -16,5 +16,6 @@ export default defineConfig({
      '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress}.config.*',
      '**/shared.test.mjs',
    ],
+    setupFiles: './vitest.setup.mjs',
  },
 });
@@ -0,0 +1,7 @@
+import { afterEach } from 'vitest';
+import { useRNG } from './packages/core/signal.mjs';
+
+afterEach(() => {
+  // Avoid bleed between tests
+  useRNG('legacy');
+});
@@ -393,6 +393,8 @@ samples({
  bass: { d2: 'https://cdn.freesound.org/previews/608/608286_13074022-lq.mp3' }
 })

+useRNG('legacy')
+
 stack(
  // bells
  n("0").euclidLegato(3,8)
@@ -430,6 +432,7 @@ export const festivalOfFingers3 = `// "Festival of fingers 3"
 // @by Felix Roos

 setcps(1)
+useRNG('legacy')

 n("[-7*3],0,2,6,[8 7]")
  .echoWith(
@@ -454,6 +457,8 @@ export const meltingsubmarine = `// "Melting submarine"
 // @by Felix Roos

 samples('github:tidalcycles/dirt-samples')
+useRNG('legacy')
+
 stack(
  s("bd:5,[~ <sd:1!3 sd:1(3,4,3)>],hh27(3,4,1)") // drums
  .speed(perlin.range(.7,.9)) // random sample speed variation
@@ -602,6 +607,9 @@ export const belldub = `// "Belldub"

 samples({ bell: {b4:'https://cdn.freesound.org/previews/339/339809_5121236-lq.mp3'}})
 // "Hand Bells, B, Single.wav" by InspectorJ (www.jshaw.co.uk) of Freesound.org
+
+useRNG('legacy')
+
 stack(
  // bass
  note("[0 ~] [2 [0 2]] [4 4*2] [[4 ~] [2 ~] 0@2]".scale('g1 dorian').superimpose(x=>x.add(.02)))
@@ -638,6 +646,7 @@ export const dinofunk = `// "Dinofunk"
 // @by Felix Roos

 setcps(1)
+useRNG('legacy')

 samples({bass:'https://cdn.freesound.org/previews/614/614637_2434927-hq.mp3',
 dino:{b4:'https://cdn.freesound.org/previews/316/316403_5123851-hq.mp3'}})
@@ -666,6 +675,8 @@ export const sampleDemo = `// "Sample demo"
 // @license CC BY-NC-SA 4.0 https://creativecommons.org/licenses/by-nc-sa/4.0/
 // @by Felix Roos

+useRNG('legacy')
+
 stack(
  // percussion
  s("[woodblock:1 woodblock:2*2] snare_rim:0,gong/8,brakedrum:1(3,8),~@3 cowbell:3")
@@ -684,6 +695,8 @@ export const holyflute = `// "Holy flute"
 // @license CC BY-NC-SA 4.0 https://creativecommons.org/licenses/by-nc-sa/4.0/
 // @by Felix Roos

+useRNG('legacy')
+
 "c3 eb3(3,8) c4/2 g3*2"
 .superimpose(
  x=>x.slow(2).add(12),
@@ -699,6 +712,8 @@ export const flatrave = `// "Flatrave"
 // @license CC BY-NC-SA 4.0 https://creativecommons.org/licenses/by-nc-sa/4.0/
 // @by Felix Roos

+useRNG('legacy')
+
 stack(
  s("bd*2,~ [cp,sd]").bank('RolandTR909'),
  
@@ -727,6 +742,8 @@ export const amensister = `// "Amensister"

 samples('github:tidalcycles/dirt-samples')

+useRNG('legacy')
+
 stack(
  // amen
  n("0 1 2 3 4 5 6 7")
@@ -834,6 +851,8 @@ export const arpoon = `// "Arpoon"
 // @license CC BY-NC-SA 4.0 https://creativecommons.org/licenses/by-nc-sa/4.0/
 // @by Felix Roos

+useRNG('legacy')
+
 samples('github:tidalcycles/dirt-samples')

 n("[0,3] 2 [1,3] 2".fast(3).lastOf(4, fast(2))).clip(2)