databender 1.0.4 → 2.0.0-alpha.1

package/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright 2018 Michael Vattuone
+Copyright 2025 Michael Vattuone
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,7 +1,5 @@
 # Databender
 
-**NOTE: This API may change wildly in v2... use at your own peril!**
-
 This module allows for generation interesting visuals by misusing the Web Audio API.
 Inspired by [David Byrne](https://www.youtube.com/watch?v=Gea9SYUdJeY) and [AudioShop](https://github.com/robertfoss/audio_shop/)
 
@@ -11,7 +9,7 @@ Full API documentation and such is _coming soon_.
 
 The quickest way to get _something_ on the page:
 
-- Run `npm i` in your project and make sure you have an image to point to somewhere.
+- Run `npm i databender` in your project and make sure you have an image to point to somewhere.
 - Paste the following snippet into `index.html` and point the image to the location of the image you'd like to bend.
 
 ```html
@@ -49,7 +47,7 @@ The quickest way to get _something_ on the page:
         value: 0.0
       }
     };
-    const databender = new Databender(config);
+    const databender = new Databender({ config });
     databender.bend(img, context);
   };
 
@@ -64,22 +62,125 @@ The quickest way to get _something_ on the page:
 - Start up a server (e.g. `python -m SimpleHTTPServer`)
 - Behold!
 
-You might also prefer using this in a CommonJS manner:
+Using an ES module aware bundler? You can import straight from npm:
 
 ```js
-const Databender = require("databender");
+import Databender from "databender";
+
+const databender = new Databender({ config });
 ```
 
-Since I am lazy, you'll need to deduce what config you want for each effect that is included by looking in the `effects` directory. At some point, this may be removed from the app, and it will be up to you to include whatever effects and dependencies you would like to use with your bent data.
+Need to stick with a classic `<script>` tag that isn't module friendly? `npm run build` will drop an IIFE bundle into `dist/databender.js` that exposes `window.Databender` just like before. Drop that bundle on the page and the snippet above will still work.
 
-### Prerequisites
+### Custom effect chains
 
-Google Chrome (ideally) and an open mind!
+You can inject any Web Audio nodes (Tone.js, Pizzicato, TunaJS, etc.) and they'll be chained in the order you provide. 
+
+```js
+import Databender from 'databender';
+
+const databender = new Databender({
+  effectsChain: [
+    ({ context }) => {
+      const filter = context.createBiquadFilter();
+      filter.type = 'lowpass';
+      filter.frequency.value = 400;
+      return filter;
+    },
+    ({ context }) => {
+      const gain = context.createGain();
+      gain.gain.value = 0.8;
+      return gain;
+    }
+  ]
+});
+
+databender.bend(img, context);
+```
+
+Effect factories can return plain nodes or promises that resolve to nodes. Databender waits on any promises before it starts rendering, which makes it possible to do async setup on the `OfflineAudioContext` (for example, loading an `AudioWorklet` module for each render).
 
-## Built With
+You can also decide how the chain is wired. By default every effect is connected in series. Pass `chainMode: 'parallel'` to fan the source out to each effect and feed each branch directly into the offline destination.
 
-- [TunaJS](https://github.com/Theodeus/tuna) - A splendid audio effects library.
-- [Rollup](https://github.com/rollup/rollup) - Module bundling
+#### Example: Pizzicato effects
+
+```js
+import Databender from 'databender';
+import Pizzicato from 'pizzicato';
+
+const swapPizzicatoContext = (EffectCtor, options) => ({ context }) => {
+  // swap pizzicato internal context=
+  const previous = Pizzicato.context;
+  Pizzicato.context = context;
+  const effect = new EffectCtor(options);
+  Pizzicato.context = previous;
+  return { input: effect.inputNode, output: effect.outputNode };
+};
+
+const databender = new Databender({
+  effectsChain: [
+    swapPizzicatoContext(Pizzicato.Effects.Delay, {
+      feedback: 0.6,
+      time: 0.4,
+      mix: 0.5
+    }),
+    swapPizzicatoContext(Pizzicato.Effects.LowPassFilter, {
+      frequency: 1200,
+      peak: 10,
+      mix: 0.4
+    })
+  ]
+});
+
+databender.bend(img, context);
+```
+
+(Note: `swapPizzicatoContext` is a tiny helper that swaps Pizzicato's internal context to the offline one Databender uses during rendering, then returns the effect's input/output nodes so Databender can connect it in sequence.)
+
+#### Example: AudioWorklet
+
+```js
+import Databender from 'databender';
+
+const useBitcrusher = async ({ context }) => {
+  await context.audioWorklet.addModule('/path/to/effects/bitcrusher.js');
+  return new AudioWorkletNode(context, 'bitcrusher');
+};
+
+const databender = new Databender({
+  config,
+  effectsChain: [useBitcrusher],
+  chainMode: 'parallel'
+});
+
+databender.bend(img, context);
+```
+
+Because Databender spins up a brand new `OfflineAudioContext` for every render, the worklet module has to be registered on that context before the node is created. Returning a promise from your effect factory ensures the render waits for the module to load.
+
+### Source parameters
+
+Some tweaks (e.g. `detune` or `playbackRate`) must be applied directly to the `AudioBufferSourceNode` **before** it starts. Pass functions to `sourceParams` and they'll run prior to chaining any effects. Each factory receives the same payload (`{ context, source, config }`) as the regular effect chain.
+
+```js
+const databender = new Databender({
+  config,
+  sourceParams: [
+    ({ source, config }) => {
+      const value = config?.detune?.value ?? 0;
+      source.detune.value = value;
+    }
+  ],
+  effectsChain: [
+    useDelayEffect(),
+    useBitcrusher()
+  ]
+});
+```
+
+### Prerequisites
+
+Google Chrome (ideally) and an open mind!
 
 ## Contributing