tweaks

Reviewed-on: https://codeberg.org/uzu/strudel/pulls/1827

CONTRIBUTING.md

@@ -4,20 +4,13 @@ Thanks for wanting to contribute!!! There are many ways you can add value to thi
 
 ## Move to codeberg
 
-We are currently in the process of moving from github to codeberg -- not everything is working, please bear with us.
-
-To update your local clone, you can run this command:
-
-```
-git remote set-url origin git@codeberg.org:uzu/strudel.git
-```
-
+Along with many other live coding projects, we have moved from Microsoft's Github platform to Codeberg for ethical reasons. Please don't fork the project back to github.
 
 ## Communication Channels
 
-To get in touch with the contributors, either
+To get in touch with the community, either
 
-- [join the Tidal Discord Channel](https://discord.com/invite/HGEdXmRkzT) and go to the #strudel channel
+- [join the Uzulang Discord Server](https://discord.com/invite/HGEdXmRkzT) and go to the strudel channels (Uzulangs are a family of live coding languages inspired by each other, including TidalCycles as well as Strudel)
 - Find related discussions on the [tidal club forum](https://club.tidalcycles.org/)
 
 ## Ask a Question
@@ -36,22 +29,35 @@ Use one of the Communication Channels listed above and drop us a line or two!
 ## Share Music
 
 If you made some music with strudel, you can give back some love and share what you've done!
-Your creation could also be part of the random selection in the REPL if you want.
 Use one of the Communication Channels listed above.
+(There used to be a random selection of contributed patterns in the REPL, but that is unfortunately disabled for now due to abuse)
 
 ## Improve the Docs
 
-If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/),
-you can edit each file directly on codeburg. (we are currently fixing the "Edit this page" links in the right sidebar)
+If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/), you can edit each file directly on codeberg. There are "Edit this page" links in the right sidebar that take you to the right place.
 
 ## Propose a Feature
 
-If you want a specific feature that is not part of strudel yet, feel free to use one of the communication channels above.
-Maybe you even want to help with the implementation of that feature!
+If you want a specific feature that is not part of strudel yet, feel free to use one of the communication channels above. Please bear in mind that this is a free/open source project, oriented around collaborative discussion. Maybe you even want to help with the implementation of that feature!
+
+## Contribute a feature
+
+Pull requests welcome! Consider starting with discussion or proof-of-concept first, rather than do loads of work on something and then find it doesn't fit the collective goals of the project, or something like that.
+
+At the time of writing we have a PR backlog, and generally prioritise bugfixes and contributions that have arisen through community discussion.
+
+### AI/LLM policy
+
+Strudel is a project handmade by humans, with thought and nuance. 
+
+If you have used LLMs (so called 'AI'), please detail that in the pull request. We are still developing our response to the onslaught of LLM technology, but for practical and legal reasons are currently not accepting wholly LLM-generated code. We are also not accepting PRs that add LLM features to strudel itself.
+
+There are #llm-chat and #llm-share channels on our discord. Please do not discuss or share LLM-related things outside of those channels.
 
 ## Report a Bug
 
 If you've found a bug, or some behaviour that does not seem right, you are welcome to file an [issue](https://codeberg.org/uzu/strudel/issues).
+
 Please check that it has not been reported before.
 
 ## Fix a Bug
@@ -118,8 +124,7 @@ There are also eslint extensions / plugins for most editors.
 
 ## Running all CI Checks
 
-When opening a PR, the CI runner will automatically check the code style and eslint, as well as run all tests.
-You can run the same check with `pnpm check`
+When opening a PR, the CI runner will (once approved by a human) check the code style and eslint, as well as run all tests. You can run the same check with `pnpm check`.
 
 ## Package Workflow
 

packages/core/controls.mjs

@@ -2753,8 +2753,13 @@ export const as = register('as', (mapping, pat) => {
   mapping = Array.isArray(mapping) ? mapping : [mapping];
   return pat.fmap((v) => {
     v = Array.isArray(v) ? v : [v];
-    v = Object.fromEntries(mapping.map((prop, i) => [getControlName(prop), v[i]]));
-    return v;
+    const entries = [];
+    for (let i = 0; i < mapping.length; ++i) {
+      if (v[i] !== undefined) {
+        entries.push([getControlName(mapping[i]), v[i]]);
+      }
+    }
+    return Object.fromEntries(entries);
   });
 });
 

packages/superdough/audioGraph.mjs

@@ -1,143 +0,0 @@
-/*
-audioGraph.mjs - Shadow web audio graph used for managing connections
-Copyright (C) 2025 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/superdough/audioGraph.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 { logger } from './logger.mjs';
-
-// 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 (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)));
-};
-
-class Edge {
-  constructor(from, to) {
-    this.from = new WeakRef(from);
-    this.to = new WeakRef(to);
-    this.subGraphs = new Set();
-  }
-  disconnect() {
-    const from = this.from.deref();
-    const to = this.to.deref();
-    from && to && from.disconnect(to);
-  }
-  release() {
-    const from = this.from.deref();
-    if (from instanceof AudioNode) {
-      releaseAudioNode(from);
-    }
-  }
-}
-
-let audioGraph;
-class AudioGraph {
-  constructor(id) {
-    this.id = id;
-    this.activeSubGraphs = [];
-    this.subGraphs = {};
-    this.edges = [];
-    this.subGraphCounter = 0;
-  }
-
-  connect(from, to) {
-    const edge = new Edge(from, to);
-    for (const subGraph of this.activeSubGraphs) {
-      // Track which subgraphs it's in
-      edge.subGraphs.add(subGraph.id);
-      // Add to the subgraph's `edges`
-      subGraph.edges.push(edge);
-      // Add to this' `edges`
-      this.edges.push(edge);
-    }
-    // Make the actual connection
-    return from.connect(to);
-  }
-
-  // Introduces a context wherein all connections will be added to both this graph
-  // and the subgraph and all edges will be tagged with the subgraph for tracking
-  asSubGraph(fn) {
-    const subGraphID = `${this.id}_${this.subGraphCounter}`;
-    this.subGraphCounter++;
-    const subGraph = new AudioGraph(subGraphID);
-    this.subGraphs[subGraphID] = subGraph;
-    this.activeSubGraphs.push(subGraph);
-    try {
-      return { subGraph, output: fn() };
-    } finally {
-      this.activeSubGraphs.pop();
-    }
-  }
-
-  // Disconnects all from-to connections (rather than naked `from.disconnect()`)
-  disconnect() {
-    this.edges.forEach((edge) => edge.disconnect());
-    this.edges = [];
-  }
-
-  // Release this entire graph (nodes will be fully disconnected, stopped, etc)
-  release() {
-    this.edges.forEach((edge) => edge.release());
-    this.edges = [];
-  }
-}
-
-export const getAudioGraph = () => {
-  if (audioGraph === undefined) {
-    audioGraph = new AudioGraph(0);
-  }
-  return audioGraph;
-};

packages/superdough/helpers.mjs

@@ -1,5 +1,4 @@
 import { getAudioContext } from './audioContext.mjs';
-import { getAudioGraph, onceEnded, releaseAudioNode } from './audioGraph.mjs';
 import { logger } from './logger.mjs';
 import { getNoiseBuffer } from './noise.mjs';
 import { clamp, nanFallback, midiToFreq, noteToMidi } from './util.mjs';
@@ -270,20 +269,30 @@ let wetfade = (d) => (d < 0.5 ? 1 : 1 - (d - 0.5) / 0.5);
 // still not too sure about how this could be used more generally...
 export function drywet(dry, wet, wetAmount = 0) {
   const ac = getAudioContext();
-  const ag = getAudioGraph();
   if (!wetAmount) {
     return dry;
   }
   let dry_gain = ac.createGain();
   let wet_gain = ac.createGain();
-  ag.connect(dry, dry_gain);
-  ag.connect(wet, wet_gain);
+  dry.connect(dry_gain);
+  wet.connect(wet_gain);
   dry_gain.gain.value = wetfade(wetAmount);
   wet_gain.gain.value = wetfade(1 - wetAmount);
-  const mix = ac.createGain();
-  ag.connect(dry_gain, mix);
-  ag.connect(wet_gain, mix);
-  return { node: mix };
+  let mix = ac.createGain();
+  dry_gain.connect(mix);
+  wet_gain.connect(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'];
@@ -311,14 +320,17 @@ export function getVibratoOscillator(param, value, t) {
   const { vibmod = 0.5, vib } = value;
   let vibratoOscillator;
   if (vib > 0) {
-    const ag = getAudioGraph();
     vibratoOscillator = getAudioContext().createOscillator();
     vibratoOscillator.frequency.value = vib;
     const gain = getAudioContext().createGain();
     // Vibmod is the amount of vibrato, in semitones
     gain.gain.value = vibmod * 100;
-    ag.connect(vibratoOscillator, gain);
-    ag.connect(gain, param);
+    vibratoOscillator.connect(gain);
+    gain.connect(param);
+    onceEnded(vibratoOscillator, () => {
+      releaseAudioNode(gain);
+      releaseAudioNode(vibratoOscillator);
+    });
     vibratoOscillator.start(t);
     return vibratoOscillator;
   }
@@ -374,7 +386,7 @@ const fm = (frequencyparam, harmonicityRatio, wave = 'sine') => {
 
 export function applyFM(param, value, begin) {
   const ac = getAudioContext();
-  const ag = getAudioGraph();
+  const toStop = []; // fm oscillators we will expose `stop` for
   const fms = {};
   // Matrix
   for (let i = 1; i <= 8; i++) {
@@ -401,6 +413,8 @@ export function applyFM(param, value, begin) {
         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)) {
@@ -420,13 +434,15 @@ export function applyFM(param, value, begin) {
               holdEnd,
               fmEnvelopeType === 'exp' ? 'exponential' : 'linear',
             );
-            output = ag.connect(osc, envGain);
+            toCleanup.push(envGain);
+            output = osc.connect(envGain);
           }
-          fms[idx] = { input: osc.frequency, output, freq };
+          fms[idx] = { input: osc.frequency, output, freq, osc, toCleanup };
         }
-        const { input, output, freq } = fms[idx];
+        const { input, output, freq, osc, toCleanup } = fms[idx];
         const g = gainNode(amt * freq);
-        io.push(isMod ? ag.connect(output, g) : input);
+        io.push(isMod ? output.connect(g) : input);
+        cleanupOnEnd(osc, [...toCleanup, g]);
       }
       if (!io[1]) {
         logger(
@@ -435,9 +451,12 @@ export function applyFM(param, value, begin) {
         );
         continue;
       }
-      ag.connect(io[0], io[1]);
+      io[0].connect(io[1]);
     }
   }
+  return {
+    stop: (t) => toStop.forEach((m) => m?.stop(t)),
+  };
 }
 
 // Saturation curves
@@ -549,3 +568,61 @@ export const getFrequencyFromValue = (value, defaultNote = 36) => {
   freq *= Math.pow(2, octave);
   return Number(freq);
 };
+
+// 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 (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/index.mjs

@@ -4,13 +4,12 @@ Copyright (C) 2022 Strudel contributors - see <https://codeberg.org/uzu/strudel/
 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/>.
 */
 
-export * from './audioContext.mjs';
-export * from './audioGraph.mjs';
-export * from './dspworklet.mjs';
-export * from './helpers.mjs';
-export * from './logger.mjs';
-export * from './sampler.mjs';
 export * from './superdough.mjs';
+export * from './sampler.mjs';
+export * from './helpers.mjs';
 export * from './synth.mjs';
-export * from './wavetable.mjs';
 export * from './zzfx.mjs';
+export * from './logger.mjs';
+export * from './dspworklet.mjs';
+export * from './audioContext.mjs';
+export * from './wavetable.mjs';

packages/superdough/noise.mjs

@@ -1,6 +1,5 @@
+import { drywet, onceEnded, releaseAudioNode } from './helpers.mjs';
 import { getAudioContext } from './audioContext.mjs';
-import { getAudioGraph, onceEnded, releaseAudioNode } from './audioGraph.mjs';
-import { drywet } from './helpers.mjs';
 
 let noiseCache = {};
 
@@ -64,17 +63,14 @@ export function getNoiseOscillator(type = 'white', t, density = 0.02) {
 }
 
 export function getNoiseMix(inputNode, wet, t) {
-  const ag = getAudioGraph();
   const noiseOscillator = getNoiseOscillator('pink', t);
-  const { subGraph, output } = ag.asSubGraph(() => {
-    return drywet(inputNode, noiseOscillator.node, wet);
-  });
+  const noiseMix = drywet(inputNode, noiseOscillator.node, wet);
   onceEnded(noiseOscillator.node, () => {
     releaseAudioNode(noiseOscillator.node);
   });
   return {
-    node: output.node,
+    node: noiseMix.node,
     stop: (time) => noiseOscillator?.stop(time),
-    teardown: subGraph.release,
+    teardown: noiseMix.teardown,
   };
 }

packages/superdough/sampler.mjs

@@ -1,8 +1,14 @@
-import { getAudioContext } from './audioContext.mjs';
-import { onceEnded, releaseAudioNode } from './audioGraph.mjs';
 import { getBaseURL, getCommonSampleInfo } from './util.mjs';
 import { registerSound, registerWaveTable } from './index.mjs';
-import { getADSRValues, getParamADSR, getPitchEnvelope, getVibratoOscillator } from './helpers.mjs';
+import { getAudioContext } from './audioContext.mjs';
+import {
+  getADSRValues,
+  getParamADSR,
+  getPitchEnvelope,
+  getVibratoOscillator,
+  onceEnded,
+  releaseAudioNode,
+} from './helpers.mjs';
 import { logger } from './logger.mjs';
 
 const bufferCache = {}; // string: Promise<ArrayBuffer>

packages/superdough/superdough.mjs

@@ -9,12 +9,20 @@ 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 { releaseAudioNode } from './audioGraph.mjs';
 import { SuperdoughAudioController } from './superdoughoutput.mjs';
 
 export const DEFAULT_MAX_POLYPHONY = 128;

packages/superdough/synth.mjs

@@ -1,7 +1,6 @@
 import { clamp } from './util.mjs';
 import { registerSound, soundMap } from './superdough.mjs';
 import { getAudioContext } from './audioContext.mjs';
-import { getAudioGraph, onceEnded, releaseAudioNode } from './audioGraph.mjs';
 import {
   applyFM,
   gainNode,
@@ -13,6 +12,8 @@ import {
   getVibratoOscillator,
   getWorklet,
   noises,
+  onceEnded,
+  releaseAudioNode,
   webAudioTimeout,
 } from './helpers.mjs';
 import { logger } from './logger.mjs';
@@ -477,25 +478,34 @@ export function getOscillator(s, t, value, onended) {
   }
   // set frequency
   o.frequency.value = getFrequencyFromValue(value);
-  const ag = getAudioGraph();
-  const { subGraph, output } = ag.asSubGraph(() => {
-    getVibratoOscillator(o.detune, value, t);
-    // pitch envelope
-    getPitchEnvelope(o.detune, value, t, t + duration);
-    applyFM(o.frequency, value, t);
-    let noiseMix;
-    if (noise) {
-      noiseMix = getNoiseMix(o, noise, t);
-    }
-    return { node: noiseMix?.node || o };
-  });
 
-  onceEnded(o, () => subGraph.release());
+  let vibratoOscillator = getVibratoOscillator(o.detune, value, t);
+
+  // pitch envelope
+  getPitchEnvelope(o.detune, value, t, t + duration);
+  const fmModulator = applyFM(o.frequency, value, t);
+
+  let noiseMix;
+  if (noise) {
+    noiseMix = getNoiseMix(o, noise, t);
+  }
+
+  onceEnded(o, () => {
+    noiseMix?.teardown();
+    releaseAudioNode(o);
+    releaseAudioNode(noiseMix?.node);
+    onended();
+  });
   o.start(t);
 
   return {
-    node: output.node,
-    stop: (time) => o.stop(time),
+    node: noiseMix?.node || o,
+    stop: (time) => {
+      fmModulator.stop(time);
+      vibratoOscillator?.stop(time);
+      noiseMix?.stop(time);
+      o.stop(time);
+    },
     triggerRelease: (time) => {
       // envGain?.stop(time);
     },

packages/superdough/wavetable.mjs

@@ -1,4 +1,3 @@
-import { releaseAudioNode } from './audioGraph.mjs';
 import { getAudioContext, registerSound } from './index.mjs';
 import { getBaseURL, getCommonSampleInfo } from './util.mjs';
 import {
@@ -10,6 +9,7 @@ import {
   getPitchEnvelope,
   getVibratoOscillator,
   getWorklet,
+  releaseAudioNode,
   webAudioTimeout,
 } from './helpers.mjs';
 import { logger } from './logger.mjs';

packages/superdough/zzfx.mjs

@@ -1,9 +1,9 @@
 //import { ZZFX } from 'zzfx';
-import { getAudioContext } from './audioContext.mjs';
-import { onceEnded, releaseAudioNode } from './audioGraph.mjs';
-import { registerSound } from './superdough.mjs';
 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 {