Merge branch 'main' into vanillarepl

packages/codemirror/codemirror.mjs

@@ -293,9 +293,9 @@ export class StrudelMirror {
       console.warn('first frame could not be painted');
     }
   }
-  async evaluate() {
+  async evaluate(autostart = true) {
     this.flash();
-    await this.repl.evaluate(this.code);
+    await this.repl.evaluate(this.code, autostart);
   }
   async stop() {
     this.repl.scheduler.stop();

packages/codemirror/keybindings.mjs

@@ -1,5 +1,5 @@
 import { defaultKeymap } from '@codemirror/commands';
-import { Prec } from '@codemirror/state';
+import { Prec, EditorState } from '@codemirror/state';
 import { keymap, ViewPlugin } from '@codemirror/view';
 // import { searchKeymap } from '@codemirror/search';
 import { emacs } from '@replit/codemirror-emacs';
@@ -133,5 +133,9 @@ const keymaps = {
 
 export function keybindings(name) {
   const active = keymaps[name];
-  return [active ? Prec.high(active()) : []];
+  const extensions = active ? [Prec.high(active())] : [];
+  if (name === 'vim') {
+    extensions.push(EditorState.allowMultipleSelections.of(true));
+  }
+  return extensions;
 }

packages/core/bench/signal.bench.mjs

@@ -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);

packages/core/controls.mjs

@@ -72,6 +72,27 @@ export function registerControl(names, ...aliases) {
   return bag;
 }
 
+export function registerMultiControl(names, maxControls, ...aliases) {
+  names = Array.isArray(names) ? names : [names];
+  let bag = {};
+  for (let i = 1; i <= maxControls; i++) {
+    let theseAliases = [...aliases];
+    let theseNames = [...names];
+    if (i === 1) {
+      // adds e.g. fm1 as an alias for fm
+      const aliases1 = theseAliases.map((a) => `${a}1`);
+      const names1 = theseNames.map((n) => `${n}1`);
+      theseAliases = theseAliases.concat(aliases1).concat(names1);
+    } else {
+      theseAliases = theseAliases.map((a) => `${a}${i}`);
+      theseNames = theseNames.map((n) => `${n}${i}`);
+    }
+    const subBag = registerControl(theseNames, ...theseAliases);
+    bag = { ...bag, ...subBag };
+  }
+  return bag;
+}
+
 /**
  * Select a sound / sample by name. When using mininotation, you can also optionally supply 'n' and 'gain' parameters
  * separated by ':'.
@@ -380,12 +401,13 @@ export const { accelerate } = registerControl('accelerate');
  * Sets the velocity from 0 to 1. Is multiplied together with gain.
  *
  * @name velocity
+ * @synonyms vel
  * @example
  * s("hh*8")
  * .gain(".4!2 1 .4!2 1 .4 1")
  * .velocity(".4 1")
  */
-export const { velocity } = registerControl('velocity');
+export const { velocity, vel } = registerControl('velocity', 'vel');
 /**
  * Controls the gain by an exponential amount.
  *
@@ -435,6 +457,9 @@ export const { attack, att } = registerControl('attack', 'att');
  * Whole numbers and simple ratios sound more natural,
  * while decimal numbers and complex ratios sound metallic.
  *
+ * A number may be added afterwards to control the harmonicity of
+ * any of the 8 individual FMs (e.g. `fmh2`)
+ *
  * @name fmh
  * @param {number | Pattern} harmonicity
  * @example
@@ -444,25 +469,40 @@ export const { attack, att } = registerControl('attack', 'att');
  * ._scope()
  *
  */
-export const { fmh } = registerControl(['fmh', 'fmi'], 'fmh');
+export const { fmh, fmh1, fmh2, fmh3, fmh4, fmh5, fmh6, fmh7, fmh8 } = registerMultiControl(['fmh', 'fmi'], 8, 'fmh');
+
 /**
  * Sets the Frequency Modulation of the synth.
  * Controls the modulation index, which defines the brightness of the sound.
  *
- * @name fm
+ * A number may be added afterwards to control the modulation index of
+ * any of the 8 individual FMs (e.g. `fm3`). Also, FMs may be routed into
+ * each other with matrix commands like `fm13`, which would send `fm1` back into
+ * `fm3`
+ *
+ * @name fmi
  * @param {number | Pattern} brightness modulation index
- * @synonyms fmi
+ * @synonyms fm
  * @example
  * note("c e g b g e")
  * .fm("<0 1 2 8 32>")
  * ._scope()
+ * @example
+ * s("sine").note("F1").seg(8)
+ *  .fm(4).fm2(rand.mul(4)).fm3(saw.mul(8).slow(8))
+ *  .fmh(1.06).fmh2(10).fmh3(0.1)
  *
  */
-export const { fmi, fm } = registerControl(['fmi', 'fmh'], 'fm');
+export const { fmi, fmi1, fmi2, fmi3, fmi4, fmi5, fmi6, fmi7, fmi8, fm, fm1, fm2, fm3, fm4, fm5, fm6, fm7, fm8 } =
+  registerMultiControl(['fmi', 'fmh'], 8, 'fm');
+
 // fm envelope
 /**
  * Ramp type of fm envelope. Exp might be a bit broken..
  *
+ * A number may be added afterwards to control the envelope of
+ * any of the 8 individual FMs (e.g. `fmenv4`)
+ *
  * @name fmenv
  * @param {number | Pattern} type lin | exp
  * @example
@@ -474,11 +514,19 @@ export const { fmi, fm } = registerControl(['fmi', 'fmh'], 'fm');
  * ._scope()
  *
  */
-export const { fmenv } = registerControl('fmenv');
+export const { fmenv, fmenv1, fmenv2, fmenv3, fmenv4, fmenv5, fmenv6, fmenv7, fmenv8 } = registerMultiControl(
+  'fmenv',
+  8,
+);
+
 /**
  * Attack time for the FM envelope: time it takes to reach maximum modulation
  *
+ * A number may be added afterwards to control the attack of the envelope of
+ * any of the 8 individual FMs (e.g. `fmatt5`)
+ *
  * @name fmattack
+ * @synonyms fmatt
  * @param {number | Pattern} time attack time
  * @example
  * note("c e g b g e")
@@ -487,11 +535,33 @@ export const { fmenv } = registerControl('fmenv');
  * ._scope()
  *
  */
-export const { fmattack } = registerControl('fmattack');
+export const {
+  fmattack,
+  fmattack1,
+  fmattack2,
+  fmattack3,
+  fmattack4,
+  fmattack5,
+  fmattack6,
+  fmattack7,
+  fmattack8,
+  fmatt,
+  fmatt1,
+  fmatt2,
+  fmatt3,
+  fmatt4,
+  fmatt5,
+  fmatt6,
+  fmatt7,
+  fmatt8,
+} = registerMultiControl('fmattack', 8, 'fmatt');
 
 /**
  * Waveform of the fm modulator
  *
+ * A number may be added afterwards to control the waveform
+ * any of the 8 individual FMs (e.g. `fmwave6`)
+ *
  * @name fmwave
  * @param {number | Pattern} wave waveform
  * @example
@@ -500,12 +570,19 @@ export const { fmattack } = registerControl('fmattack');
  * n("0 1 2 3".fast(4)).chord("<Dm Am F G>").voicing().s("sawtooth").fmwave("brown").fm(.6)
  *
  */
-export const { fmwave } = registerControl('fmwave');
+export const { fmwave, fmwave1, fmwave2, fmwave3, fmwave4, fmwave5, fmwave6, fmwave7, fmwave8 } = registerMultiControl(
+  'fmwave',
+  8,
+);
 
 /**
  * Decay time for the FM envelope: seconds until the sustain level is reached after the attack phase.
  *
+ * A number may be added afterwards to control the decay of the envelope of
+ * any of the 8 individual FMs (e.g. `fmdec6`)
+ *
  * @name fmdecay
+ * @synonyms fmdec
  * @param {number | Pattern} time decay time
  * @example
  * note("c e g b g e")
@@ -515,11 +592,35 @@ export const { fmwave } = registerControl('fmwave');
  * ._scope()
  *
  */
-export const { fmdecay } = registerControl('fmdecay');
+export const {
+  fmdecay,
+  fmdecay1,
+  fmdecay2,
+  fmdecay3,
+  fmdecay4,
+  fmdecay5,
+  fmdecay6,
+  fmdecay7,
+  fmdecay8,
+  fmdec,
+  fmdec1,
+  fmdec2,
+  fmdec3,
+  fmdec4,
+  fmdec5,
+  fmdec6,
+  fmdec7,
+  fmdec8,
+} = registerMultiControl('fmdecay', 8, 'fmdec');
+
 /**
  * Sustain level for the FM envelope: how much modulation is applied after the decay phase
  *
+ * A number may be added afterwards to control the sustain of the envelope of
+ * any of the 8 individual FMs (e.g. `fmsus7`)
+ *
  * @name fmsustain
+ * @synonyms fmsus
  * @param {number | Pattern} level sustain level
  * @example
  * note("c e g b g e")
@@ -529,10 +630,69 @@ export const { fmdecay } = registerControl('fmdecay');
  * ._scope()
  *
  */
-export const { fmsustain } = registerControl('fmsustain');
-// these are not really useful... skipping for now
-export const { fmrelease } = registerControl('fmrelease');
-export const { fmvelocity } = registerControl('fmvelocity');
+export const {
+  fmsustain,
+  fmsustain1,
+  fmsustain2,
+  fmsustain3,
+  fmsustain4,
+  fmsustain5,
+  fmsustain6,
+  fmsustain7,
+  fmsustain8,
+  fmsus,
+  fmsus1,
+  fmsus2,
+  fmsus3,
+  fmsus4,
+  fmsus5,
+  fmsus6,
+  fmsus7,
+  fmsus8,
+} = registerMultiControl('fmsustain', 8, 'fmsus');
+
+/**
+ * Release time for the FM envelope: how much modulation is applied after the note is released
+ *
+ * A number may be added afterwards to control the release of the envelope of
+ * any of the 8 individual FMs (e.g. `fmrel8`)
+ *
+ * @name fmrelease
+ * @synonyms fmrel
+ * @param {number | Pattern} time release time
+ *
+ */
+export const {
+  fmrelease,
+  fmrelease1,
+  fmrelease2,
+  fmrelease3,
+  fmrelease4,
+  fmrelease5,
+  fmrelease6,
+  fmrelease7,
+  fmrelease8,
+  fmrel,
+  fmrel1,
+  fmrel2,
+  fmrel3,
+  fmrel4,
+  fmrel5,
+  fmrel6,
+  fmrel7,
+  fmrel8,
+} = registerMultiControl('fmrelease', 8, 'fmrel');
+
+// FM Matrix
+// Note: we do not declare top-level exports here since it would add
+// ~162 more explicit exports. This is likely fine as the most common use-case would be to at least
+// declare one other FM prior to utilizing the matrix functionality, but if we ever decide we need it,
+// TODO to add it explicitly / go with the globalThis approach
+for (let i = 0; i <= 8; i++) {
+  for (let j = 0; j <= 8; j++) {
+    registerControl(`fmi${i}${j}`, `fm${i}${j}`);
+  }
+}
 
 /**
  * Select the sound bank to use. To be used together with `s`. The bank name (+ "_") will be prepended to the value of `s`.
@@ -1294,6 +1454,8 @@ export const { fanchor } = registerControl('fanchor');
  *
  * @name lprate
  * @param {number | Pattern} rate rate in hertz
+ * @example
+ * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).lprate("<4 8 2 1>")
  */
 export const { lprate } = registerControl('lprate');
 
@@ -1302,6 +1464,8 @@ export const { lprate } = registerControl('lprate');
  *
  * @name lpsync
  * @param {number | Pattern} rate rate in cycles
+ * @example
+ * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).lpsync("<4 8 2 1>")
  */
 export const { lpsync } = registerControl('lpsync');
 
@@ -1310,8 +1474,22 @@ export const { lpsync } = registerControl('lpsync');
  *
  * @name lpdepth
  * @param {number | Pattern} depth depth of modulation
+ * @example
+ * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).lpdepth("<1 .5 1.8 0>")
  */
+
 export const { lpdepth } = registerControl('lpdepth');
+/**
+ * Depth of the LFO for the lowpass filter, in HZ
+ *
+ * @name lpdepthfrequency
+ * @synonyms lpdepthfreq
+ * @param {number | Pattern} depth depth of modulation
+ * @example
+ * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).lpdepthfrequency("<200 500 100 0>")
+ */
+
+export const { lpdepthfrequency, lpdepthfreq } = registerControl('lpdepthfrequency', 'lpdepthfreq');
 
 /**
  * Shape of the LFO for the lowpass filter
@@ -1361,6 +1539,18 @@ export const { bpsync } = registerControl('bpsync');
  */
 export const { bpdepth } = registerControl('bpdepth');
 
+/**
+ * Depth of the LFO for the bandpass filter, in HZ
+ *
+ * @name bpdepthfrequency
+ * @synonyms bpdepthfreq
+ * @param {number | Pattern} depth depth of modulation
+ * @example
+ * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).bpdepthfrequency("<200 500 100 0>")
+ */
+
+export const { bpdepthfrequency, bpdepthfreq } = registerControl('bpdepthfrequency', 'bpdepthfreq');
+
 /**
  * Shape of the LFO for the bandpass filter
  *
@@ -1409,6 +1599,18 @@ export const { hpsync } = registerControl('hpsync');
  */
 export const { hpdepth } = registerControl('hpdepth');
 
+/**
+ * Depth of the LFO for the hipass filter, in hz
+ *
+ * @name hpdepthfrequency
+ * @synonyms hpdepthfreq
+ * @param {number | Pattern} depth depth of modulation
+ * @example
+ * note("<c c c# c c c4>*16").s("sawtooth").lpf(600).hpdepthfrequency("<200 500 100 0>")
+ */
+
+export const { hpdepthfrequency, hpdepthfreq } = registerControl('hpdepthfrequency', 'hpdepthfreq');
+
 /**
  * Shape of the LFO for the highpass filter
  *
@@ -1820,12 +2022,12 @@ export const { nudge } = registerControl('nudge');
  * Sets the default octave of a synth.
  *
  * @name octave
+ * @synonyms oct
  * @param {number | Pattern} octave octave number
  * @example
- * n("0,4,7").s('supersquare').octave("<3 4 5 6>").osc()
- * @superDirtOnly
+ * n("0,4,7").scale("F:minor").s('supersaw').octave("<0 1 2 3>")
  */
-export const { octave } = registerControl('octave');
+export const { octave, oct } = registerControl('octave', 'oct');
 
 // ['ophatdecay'],
 // TODO: example
@@ -1833,6 +2035,7 @@ export const { octave } = registerControl('octave');
  * An `orbit` is a global parameter context for patterns. Patterns with the same orbit will share the same global effects.
  *
  * @name orbit
+ * @synonyms o
  * @param {number | Pattern} number
  * @example
  * stack(
@@ -1840,7 +2043,7 @@ export const { octave } = registerControl('octave');
  *   s("~ sd ~ sd").delay(.5).delaytime(.125).orbit(2)
  * )
  */
-export const { orbit } = registerControl('orbit');
+export const { orbit } = registerControl('orbit', 'o');
 // TODO: what is this? not found in tidal doc Answer: gain is limited to maximum of 2. This allows you to go over that
 export const { overgain } = registerControl('overgain');
 // TODO: what is this? not found in tidal doc. Similar to above, but limited to 1
@@ -2550,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);
   });
 });
 
@@ -2583,3 +2791,17 @@ export const scrub = register(
   },
   false,
 );
+
+/**
+ * Transient shaper. Gives independent control over the emphasis on transients
+ * and sustains
+ *
+ * @name transient
+ * @param {number | Pattern} attack Emphasis on transients; between -1 (deaccentuate) and 1 (accentuate)
+ * @param {number | Pattern} sustain Emphasis on the sustains; between -1 (deaccentuate) and 1 (accentuate)
+ * @example
+ * s("bd").transient("<-1 -0.5 0 0.5 1>")
+ * @example
+ * s("hh*16").bank("tr909").transient("<-1:1 1:-1>")
+ */
+export const { transient } = registerControl(['transient', 'transsustain']);

packages/core/impure.mjs

@@ -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,
+);

packages/core/index.mjs

@@ -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';

packages/core/pattern.mjs

@@ -25,7 +25,7 @@ import {
   stringifyValues,
 } from './util.mjs';
 import drawLine from './drawLine.mjs';
-import { logger } from './logger.mjs';
+import { errorLogger, logger } from './logger.mjs';
 
 let stringParser;
 
@@ -414,7 +414,7 @@ export class Pattern {
     try {
       return this.query(new State(new TimeSpan(begin, end), controls));
     } catch (err) {
-      logger(`[query]: ${err.message}`, 'error');
+      errorLogger(err, 'query');
       return [];
     }
   }
@@ -574,7 +574,8 @@ export class Pattern {
    * Returns a new Pattern, which only returns haps that meet the given test.
    * @param {Function} hap_test - a function which returns false for haps to be removed from the pattern
    * @returns Pattern
-   * @noAutocomplete
+   * @example
+   * s("bd*8").velocity(rand).filterHaps((h) => (h.whole.begin % 1) < h.value.velocity)
    */
   filterHaps(hap_test) {
     return new Pattern((state) => this.query(state).filter(hap_test));
@@ -585,7 +586,11 @@ export class Pattern {
    * inside haps.
    * @param {Function} value_test
    * @returns Pattern
-   * @noAutocomplete
+   * @example
+   * const drums = s("bd sd bd sd")
+   * kick: drums.filterValues((v) => v.s === 'bd').duck(2)
+   * snare: drums.filterValues((v) => v.s === 'sd')
+   * bass: s("saw!4").note("G#1").lpf(80).lpenv(4).orbit(2)
    */
   filterValues(value_test) {
     return new Pattern((state) => this.query(state).filter((hap) => value_test(hap.value))).setSteps(this._steps);
@@ -1587,7 +1592,13 @@ export const func = curry((a, b) => reify(b).func(a));
  *
  * @param {string | string[]} name name of the function, or an array of names to be used as synonyms
  * @param {function} func function with 1 or more params, where last is the current pattern
- * @noAutocomplete
+ * @param {bool} patternify defaults to true; if set to false, you will have more control over the arguments to `func` as they will be
+ *   in their raw form and it will be up to you to patternify them and/or query them for values
+ * @example
+ * const vlpf = register('vlpf', (freq, pat) => {
+ *   return pat.fmap((v) => ({...v, cutoff: freq * (v.velocity ?? 1) }));
+ * })
+ * s("saw").seg(8).velocity(rand).vlpf(800)
  *
  */
 export function register(name, func, patternify = true, preserveSteps = false, join = (x) => x.innerJoin()) {
@@ -2234,7 +2245,7 @@ export const brak = register('brak', function (pat) {
 });
 
 /**
- * Reverse all haps in a pattern
+ * Reverse all cycles in a pattern. See also `revv` for reversing a whole pattern.
  *
  * @name rev
  * @memberof Pattern
@@ -2266,6 +2277,23 @@ export const rev = register(
   true,
 );
 
+/**
+ * Reverse a whole pattern. See also `rev` for reversing each cycle.
+ *
+ * @name revv
+ * @memberof Pattern
+ * @returns Pattern
+ * @example
+ * // This is the same as `<[g e] [d c]>`. If `rev()` is used, you get
+ * // the same as `<[d c] [g e]>`, where each cycle reverses, but the order of
+ * // cycles stays the same.
+ * note("<[c d] [e g]>").revv()
+ */
+export const revv = register('revv', function (pat) {
+  const negateSpan = (span) => new TimeSpan(Fraction(0).sub(span.end), Fraction(0).sub(span.begin));
+  return pat.withQuerySpan(negateSpan).withHapSpan(negateSpan);
+});
+
 /** Like press, but allows you to specify the amount by which each
  * event is shifted. pressBy(0.5) is the same as press, while
  * pressBy(1/3) shifts each event by a third of its timespan.
@@ -2659,8 +2687,13 @@ export const hsl = register('hsl', (h, s, l, pat) => {
 /**
  * Tags each Hap with an identifier. Good for filtering. The function populates Hap.context.tags (Array).
  * @name tag
- * @noAutocomplete
  * @param {string} tag anything unique
+ * @example
+ * s("saw!16").note("F1")
+ *   .lpf(tri.range(40, 80).slow(4)).lpenv(5).lpq(4).lpd(0.15)
+ *   .when(rand.late(0.1).gte(0.5), x => x.transpose("12").tag('altered'))
+ *   .when(rand.late(0.2).gte(0.5), x => x.s("square").tag('altered'))
+ *   .when("<0 1>", x => x.filter((hap) => hap.hasTag('altered')))
  */
 Pattern.prototype.tag = function (tag) {
   return this.withContext((ctx) => ({ ...ctx, tags: (ctx.tags || []).concat([tag]) }));
@@ -2671,15 +2704,16 @@ Pattern.prototype.tag = function (tag) {
  * @name filter
  * @param {Function} test function to test Hap
  * @example
- * s("hh!7 oh").filter(hap => hap.value.s==='hh')
+ * s("hh!7 oh").filter(hap => hap.value.s === 'hh')
  */
 export const filter = register('filter', (test, pat) => pat.withHaps((haps) => haps.filter(test)));
 
 /**
  * Filters haps by their begin time
  * @name filterWhen
- * @noAutocomplete
  * @param {Function} test function to test Hap.whole.begin
+ * @example
+ * oneCycle: s("bd*4").filterWhen((t) => t < 1)
  */
 export const filterWhen = register('filterWhen', (test, pat) => pat.filter((h) => test(h.whole.begin)));
 

packages/core/repl.mjs

@@ -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,
@@ -152,9 +156,9 @@ export function repl({
         // allows muting a pattern x with x_ or _x
         return silence;
       }
-      if (id === '$') {
+      if (id.includes('$')) {
         // allows adding anonymous patterns with $:
-        id = `$${anonymousIndex}`;
+        id = `${id}${anonymousIndex}`;
         anonymousIndex++;
       }
       pPatterns[id] = this;
@@ -215,8 +219,19 @@ export function repl({
       let { pattern, meta } = await _evaluate(code, transpiler, transpilerOptions);
       if (Object.keys(pPatterns).length) {
         let patterns = [];
+        let soloActive = false;
         for (const [key, value] of Object.entries(pPatterns)) {
-          patterns.push(value.withState((state) => state.setControls({ id: key })));
+          // handle soloed patterns ex: S$: s("bd!4")
+          const isSolod = key.length > 1 && key.startsWith('S');
+          if (isSolod && soloActive === false) {
+            // first time we see a soloed pattern, clear existing patterns
+            patterns = [];
+            soloActive = true;
+          }
+          if (!soloActive || (soloActive && isSolod)) {
+            const valWithState = value.withState((state) => state.setControls({ id: key }));
+            patterns.push(valWithState);
+          }
         }
         if (eachTransform) {
           // Explicit lambda so only element (not index and array) are passed
@@ -227,14 +242,13 @@ export function repl({
         pattern = eachTransform(pattern);
       }
       if (allTransforms.length) {
-        for (let i in allTransforms) {
-          pattern = allTransforms[i](pattern);
+        for (const transform of allTransforms) {
+          pattern = transform(pattern);
         }
       }
 
       if (!isPattern(pattern)) {
-        const message = `got "${typeof evaluated}" instead of pattern`;
-        throw new Error(message + (typeof evaluated === 'function' ? ', did you forget to call a function?' : '.'));
+        pattern = silence;
       }
       logger(`[eval] code updated`);
       pattern = await setPattern(pattern, autostart);

packages/core/signal.mjs

@@ -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
  */
@@ -524,7 +614,7 @@ export const wchoose = (...pairs) => wchooseWith(rand, ...pairs);
  * @example
  * wchooseCycles(["bd",10], ["hh",1], ["sd",1]).s().fast(8)
  * @example
- * wchooseCycles(["bd bd bd",5], ["hh hh hh",3], ["sd sd sd",1]).fast(4).s()
+ * wchooseCycles(["c c c",5], ["a a a",3], ["f f f",1]).fast(4).note()
  * @example
  * // The probability can itself be a pattern
  * wchooseCycles(["bd(3,8)","<5 0>"], ["hh hh hh",3]).fast(4).s()
@@ -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)];
+});

packages/core/test/pattern.test.mjs

@@ -586,6 +586,18 @@ describe('Pattern', () => {
           .map((a) => a.value),
       ).toStrictEqual(['c', 'b', 'a']);
     });
+    it('Does not reverse the order of cycles', () => {
+      expect(fastcat('a', 'b', 'c', 'd').slow(2).rev().fast(2).sortHapsByPart().firstCycle()).toStrictEqual(
+        fastcat('b', 'a', 'd', 'c').firstCycle(),
+      );
+    });
+  });
+  describe('revv()', () => {
+    it('Does reverse the order of cycles', () => {
+      expect(fastcat('a', 'b', 'c', 'd').slow(2).revv().fast(2).sortHapsByPart().firstCycle()).toStrictEqual(
+        fastcat('d', 'c', 'b', 'a').firstCycle(),
+      );
+    });
   });
   describe('sequence()', () => {
     it('Can work like fastcat', () => {
@@ -728,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(

packages/core/test/signal.test.mjs

@@ -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))),
+    );
+  });
+});

packages/hydra/hydra.mjs

@@ -35,6 +35,7 @@ export async function initHydra(options = {}) {
       hydra.synth.s0.init({ src: canvas });
     }
   }
+  return hydra;
 }
 
 export function clearHydra() {

packages/midi/midi.mjs

@@ -479,14 +479,24 @@ Pattern.prototype.midi = function (midiport, options = {}) {
 
 let listeners = {};
 const refs = {};
+const refsByChan = {};
 
 /**
  * MIDI input: Opens a MIDI input port to receive MIDI control change messages.
+ *
+ * The output is a function that accepts a midi cc value to query as well as (optionally) a midi channel
  * @param {string | number} input MIDI device name or index defaulting to 0
- * @returns {Function}
+ * @returns {function(number, number=): Pattern} A function from (cc, channel?) to a pattern.
+ *   When queried, the pattern will produces the most recently received midi value (normalized to 0 to 1)
+ *   that came through that cc number (and channel, if provided)
  * @example
- * let cc = await midin('IAC Driver Bus 1')
+ * const cc = await midin('IAC Driver Bus 1')
  * note("c a f e").lpf(cc(0).range(0, 1000)).lpq(cc(1).range(0, 10)).sound("sawtooth")
+ * @example
+ * const allCC = await midin('IAC Driver Bus 1')
+ * const cc = (ccNum) => allCC(ccNum, 2) // just channel 2
+ * note("c a f e").s("saw")
+ *   .when(cc(0).gt(0), x => x.postgain(0))
  */
 export async function midin(input) {
   if (isPattern(input)) {
@@ -511,17 +521,24 @@ export async function midin(input) {
       }`,
     );
   }
-  // ensure refs for this input are initialized
-  if (!refs[input]) {
-    refs[input] = {};
-  }
-  const cc = (cc) => ref(() => refs[input][cc] || 0);
+  refs[input] ??= {};
+  refsByChan[input] ??= {};
+  const cc = (cc, chan) => {
+    if (chan !== undefined) {
+      return ref(() => refsByChan[input][cc]?.[chan] || 0);
+    }
+    return ref(() => refs[input][cc] || 0);
+  };
 
   listeners[input] && device.removeListener('midimessage', listeners[input]);
   listeners[input] = (e) => {
-    const cc = e.dataBytes[0];
+    const ccNum = e.dataBytes[0];
     const v = e.dataBytes[1];
-    refs[input] && (refs[input][cc] = v / 127);
+    const chan = e.message.channel;
+    const scaled = v / 127;
+    refsByChan[input][ccNum] ??= {};
+    refsByChan[input][ccNum][chan] = scaled;
+    refs[input][ccNum] = scaled;
   };
   device.addListener('midimessage', listeners[input]);
   return cc;

packages/sampler/sample-server.mjs

@@ -9,6 +9,7 @@ import readline from 'readline';
 import os from 'os';
 
 const LOG = !!process.env.LOG || false;
+const PORT = process.env.PORT || 5432;
 const VALID_AUDIO_EXTENSIONS = ['wav', 'mp3', 'ogg'];
 
 const isAudioFile = (f) => {
@@ -54,7 +55,6 @@ async function getBanks(directory, flat = false) {
     banks[bank].push(subDir);
     return subDir;
   });
-  banks._base = `http://localhost:5432`;
   return { banks, files };
 }
 
@@ -134,8 +134,6 @@ const server = http.createServer(async (req, res) => {
   readStream.pipe(res);
 });
 
-// eslint-disable-next-line
-const PORT = process.env.PORT || 5432;
 const IP_ADDRESS = '0.0.0.0';
 let IP;
 const networkInterfaces = os.networkInterfaces();

packages/soundfonts/fontloader.mjs

@@ -6,6 +6,8 @@ import {
   getADSRValues,
   getPitchEnvelope,
   getVibratoOscillator,
+  onceEnded,
+  releaseAudioNode,
 } from '@strudel/webaudio';
 import gm from './gm.mjs';
 
@@ -170,12 +172,11 @@ export function registerSoundfonts() {
 
         bufferSource.stop(envEnd);
         const stop = (releaseTime) => {};
-        bufferSource.onended = () => {
-          bufferSource.disconnect();
-          vibratoOscillator?.stop();
-          node.disconnect();
+        onceEnded(bufferSource, () => {
+          releaseAudioNode(bufferSource);
+          releaseAudioNode(vibratoOscillator);
           onended();
-        };
+        });
         return { node, stop };
       },
       { type: 'soundfont', prebake: true, fonts },

packages/superdough/audioContext.mjs

@@ -5,6 +5,11 @@ export const setDefaultAudioContext = () => {
   return audioContext;
 };
 
+export const setAudioContext = (context) => {
+  audioContext = context;
+  return audioContext;
+};
+
 export const getAudioContext = () => {
   if (!audioContext) {
     return setDefaultAudioContext();

packages/superdough/feedbackdelay.mjs

@@ -25,7 +25,7 @@ if (typeof DelayNode !== 'undefined') {
     }
   }
 
-  AudioContext.prototype.createFeedbackDelay = function (wet, time, feedback) {
+  BaseAudioContext.prototype.createFeedbackDelay = function (wet, time, feedback) {
     return new FeedbackDelayNode(this, wet, time, feedback);
   };
 }

packages/superdough/helpers.mjs

@@ -1,7 +1,7 @@
 import { getAudioContext } from './audioContext.mjs';
-import { clamp, nanFallback, midiToFreq, noteToMidi } from './util.mjs';
-import { getNoiseBuffer } from './noise.mjs';
 import { logger } from './logger.mjs';
+import { getNoiseBuffer } from './noise.mjs';
+import { clamp, nanFallback, midiToFreq, noteToMidi } from './util.mjs';
 
 export const noises = ['pink', 'white', 'brown', 'crackle'];
 
@@ -42,6 +42,7 @@ export const getParamADSR = (
   decay,
   sustain,
   release,
+  // min = value at start of attack, max = value at end of attack; it is possible that max < min
   min,
   max,
   begin,
@@ -59,17 +60,15 @@ export const getParamADSR = (
     max = max === 0 ? 0.001 : max;
   }
   const range = max - min;
-  const peak = max;
   const sustainVal = min + sustain * range;
   const duration = end - begin;
 
   const envValAtTime = (time) => {
     let val;
     if (attack > time) {
-      let slope = getSlope(min, peak, 0, attack);
-      val = time * slope + (min > peak ? min : 0);
+      val = time * getSlope(min, max, 0, attack) + min;
     } else {
-      val = (time - attack) * getSlope(peak, sustainVal, 0, decay) + peak;
+      val = (time - attack) * getSlope(max, sustainVal, 0, decay) + max;
     }
     if (curve === 'exponential') {
       val = val || 0.001;
@@ -189,10 +188,9 @@ 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) {
+export function createFilter(context, start, end, params, cps, cycle) {
   let {
     frequency,
     anchor,
@@ -202,12 +200,14 @@ export function createFilter(context, start, end, params, cps) {
     q = 1,
     drive = 0.69,
     depth,
+    depthfrequency,
     dcoffset = -0.5,
     skew,
     shape,
     rate,
     sync,
   } = params;
+
   let frequencyParam, filter;
   if (model === 'ladder') {
     filter = getWorklet(context, 'ladder-processor', { frequency, q, drive });
@@ -238,9 +238,27 @@ export function createFilter(context, start, end, params, cps) {
   if (sync != null) {
     rate = cps * sync;
   }
-  const lfoValues = { depth, dcoffset, skew, shape, frequency: rate };
-  getParamLfo(context, frequencyParam, start, end, lfoValues);
-  return filter;
+  const hasLFO = [depth, depthfrequency, skew, shape, rate].some((v) => v !== undefined);
+  let lfo;
+  if (hasLFO) {
+    depth = depth ?? 1;
+    const time = cycle / cps;
+    const modDepth = depthfrequency ?? (depth ?? 1) * frequency;
+    const lfoValues = {
+      depth: modDepth,
+      dcoffset,
+      skew,
+      shape,
+      frequency: rate ?? cps,
+      min: -frequency + 30,
+      max: 20000 - frequency,
+      time,
+      curve: 1,
+    };
+    lfo = getParamLfo(context, frequencyParam, start, end, lfoValues);
+  }
+
+  return { filter, lfo };
 }
 
 // stays 1 until .5, then fades out
@@ -262,7 +280,18 @@ export function drywet(dry, wet, wetAmount = 0) {
   let mix = ac.createGain();
   dry_gain.connect(mix);
   wet_gain.connect(mix);
-  return mix;
+  return {
+    node: 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);
+    },
+  };
 }
 
 let curves = ['linear', 'exponential'];
@@ -297,6 +326,10 @@ export function getVibratoOscillator(param, value, t) {
     gain.gain.value = vibmod * 100;
     vibratoOscillator.connect(gain);
     gain.connect(param);
+    onceEnded(vibratoOscillator, () => {
+      releaseAudioNode(gain);
+      releaseAudioNode(vibratoOscillator);
+    });
     vibratoOscillator.start(t);
     return vibratoOscillator;
   }
@@ -318,25 +351,17 @@ export function webAudioTimeout(audioContext, onComplete, startTime, stopTime) {
   constantNode.connect(zeroGain);
 
   // Schedule the `onComplete` callback to occur at `stopTime`
-  constantNode.onended = () => {
-    // Ensure garbage collection
-    try {
-      zeroGain.disconnect();
-    } catch {
-      // pass
-    }
-    try {
-      constantNode.disconnect();
-    } catch {
-      // pass
-    }
+  onceEnded(constantNode, () => {
+    releaseAudioNode(zeroGain);
+    releaseAudioNode(constantNode);
     onComplete();
-  };
+  });
   constantNode.start(startTime);
   constantNode.stop(stopTime);
   return constantNode;
 }
-const mod = (freq, range = 1, type = 'sine') => {
+
+const mod = (freq, type = 'sine') => {
   const ctx = getAudioContext();
   let osc;
   if (noises.includes(type)) {
@@ -348,64 +373,89 @@ const mod = (freq, range = 1, type = 'sine') => {
     osc.type = type;
     osc.frequency.value = freq;
   }
-
   osc.start();
-  const g = new GainNode(ctx, { gain: range });
-  osc.connect(g); // -range, range
-  return { node: g, stop: (t) => osc.stop(t) };
+  return osc;
 };
-const fm = (frequencyparam, harmonicityRatio, modulationIndex, wave = 'sine') => {
+
+const fm = (frequencyparam, harmonicityRatio, wave = 'sine') => {
   const carrfreq = frequencyparam.value;
   const modfreq = carrfreq * harmonicityRatio;
-  const modgain = modfreq * modulationIndex;
-  return mod(modfreq, modgain, wave);
+  return { osc: mod(modfreq, wave), freq: modfreq };
 };
+
 export function applyFM(param, value, begin) {
-  const {
-    fmh: fmHarmonicity = 1,
-    fmi: fmModulationIndex,
-    fmenv: fmEnvelopeType = 'exp',
-    fmattack: fmAttack,
-    fmdecay: fmDecay,
-    fmsustain: fmSustain,
-    fmrelease: fmRelease,
-    fmvelocity: fmVelocity,
-    fmwave: fmWaveform = 'sine',
-    duration,
-  } = value;
-  let modulator;
-  let stop = () => {};
-
-  if (fmModulationIndex) {
-    const ac = getAudioContext();
-    const envGain = ac.createGain();
-    const fmmod = fm(param, fmHarmonicity, fmModulationIndex, fmWaveform);
-
-    modulator = fmmod.node;
-    stop = fmmod.stop;
-    if (![fmAttack, fmDecay, fmSustain, fmRelease, fmVelocity].some((v) => v !== undefined)) {
-      // no envelope by default
-      modulator.connect(param);
-    } else {
-      const [attack, decay, sustain, release] = getADSRValues([fmAttack, fmDecay, fmSustain, fmRelease]);
-      const holdEnd = begin + duration;
-      getParamADSR(
-        envGain.gain,
-        attack,
-        decay,
-        sustain,
-        release,
-        0,
-        1,
-        begin,
-        holdEnd,
-        fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
-      );
-      modulator.connect(envGain);
-      envGain.connect(param);
+  const ac = getAudioContext();
+  const toStop = []; // fm oscillators we will expose `stop` for
+  const fms = {};
+  // Matrix
+  for (let i = 1; i <= 8; i++) {
+    for (let j = 0; j <= 8; j++) {
+      let control;
+      if (i === j + 1) {
+        // Standard fm3 -> fm2 -> fm1 -> param usage
+        const iS = i === 1 ? '' : i;
+        control = `fmi${iS}`;
+      } else {
+        control = `fmi${i}${j}`;
+      }
+      const amt = value[control];
+      if (!amt) continue;
+      let io = [];
+      for (let [isMod, idx] of [
+        [true, i], // source
+        [false, j], // target
+      ]) {
+        if (idx === 0) {
+          io.push(param);
+          continue;
+        }
+        if (!fms[idx]) {
+          const idxS = idx === 1 ? '' : idx;
+          const { osc, freq } = fm(param, value[`fmh${idxS}`] ?? 1, value[`fmwave${idxS}`] ?? 'sine');
+          toStop.push(osc);
+          const toCleanup = [osc]; // nodes we want to cleanup after oscillator `stop`
+          const adsr = ['attack', 'decay', 'sustain', 'release'].map((s) => value[`fm${s}${idxS}`]);
+          let output = osc;
+          if (adsr.some((v) => v !== undefined)) {
+            const envGain = ac.createGain();
+            const [attack, decay, sustain, release] = getADSRValues(adsr);
+            const holdEnd = begin + value.duration;
+            const fmEnvelopeType = value[`fmenv${idxS}`] ?? 'exp';
+            getParamADSR(
+              envGain.gain,
+              attack,
+              decay,
+              sustain,
+              release,
+              0,
+              1,
+              begin,
+              holdEnd,
+              fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
+            );
+            toCleanup.push(envGain);
+            output = osc.connect(envGain);
+          }
+          fms[idx] = { input: osc.frequency, output, freq, osc, toCleanup };
+        }
+        const { input, output, freq, osc, toCleanup } = fms[idx];
+        const g = gainNode(amt * freq);
+        io.push(isMod ? output.connect(g) : input);
+        cleanupOnEnd(osc, [...toCleanup, g]);
+      }
+      if (!io[1]) {
+        logger(
+          `[superdough] control ${control} failed to connect FM ${i} to target ${j} due to missing frequency parameter (likely because fm${j} is noise)`,
+          'warning',
+        );
+        continue;
+      }
+      io[0].connect(io[1]);
     }
   }
-  return { stop };
+  return {
+    stop: (t) => toStop.forEach((m) => m?.stop(t)),
+  };
 }
 
 // Saturation curves
@@ -505,7 +555,7 @@ export const getDistortion = (distort, postgain, algorithm) => {
 };
 
 export const getFrequencyFromValue = (value, defaultNote = 36) => {
-  let { note, freq } = value;
+  let { note, freq, octave = 0 } = value;
   note = note || defaultNote;
   if (typeof note === 'string') {
     note = noteToMidi(note); // e.g. c3 => 48
@@ -514,14 +564,64 @@ export const getFrequencyFromValue = (value, defaultNote = 36) => {
   if (!freq && typeof note === 'number') {
     freq = midiToFreq(note); // + 48);
   }
-
+  freq *= Math.pow(2, octave);
   return Number(freq);
 };
 
-export const destroyAudioWorkletNode = (node) => {
-  if (node == null) {
-    return;
-  }
-  node.disconnect();
-  node.parameters.get('end')?.setValueAtTime(0, 0);
+// This helper should be used instead of the `node.onended = callback` pattern
+// It adds a mechanism to help minimize gc retention
+export const onceEnded = (node, callback) => {
+  const onended = callback;
+  node.onended = function cleanup() {
+    onended && onended();
+    this.onended = null;
+  };
+};
+
+export const releaseAudioNode = (node) => {
+  if (node == null) return;
+
+  // check we received an AudioNode
+  if (!(node instanceof AudioNode)) {
+    throw new Error('releaseAudioNode can only release an AudioNode');
+  }
+
+  // https://developer.mozilla.org/en-US/docs/Web/API/AudioNode/disconnect
+  node.disconnect();
+
+  // make sure all AudioScheduledSourceNodes are in a stopped state
+  // https://developer.mozilla.org/en-US/docs/Web/API/AudioScheduledSourceNode
+  if (node instanceof AudioScheduledSourceNode) {
+    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`,
+      );
+    }
+    try {
+      node.stop();
+    } catch (e) {
+      // At the stage, `start` was not called on the node
+      // but an `onended` callback releasing resources may exist
+      // and we want it to fire :
+      // - we force a start/stop cycle so that `onended` gets called
+      // - we `lock` the node so that no-one can start it
+      node.start(node.context.currentTime + 5); // will never happen
+      node.stop();
+    }
+  }
+
+  // https://www.w3.org/TR/webaudio-1.1/#AudioNode-actively-processing
+  // An AudioWorkletNode is actively processing when its AudioWorkletProcessor's [[callable process]]
+  // 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);
+  }
+};
+
+// Once the `anchor` node has ended, release all nodes in `toCleanup`
+export const cleanupOnEnd = (anchor, toCleanup) => {
+  onceEnded(anchor, () => toCleanup.forEach((n) => releaseAudioNode(n)));
 };

packages/superdough/noise.mjs

@@ -1,4 +1,4 @@
-import { drywet } from './helpers.mjs';
+import { drywet, onceEnded, releaseAudioNode } from './helpers.mjs';
 import { getAudioContext } from './audioContext.mjs';
 
 let noiseCache = {};
@@ -65,8 +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);
+  onceEnded(noiseOscillator.node, () => {
+    releaseAudioNode(noiseOscillator.node);
+  });
   return {
-    node: noiseMix,
+    node: noiseMix.node,
     stop: (time) => noiseOscillator?.stop(time),
+    teardown: noiseMix.teardown,
   };
 }

packages/superdough/reverb.mjs

@@ -2,7 +2,7 @@ import reverbGen from './reverbGen.mjs';
 import { clamp } from './util.mjs';
 
 if (typeof AudioContext !== 'undefined') {
-  AudioContext.prototype.adjustLength = function (duration, buffer, speed = 1, offsetAmount = 0) {
+  BaseAudioContext.prototype.adjustLength = function (duration, buffer, speed = 1, offsetAmount = 0) {
     const sampleOffset = Math.floor(clamp(offsetAmount, 0, 1) * buffer.length);
     const newLength = buffer.sampleRate * duration;
     const newBuffer = this.createBuffer(buffer.numberOfChannels, buffer.length, buffer.sampleRate);
@@ -23,7 +23,7 @@ if (typeof AudioContext !== 'undefined') {
     return newBuffer;
   };
 
-  AudioContext.prototype.createReverb = function (duration, fade, lp, dim, ir, irspeed, irbegin) {
+  BaseAudioContext.prototype.createReverb = function (duration, fade, lp, dim, ir, irspeed, irbegin) {
     const convolver = this.createConvolver();
     convolver.generate = (d = 2, fade = 0.1, lp = 15000, dim = 1000, ir, irspeed, irbegin) => {
       convolver.duration = d;

packages/superdough/sampler.mjs

@@ -1,7 +1,14 @@
-import { getCommonSampleInfo } from './util.mjs';
+import { getBaseURL, getCommonSampleInfo } from './util.mjs';
 import { registerSound, registerWaveTable } from './index.mjs';
 import { getAudioContext } from './audioContext.mjs';
-import { getADSRValues, getParamADSR, getPitchEnvelope, getVibratoOscillator } from './helpers.mjs';
+import {
+  getADSRValues,
+  getParamADSR,
+  getPitchEnvelope,
+  getVibratoOscillator,
+  onceEnded,
+  releaseAudioNode,
+} from './helpers.mjs';
 import { logger } from './logger.mjs';
 
 const bufferCache = {}; // string: Promise<ArrayBuffer>
@@ -211,7 +218,7 @@ export async function fetchSampleMap(url) {
     // not a browser
     return;
   }
-  const base = url.split('/').slice(0, -1).join('/');
+  const base = getBaseURL(url);
   if (typeof fetch === 'undefined') {
     // skip fetch when in node / testing
     return;
@@ -236,12 +243,6 @@ export async function fetchSampleMap(url) {
  *  sd: '808sd/SD0010.WAV'
  *  }, 'https://raw.githubusercontent.com/tidalcycles/Dirt-Samples/master/');
  * s("[bd ~]*2, [~ hh]*2, ~ sd")
- * @example
- * samples('shabda:noise,chimp:2')
- * s("noise <chimp:0*2 chimp:1>")
- * @example
- * samples('shabda/speech/fr-FR/f:chocolat')
- * s("chocolat*4")
  */
 
 export const samples = async (sampleMap, baseUrl = sampleMap._base || '', options = {}) => {
@@ -286,17 +287,19 @@ export async function onTriggerSample(t, value, onended, bank, resolveUrl) {
 
   const { bufferSource, sliceDuration, offset } = await getSampleBufferSource(value, bank, resolveUrl);
 
-  // asny stuff above took too long?
-  if (ac.currentTime > t) {
-    logger(`[sampler] still loading sound "${s}:${n}"`, 'highlight');
-    // console.warn('sample still loading:', s, n);
-    return;
-  }
   if (!bufferSource) {
     logger(`[sampler] could not load "${s}:${n}"`, 'error');
     return;
   }
 
+  // async stuff above took too long?
+  if (ac.currentTime > t) {
+    logger(`[sampler] loading sound "${s}:${n}" took too long`, 'highlight');
+    // AudioBufferSourceNode will never be used. discard it
+    releaseAudioNode(bufferSource);
+    return;
+  }
+
   // vibrato
   let vibratoOscillator = getVibratoOscillator(bufferSource.detune, value, t);
 
@@ -319,13 +322,13 @@ 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);
-  bufferSource.onended = function () {
-    bufferSource.disconnect();
-    vibratoOscillator?.stop();
-    node.disconnect();
-    out.disconnect();
+  onceEnded(bufferSource, function () {
+    releaseAudioNode(bufferSource);
+    releaseAudioNode(vibratoOscillator);
+    releaseAudioNode(node);
+    releaseAudioNode(out);
     onended();
-  };
+  });
   let envEnd = holdEnd + release + 0.01;
   bufferSource.stop(envEnd);
   const stop = (endTime) => {

packages/superdough/superdough.mjs

@@ -9,23 +9,44 @@ 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';
-import { getAudioContext } from './audioContext.mjs';
+import { getAudioContext, setAudioContext } from './audioContext.mjs';
 import { SuperdoughAudioController } from './superdoughoutput.mjs';
+import { resetSeenKeys } from './wavetable.mjs';
 
 export const DEFAULT_MAX_POLYPHONY = 128;
 const DEFAULT_AUDIO_DEVICE_NAME = 'System Standard';
 
-let maxPolyphony = DEFAULT_MAX_POLYPHONY;
+export 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;
 }
 
-let multiChannelOrbits = false;
+export let multiChannelOrbits = false;
 export function setMultiChannelOrbits(bool) {
   multiChannelOrbits = bool == true;
 }
@@ -43,6 +64,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;
 }
@@ -203,11 +235,13 @@ export function registerWorklet(url) {
 }
 
 let workletsLoading;
-function loadWorklets() {
+export function loadWorklets() {
   if (!workletsLoading) {
     const audioCtx = getAudioContext();
     const allWorkletURLs = externalWorklets.concat([workletsUrl]);
-    workletsLoading = Promise.all(allWorkletURLs.map((workletURL) => audioCtx.audioWorklet.addModule(workletURL)));
+    workletsLoading = Promise.all(allWorkletURLs.map((workletURL) => audioCtx.audioWorklet.addModule(workletURL))).then(
+      () => (workletsLoading = undefined),
+    );
   }
 
   return workletsLoading;
@@ -224,6 +258,7 @@ export async function initAudio(options = {}) {
 
   setMaxPolyphony(maxPolyphony);
   setMultiChannelOrbits(multiChannelOrbits);
+  resetSeenKeys();
   if (typeof window === 'undefined') {
     return;
   }
@@ -245,8 +280,9 @@ export async function initAudio(options = {}) {
       logger('[superdough] failed to set audio interface', 'warning');
     }
   }
-
-  await audioCtx.resume();
+  if ((!audioCtx) instanceof OfflineAudioContext) {
+    await audioCtx.resume();
+  }
   if (disableWorklets) {
     logger('[superdough]: AudioWorklets disabled with disableWorklets');
     return;
@@ -263,8 +299,8 @@ let audioReady;
 export async function initAudioOnFirstClick(options) {
   if (!audioReady) {
     audioReady = new Promise((resolve) => {
-      document.addEventListener('click', async function listener() {
-        document.removeEventListener('click', listener);
+      document.addEventListener('mousedown', async function listener() {
+        document.removeEventListener('mousedown', listener);
         await initAudio(options);
         resolve();
       });
@@ -274,12 +310,18 @@ export async function initAudioOnFirstClick(options) {
 }
 
 let controller;
-function getSuperdoughAudioController() {
+export function getSuperdoughAudioController() {
   if (controller == null) {
     controller = new SuperdoughAudioController(getAudioContext());
   }
   return controller;
 }
+
+export function setSuperdoughAudioController(newController) {
+  controller = newController;
+  return controller;
+}
+
 export function connectToDestination(input, channels) {
   const controller = getSuperdoughAudioController();
   controller.output.connectToDestination(input, channels);
@@ -287,11 +329,11 @@ export function connectToDestination(input, channels) {
 
 function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000, sweep = 2000) {
   const ac = getAudioContext();
-  const lfoGain = getLfo(ac, time, end, { frequency, depth: sweep * 2 });
+  const lfo = getLfo(ac, time, end, { frequency, depth: sweep * 2 });
 
   //filters
-  const numStages = 2; //num of filters in series
-  let fOffset = 0;
+  const numStages = 1; //num of filters in series
+  let fOffset = 282; //for backward compat in #1800
   const filterChain = [];
   for (let i = 0; i < numStages; i++) {
     const filter = ac.createBiquadFilter();
@@ -300,14 +342,11 @@ function getPhaser(time, end, frequency = 1, depth = 0.5, centerFrequency = 1000
     filter.frequency.value = centerFrequency + fOffset;
     filter.Q.value = 2 - Math.min(Math.max(depth * 2, 0), 1.9);
 
-    lfoGain.connect(filter.detune);
+    lfo.connect(filter.detune);
     fOffset += 282;
-    if (i > 0) {
-      filterChain[i - 1].connect(filter);
-    }
     filterChain.push(filter);
   }
-  return filterChain[filterChain.length - 1];
+  return { filterChain, lfo };
 }
 
 function getFilterType(ftype) {
@@ -320,7 +359,7 @@ export let analysers = {},
   analysersData = {};
 
 export function getAnalyserById(id, fftSize = 1024, smoothingTimeConstant = 0.5) {
-  if (!analysers[id]) {
+  if (!analysers[id] || analysers[id].audioContext != getAudioContext()) {
     // make sure this doesn't happen too often as it piles up garbage
     const analyserNode = getAudioContext().createAnalyser();
     analyserNode.fftSize = fftSize;
@@ -382,7 +421,6 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   // duration is passed as value too..
   value.duration = hapDuration;
   // calculate absolute time
-
   if (t < ac.currentTime) {
     console.warn(
       `[superdough]: cannot schedule sounds in the past (target: ${t.toFixed(2)}, now: ${ac.currentTime.toFixed(2)})`,
@@ -413,7 +451,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     release = 0,
 
     //phaser
-    phaserrate: phaser,
+    phaserrate,
     phaserdepth = getDefaultValue('phaserdepth'),
     phasersweep,
     phasercenter,
@@ -451,6 +489,8 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     compressorKnee,
     compressorAttack,
     compressorRelease,
+    transient,
+    transsustain,
   } = value;
 
   delaytime = delaytime ?? cycleToSeconds(delaysync, cps);
@@ -506,7 +546,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);
@@ -532,6 +572,23 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   chain.push(sourceNode);
   stretch !== undefined && chain.push(getWorklet(ac, 'phase-vocoder-processor', { pitchFactor: stretch }));
 
+  transient !== undefined &&
+    chain.push(
+      getWorklet(
+        ac,
+        'transient-processor',
+        {},
+        {
+          processorOptions: {
+            attack: transient,
+            sustain: transsustain,
+            begin: t,
+            end: endWithRelease,
+          },
+        },
+      ),
+    );
+
   // gain stage
   chain.push(gainNode(gain));
 
@@ -553,16 +610,21 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
       rate: 'lprate',
       sync: 'lpsync',
       depth: 'lpdepth',
+      depthfrequency: 'lpdepthfrequency',
       shape: 'lpshape',
       dcoffset: 'lpdc',
       skew: 'lpskew',
     };
     const lpParams = pickAndRename(value, lpMap);
     lpParams.type = 'lowpass';
-    let lp = () => createFilter(ac, t, end, lpParams, cps);
-    chain.push(lp());
+    const lp = () => createFilter(ac, t, end, lpParams, cps, cycle);
+    const { filter: lpf1, lfo: lfo1 } = lp();
+    chain.push(lpf1);
+    lfo1 && audioNodes.push(lfo1);
     if (ftype === '24db') {
-      chain.push(lp());
+      const { filter: lpf2, lfo: lfo2 } = lp();
+      chain.push(lpf2);
+      lfo2 && audioNodes.push(lfo2);
     }
   }
 
@@ -581,16 +643,21 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
       rate: 'hprate',
       sync: 'hpsync',
       depth: 'hpdepth',
+      depthfrequency: 'hpdepthfrequency',
       shape: 'hpshape',
       dcoffset: 'hpdc',
       skew: 'hpskew',
     };
     const hpParams = pickAndRename(value, hpMap);
     hpParams.type = 'highpass';
-    let hp = () => createFilter(ac, t, end, hpParams, cps);
-    chain.push(hp());
+    const hp = () => createFilter(ac, t, end, hpParams, cps, cycle);
+    const { filter: hpf1, lfo: lfo1 } = hp();
+    chain.push(hpf1);
+    lfo1 && audioNodes.push(lfo1);
     if (ftype === '24db') {
-      chain.push(hp());
+      const { filter: hpf2, lfo: lfo2 } = hp();
+      chain.push(hpf2);
+      lfo2 && audioNodes.push(lfo2);
     }
   }
 
@@ -609,16 +676,21 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
       rate: 'bprate',
       sync: 'bpsync',
       depth: 'bpdepth',
+      depthfrequency: 'bpdepthfrequency',
       shape: 'bpshape',
       dcoffset: 'bpdc',
       skew: 'bpskew',
     };
     const bpParams = pickAndRename(value, bpMap);
     bpParams.type = 'bandpass';
-    let bp = () => createFilter(ac, t, end, bpParams, cps);
-    chain.push(bp());
+    const bp = () => createFilter(ac, t, end, bpParams, cps, cycle);
+    const { filter: bpf1, lfo: lfo1 } = bp();
+    chain.push(bpf1);
+    lfo1 && audioNodes.push(lfo1);
     if (ftype === '24db') {
-      chain.push(bp());
+      const { filter: bpf2, lfo: lfo2 } = bp();
+      chain.push(bpf2);
+      lfo2 && audioNodes.push(lfo2);
     }
   }
 
@@ -665,6 +737,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
       curve: 1.5,
     });
     lfo.connect(amGain.gain);
+    audioNodes.push(lfo);
     chain.push(amGain);
   }
 
@@ -680,9 +753,10 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
     chain.push(panner);
   }
   // phaser
-  if (phaser !== undefined && phaserdepth > 0) {
-    const phaserFX = getPhaser(t, endWithRelease, phaser, phaserdepth, phasercenter, phasersweep);
-    chain.push(phaserFX);
+  if (phaserrate !== undefined && phaserdepth > 0) {
+    const { filterChain, lfo } = getPhaser(t, endWithRelease, phaserrate, phaserdepth, phasercenter, phasersweep);
+    audioNodes.push(lfo);
+    chain.push(...filterChain);
   }
 
   // last gain
@@ -692,7 +766,8 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   // delay
   if (delay > 0 && delaytime > 0 && delayfeedback > 0) {
     orbitBus.getDelay(delaytime, delayfeedback, t);
-    orbitBus.sendDelay(post, delay);
+    const send = orbitBus.sendDelay(post, delay);
+    audioNodes.push(send);
   }
   // reverb
   if (room > 0) {
@@ -717,7 +792,7 @@ export const superdough = async (value, t, hapDuration, cps = 0.5, cycle = 0.5)
   }
 
   // analyser
-  if (analyze) {
+  if (analyze && !(ac instanceof OfflineAudioContext)) {
     const analyserNode = getAnalyserById(analyze, 2 ** (fft + 5));
     const analyserSend = effectSend(post, analyserNode, 1);
     audioNodes.push(analyserSend);

packages/superdough/superdoughoutput.mjs

@@ -82,7 +82,7 @@ export class Orbit {
   }
 
   sendDelay(node, amount) {
-    effectSend(node, this.delayNode, amount);
+    return effectSend(node, this.delayNode, amount);
   }
 
   duck(t, onsettime = 0, attacktime = 0.1, depth = 1) {

packages/superdough/synth.mjs

@@ -3,7 +3,6 @@ import { registerSound, soundMap } from './superdough.mjs';
 import { getAudioContext } from './audioContext.mjs';
 import {
   applyFM,
-  destroyAudioWorkletNode,
   gainNode,
   getADSRValues,
   getFrequencyFromValue,
@@ -13,6 +12,8 @@ import {
   getVibratoOscillator,
   getWorklet,
   noises,
+  onceEnded,
+  releaseAudioNode,
   webAudioTimeout,
 } from './helpers.mjs';
 import { logger } from './logger.mjs';
@@ -48,19 +49,17 @@ export function registerSynthSounds() {
           [0.001, 0.05, 0.6, 0.01],
         );
 
-        let sound = getOscillator(s, t, value);
-        let { node: o, stop, triggerRelease } = sound;
-
         // turn down
         const g = gainNode(0.3);
 
-        const { duration } = value;
-
-        o.onended = () => {
-          o.disconnect();
-          g.disconnect();
+        let sound = getOscillator(s, t, value, () => {
+          releaseAudioNode(g);
           onended();
-        };
+        });
+
+        let { node: o, stop, triggerRelease } = sound;
+
+        const { duration } = value;
 
         const envGain = gainNode(1);
         let node = o.connect(g).connect(envGain);
@@ -112,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);
@@ -194,8 +193,7 @@ export function registerSynthSounds() {
       let timeoutNode = webAudioTimeout(
         ac,
         () => {
-          destroyAudioWorkletNode(o);
-          envGain.disconnect();
+          releaseAudioNode(o);
           onended();
           fm?.stop();
           vibratoOscillator?.stop();
@@ -272,8 +270,7 @@ export function registerSynthSounds() {
       let timeoutNode = webAudioTimeout(
         ac,
         () => {
-          destroyAudioWorkletNode(o);
-          envGain.disconnect();
+          releaseAudioNode(o);
           onended();
         },
         begin,
@@ -346,9 +343,8 @@ export function registerSynthSounds() {
       let timeoutNode = webAudioTimeout(
         ac,
         () => {
-          destroyAudioWorkletNode(o);
-          destroyAudioWorkletNode(lfo);
-          envGain.disconnect();
+          releaseAudioNode(o);
+          releaseAudioNode(lfo);
           onended();
           fm?.stop();
           vibratoOscillator?.stop();
@@ -389,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);
@@ -460,7 +456,7 @@ export function waveformN(partials, phases, type) {
 }
 
 // expects one of waveforms as s
-export function getOscillator(s, t, value) {
+export function getOscillator(s, t, value, onended) {
   const { duration, noise = 0 } = value;
   const partials = value.partials ?? value.n;
   let o;
@@ -482,7 +478,6 @@ export function getOscillator(s, t, value) {
   }
   // set frequency
   o.frequency.value = getFrequencyFromValue(value);
-  o.start(t);
 
   let vibratoOscillator = getVibratoOscillator(o.detune, value, t);
 
@@ -495,6 +490,14 @@ export function getOscillator(s, t, value) {
     noiseMix = getNoiseMix(o, noise, t);
   }
 
+  onceEnded(o, () => {
+    noiseMix?.teardown();
+    releaseAudioNode(o);
+    releaseAudioNode(noiseMix?.node);
+    onended();
+  });
+  o.start(t);
+
   return {
     node: noiseMix?.node || o,
     stop: (time) => {

packages/superdough/util.mjs

@@ -114,3 +114,13 @@ export function getCommonSampleInfo(hapValue, bank) {
 export const pickAndRename = (source, map) => {
   return Object.fromEntries(Object.entries(map).map(([newKey, oldKey]) => [newKey, source[oldKey]]));
 };
+
+export const getBaseURL = (url) => {
+  try {
+    // For real URLs
+    return new URL('.', new URL(url)).href.replace(/\/$/, ''); // removes trailing slash
+  } catch {
+    // For pseudo URLS
+    return url.split('/').slice(0, -1).join('/');
+  }
+};

packages/superdough/vowel.mjs

@@ -45,7 +45,8 @@ if (typeof GainNode !== 'undefined') {
         throw new Error('vowel: unknown vowel ' + letter);
       }
       const { gains, qs, freqs } = vowelFormant[letter];
-      const makeupGain = ac.createGain();
+      this.makeupGain = ac.createGain();
+      this.audioNodes = [];
       for (let i = 0; i < 5; i++) {
         const gain = ac.createGain();
         gain.gain.value = gains[i];
@@ -53,17 +54,28 @@ if (typeof GainNode !== 'undefined') {
         filter.type = 'bandpass';
         filter.Q.value = qs[i];
         filter.frequency.value = freqs[i];
-        this.connect(filter);
+        super.connect(filter);
         filter.connect(gain);
-        gain.connect(makeupGain);
+        this.audioNodes.push(filter);
+        gain.connect(this.makeupGain);
+        this.audioNodes.push(gain);
       }
-      makeupGain.gain.value = 8; // how much makeup gain to add?
-      this.connect = (target) => makeupGain.connect(target);
+      this.makeupGain.gain.value = 8; // how much makeup gain to add?
       return this;
     }
+    connect(target) {
+      this.makeupGain.connect(target);
+    }
+    disconnect() {
+      this.makeupGain.disconnect();
+      this.audioNodes.forEach((n) => n.disconnect());
+      super.disconnect();
+      this.makeupGain = null;
+      this.audioNodes = null;
+    }
   }
 
-  AudioContext.prototype.createVowelFilter = function (letter) {
+  BaseAudioContext.prototype.createVowelFilter = function (letter) {
     return new VowelNode(this, letter);
   };
 }

packages/superdough/wavetable.mjs

@@ -1,15 +1,15 @@
 import { getAudioContext, registerSound } from './index.mjs';
-import { getCommonSampleInfo } from './util.mjs';
+import { getBaseURL, getCommonSampleInfo } from './util.mjs';
 import {
   applyFM,
   applyParameterModulators,
-  destroyAudioWorkletNode,
   getADSRValues,
   getFrequencyFromValue,
   getParamADSR,
   getPitchEnvelope,
   getVibratoOscillator,
   getWorklet,
+  releaseAudioNode,
   webAudioTimeout,
 } from './helpers.mjs';
 import { logger } from './logger.mjs';
@@ -40,6 +40,11 @@ export const Warpmode = Object.freeze({
 });
 
 const seenKeys = new Set();
+
+export function resetSeenKeys() {
+  seenKeys.clear();
+}
+
 async function getPayload(url, label, frameLen = 2048) {
   const key = `${url},${frameLen}`;
   if (!seenKeys.has(key)) {
@@ -190,6 +195,7 @@ export const tables = async (url, frameLen, json, options = {}) => {
   if (url.startsWith('local:')) {
     url = `http://localhost:5432`;
   }
+  const base = getBaseURL(url);
   if (typeof fetch !== 'function') {
     // not a browser
     return;
@@ -200,7 +206,7 @@ export const tables = async (url, frameLen, json, options = {}) => {
   }
   return fetch(url)
     .then((res) => res.json())
-    .then((json) => _processTables(json, url, frameLen, options))
+    .then((json) => _processTables(json, base, frameLen, options))
     .catch((error) => {
       console.error(error);
       throw new Error(`error loading "${url}"`);
@@ -318,12 +324,11 @@ export async function onTriggerSynth(t, value, onended, tables, cps, frameLen) {
   const timeoutNode = webAudioTimeout(
     ac,
     () => {
-      destroyAudioWorkletNode(source);
-      vibratoOscillator?.stop();
+      releaseAudioNode(source);
+      releaseAudioNode(vibratoOscillator);
       fm?.stop();
-      node.disconnect();
-      wtPosModulators?.disconnect();
-      wtWarpModulators?.disconnect();
+      releaseAudioNode(wtPosModulators);
+      releaseAudioNode(wtWarpModulators);
       onended();
     },
     t,

packages/superdough/worklets.mjs

@@ -11,6 +11,9 @@ const PI = Math.PI;
 const TWO_PI = 2 * PI;
 const INVSR = 1 / sampleRate;
 
+const timeToCoeff = (t) => 1 - Math.exp(-INVSR / t);
+const dbToLin = (db) => Math.pow(10, db / 20);
+
 const clamp = (num, min, max) => Math.min(Math.max(num, min), max);
 const mod = (n, m) => ((n % m) + m) % m;
 const lerp = (a, b, n) => n * (b - a) + a;
@@ -508,13 +511,14 @@ class SuperSawOscillatorProcessor extends AudioWorkletProcessor {
     ];
   }
   process(_input, outputs, params) {
-    if (currentTime <= params.begin[0]) {
-      return true;
-    }
     if (currentTime >= params.end[0]) {
-      // this.port.postMessage({ type: 'onended' });
+      // should terminate
       return false;
     }
+    if (currentTime <= params.begin[0]) {
+      // keep alive
+      return true;
+    }
     const output = outputs[0];
     const voices = params.voices[0]; // k-rate
     for (let i = 0; i < output[0].length; i++) {
@@ -532,7 +536,7 @@ class SuperSawOscillatorProcessor extends AudioWorkletProcessor {
         const freqVoice = applySemitoneDetuneToFrequency(freq, detuner(n));
         // We must wrap this here because it is passed into sawblep below which
         // has domain [0, 1]
-        const dt = ffrac(freqVoice * INVSR);
+        const dt = frac(freqVoice * INVSR);
         this.phase[n] = this.phase[n] ?? Math.random();
         const v = waveshapes.sawblep(this.phase[n], dt);
 
@@ -543,8 +547,9 @@ class SuperSawOscillatorProcessor extends AudioWorkletProcessor {
         if (pn >= 1.0) pn -= 1.0;
         this.phase[n] = pn;
         // invert right and left gain
+        const tmp = gainL;
         gainL = gainR;
-        gainR = gainL;
+        gainR = tmp;
       }
     }
     return true;
@@ -1338,7 +1343,7 @@ class WavetableOscillatorProcessor extends AudioWorkletProcessor {
       const tablePos = clamp(pv(parameters.position, i), 0, 1);
       const idx = tablePos * (this.numFrames - 1);
       const fIdx = idx | 0;
-      const frac = idx - fIdx;
+      const interpT = idx - fIdx;
       const warpAmount = clamp(pv(parameters.warp, i), 0, 1);
       const warpMode = pv(parameters.warpMode, i);
       const phaseRand = clamp(pv(parameters.phaserand, i), 0, 1);
@@ -1368,13 +1373,13 @@ class WavetableOscillatorProcessor extends AudioWorkletProcessor {
         const ph = this._warpPhase(this.phase[n], warpAmount, warpMode);
         const s0 = this._sampleFrame(table[fIdx], ph);
         const s1 = this._sampleFrame(table[Math.min(this.numFrames - 1, fIdx + 1)], ph);
-        let s = s0 + (s1 - s0) * frac;
+        let s = lerp(s0, s1, interpT);
         if (warpMode === WarpMode.FLIP && this.phase[n] < warpAmount) {
           s = -s;
         }
         outL[i] += s * gainL * normalizer;
         outR[i] += s * gainR * normalizer;
-        this.phase[n] = ffrac(this.phase[n] + dPhase);
+        this.phase[n] = frac(this.phase[n] + dPhase);
       }
     }
     return true;
@@ -1382,3 +1387,82 @@ class WavetableOscillatorProcessor extends AudioWorkletProcessor {
 }
 
 registerProcessor('wavetable-oscillator-processor', WavetableOscillatorProcessor);
+
+class TransientProcessor extends AudioWorkletProcessor {
+  static get parameterDescriptors() {
+    return [];
+  }
+
+  constructor(options) {
+    super();
+    this.gainCoeff = timeToCoeff(0.2);
+    this.avgGain = 1;
+    let {
+      attackTime = 0.003,
+      sustainTime = 0.08,
+      attack = 0,
+      sustain = 0,
+      sensitivity = 0.1,
+      mix = 1,
+      begin = 0,
+      end = 0,
+    } = options.processorOptions;
+    attackTime = clamp(attackTime, 0.0005, 0.05);
+    sustainTime = clamp(sustainTime, 0.01, 0.5);
+    this.attackCoeff = timeToCoeff(attackTime);
+    this.sustainCoeff = timeToCoeff(sustainTime);
+    this.attackAmt = clamp(attack, -1, 1);
+    this.sustainAmt = clamp(sustain, -1, 1);
+    this.scaling = 0.5 + 5 * clamp(sensitivity, 0, 1);
+    this.mix = clamp(mix, 0, 1);
+    this.begin = begin;
+    this.end = end;
+    this.attackEnv = new Float32Array(2); // assume stereo
+    this.sustainEnv = new Float32Array(2);
+  }
+
+  process(inputs, outputs, _params) {
+    const input = inputs[0];
+    const output = outputs[0];
+    if (currentTime >= this.end) {
+      return false;
+    }
+    if (currentTime <= this.begin) {
+      return true;
+    }
+    const channels = input.length;
+    if (channels > this.attackEnv.length) {
+      this.attackEnv = new Float32Array(channels);
+      this.sustainEnv = new Float32Array(channels);
+    }
+    let avgGain = this.avgGain;
+    for (let ch = 0; ch < channels; ch++) {
+      let attEnv = this.attackEnv[ch];
+      let susEnv = this.sustainEnv[ch];
+      for (let n = 0; n < blockSize; n++) {
+        const sample = input[ch][n];
+        const x = Math.abs(sample);
+        attEnv = lerp(attEnv, x, this.attackCoeff);
+        susEnv = lerp(susEnv, x, this.sustainCoeff);
+        const peakiness = clamp((this.scaling * (attEnv - susEnv)) / (susEnv + 1e-6), -1.5, 1.5);
+        const attScale = peakiness > 0 ? peakiness : 0;
+        const susScale = peakiness < 0 ? -peakiness : 0;
+        const attackGain = dbToLin(this.attackAmt * attScale * 18);
+        const sustainGain = dbToLin(this.sustainAmt * susScale * 36);
+        const gain = clamp(attackGain * sustainGain, 0, 8);
+        avgGain = lerp(avgGain, gain, this.gainCoeff);
+        const makeup = avgGain > 1e-3 ? 1 / avgGain : 1;
+        const wet = sample * gain * makeup;
+        let y = lerp(sample, wet, this.mix);
+        y /= 1 + Math.abs(y); // soft clip
+        output[ch][n] = y;
+      }
+      this.attackEnv[ch] = attEnv;
+      this.sustainEnv[ch] = susEnv;
+    }
+    this.avgGain = avgGain;
+    return true;
+  }
+}
+
+registerProcessor('transient-processor', TransientProcessor);

packages/superdough/zzfx.mjs

@@ -3,6 +3,7 @@ import { midiToFreq, noteToMidi } from './util.mjs';
 import { registerSound } from './superdough.mjs';
 import { getAudioContext } from './audioContext.mjs';
 import { buildSamples } from './zzfx_fork.mjs';
+import { onceEnded, releaseAudioNode } from './helpers.mjs';
 
 export const getZZFX = (value, t) => {
   let {
@@ -83,10 +84,10 @@ export function registerZZFXSounds() {
       wave,
       (t, value, onended) => {
         const { node: o } = getZZFX({ s: wave, ...value }, t);
-        o.onended = () => {
-          o.disconnect();
+        onceEnded(o, () => {
+          releaseAudioNode(o);
           onended();
-        };
+        });
         return {
           node: o,
           stop: () => {},

packages/tonal/tonal.mjs

@@ -5,7 +5,16 @@ This program is free software: you can redistribute it and/or modify it under th
 */
 
 import { Note, Interval, Scale } from '@tonaljs/tonal';
-import { register, _mod, logger, isNote, noteToMidi, removeUndefineds, getAccidentalsOffset } from '@strudel/core';
+import {
+  _mod,
+  errorLogger,
+  getAccidentalsOffset,
+  isNote,
+  logger,
+  noteToMidi,
+  register,
+  removeUndefineds,
+} from '@strudel/core';
 import { stepInNamedScale, nearestNumberIndex } from './tonleiter.mjs';
 
 const octavesInterval = (octaves) => (octaves <= 0 ? -1 : 1) + octaves * 7 + 'P';
@@ -294,7 +303,7 @@ export const scale = register(
             }
             if (offset != 0) scaleNote = Note.transpose(scaleNote, Interval.fromSemitones(offset));
           } catch (err) {
-            logger(`[tonal] ${err.message}`, 'error');
+            errorLogger(err, 'tonal');
             return; // will be removed
           }
         }

packages/webaudio/webaudio.mjs

@@ -5,10 +5,21 @@ This program is free software: you can redistribute it and/or modify it under th
 */
 
 import * as strudel from '@strudel/core';
-import { superdough, getAudioContext, setLogger, doughTrigger, registerWorklet } from 'superdough';
+import {
+  superdough,
+  getAudioContext,
+  setLogger,
+  doughTrigger,
+  registerWorklet,
+  setAudioContext,
+  initAudio,
+  setSuperdoughAudioController,
+  resetGlobalEffects,
+  errorLogger,
+} from 'superdough';
 import './supradough.mjs';
 import { workletUrl } from 'supradough';
-
+import { SuperdoughAudioController } from 'superdough/superdoughoutput.mjs';
 registerWorklet(workletUrl);
 
 const { Pattern, logger, repl } = strudel;
@@ -26,6 +37,71 @@ export const webaudioOutput = (hap, _deadline, hapDuration, cps, t) => {
   return superdough(hap2value(hap), t, hapDuration, cps, hap.whole?.begin.valueOf());
 };
 
+export async function renderPatternAudio(
+  pattern,
+  cps,
+  begin,
+  end,
+  sampleRate,
+  maxPolyphony,
+  multiChannelOrbits,
+  downloadName = undefined,
+) {
+  let audioContext = getAudioContext();
+  await audioContext.close();
+  audioContext = new OfflineAudioContext(2, ((end - begin) / cps) * sampleRate, sampleRate);
+  setAudioContext(audioContext);
+  setSuperdoughAudioController(new SuperdoughAudioController(audioContext));
+  await initAudio({
+    maxPolyphony,
+    multiChannelOrbits,
+  });
+  logger('[webaudio] preloading');
+
+  // Calling superdough(...) in ascending onset time order is important
+  // for controls that depend on the audio graph state like `cut`
+  let haps = pattern
+    .queryArc(begin, end, { _cps: cps })
+    .sort((a, b) => a.whole.begin.valueOf() - b.whole.begin.valueOf());
+  for (const hap of haps) {
+    if (hap.hasOnset()) {
+      try {
+        await superdough(
+          hap2value(hap),
+          (hap.whole.begin.valueOf() - begin) / cps,
+          hap.duration / cps,
+          cps,
+          (hap.whole?.begin.valueOf() - begin) / cps,
+        );
+      } catch (err) {
+        errorLogger(err, 'webaudio');
+      }
+    }
+  }
+  logger('[webaudio] start rendering');
+
+  return audioContext
+    .startRendering()
+    .then((renderedBuffer) => {
+      const wavBuffer = audioBufferToWav(renderedBuffer);
+      const blob = new Blob([wavBuffer], { type: 'audio/wav' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      downloadName = downloadName ? `${downloadName}.wav` : `${new Date().toISOString()}.wav`;
+      a.download = `${downloadName}`;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+    })
+    .finally(async () => {
+      setAudioContext(null);
+      setSuperdoughAudioController(null);
+      resetGlobalEffects();
+    });
+}
+
 export function webaudioRepl(options = {}) {
   options = {
     getTime: () => getAudioContext().currentTime,
@@ -38,3 +114,98 @@ export function webaudioRepl(options = {}) {
 Pattern.prototype.dough = function () {
   return this.onTrigger(doughTrigger, 1);
 };
+
+function audioBufferToWav(buffer, opt) {
+  opt = opt || {};
+
+  var numChannels = buffer.numberOfChannels;
+  var sampleRate = buffer.sampleRate;
+  var format = opt.float32 ? 3 : 1;
+  var bitDepth = format === 3 ? 32 : 16;
+
+  var result;
+  if (numChannels === 2) {
+    result = interleave(buffer.getChannelData(0), buffer.getChannelData(1));
+  } else {
+    result = buffer.getChannelData(0);
+  }
+
+  return encodeWAV(result, format, sampleRate, numChannels, bitDepth);
+}
+
+function encodeWAV(samples, format, sampleRate, numChannels, bitDepth) {
+  var bytesPerSample = bitDepth / 8;
+  var blockAlign = numChannels * bytesPerSample;
+
+  var buffer = new ArrayBuffer(44 + samples.length * bytesPerSample);
+  var view = new DataView(buffer);
+
+  /* RIFF identifier */
+  writeString(view, 0, 'RIFF');
+  /* RIFF chunk length */
+  view.setUint32(4, 36 + samples.length * bytesPerSample, true);
+  /* RIFF type */
+  writeString(view, 8, 'WAVE');
+  /* format chunk identifier */
+  writeString(view, 12, 'fmt ');
+  /* format chunk length */
+  view.setUint32(16, 16, true);
+  /* sample format (raw) */
+  view.setUint16(20, format, true);
+  /* channel count */
+  view.setUint16(22, numChannels, true);
+  /* sample rate */
+  view.setUint32(24, sampleRate, true);
+  /* byte rate (sample rate * block align) */
+  view.setUint32(28, sampleRate * blockAlign, true);
+  /* block align (channel count * bytes per sample) */
+  view.setUint16(32, blockAlign, true);
+  /* bits per sample */
+  view.setUint16(34, bitDepth, true);
+  /* data chunk identifier */
+  writeString(view, 36, 'data');
+  /* data chunk length */
+  view.setUint32(40, samples.length * bytesPerSample, true);
+  if (format === 1) {
+    // Raw PCM
+    floatTo16BitPCM(view, 44, samples);
+  } else {
+    writeFloat32(view, 44, samples);
+  }
+
+  return buffer;
+}
+
+function interleave(inputL, inputR) {
+  var length = inputL.length + inputR.length;
+  var result = new Float32Array(length);
+
+  var index = 0;
+  var inputIndex = 0;
+
+  while (index < length) {
+    result[index++] = inputL[inputIndex];
+    result[index++] = inputR[inputIndex];
+    inputIndex++;
+  }
+  return result;
+}
+
+function writeFloat32(output, offset, input) {
+  for (var i = 0; i < input.length; i++, offset += 4) {
+    output.setFloat32(offset, input[i], true);
+  }
+}
+
+function floatTo16BitPCM(output, offset, input) {
+  for (var i = 0; i < input.length; i++, offset += 2) {
+    var s = Math.max(-1, Math.min(1, input[i]));
+    output.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7fff, true);
+  }
+}
+
+function writeString(view, offset, string) {
+  for (var i = 0; i < string.length; i++) {
+    view.setUint8(offset + i, string.charCodeAt(i));
+  }
+}