v0.3.0

Author: shakfu

CHANGELOG.md

@@ -6,8 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.0]
+
 ### Added
 
+- **Web Audio runtime buffer loading** -- The `webaudio` backend can now fill gen~ buffers with sample data at runtime. New Emscripten exports (`wa_load_buffer`, `wa_get_num_buffers`, `wa_get_buffer_name`) are backed by a genlib-side `wrapper_load_buffer()` that copies interleaved float samples into the `WebaudioBuffer` instances. The AudioWorklet (`processor.js`) handles a `load-buffer` message (queued until the WASM module is ready, then applied between render quanta), and the generated `index.html` adds a file input per buffer that decodes an audio file via `decodeAudioData()` and posts the samples to the worklet. Previously buffers were allocated but unfillable, so buffer-backed patches (sample players, wavetables) ran silent; effects and parameter-driven generators were unaffected. Covered by a Node.js round-trip integration test (`test_buffer_loading_rampleplayer`).
+
 - **GDSP DSL `split()` / `merge()` composition** -- The fan-out/fan-in combinators are now callable from `.gdsp` source (previously available only via the Python `gen_dsp.graph.algebra` API). They accept two graph operands (graph references, partially-applied graph calls, or nested compositions), compose with `>>` and `//`, and lower to a `Subgraph` wrapping the composed graph. `split(a, b)` distributes `a`'s outputs cyclically across `b`'s inputs (requires `len(b.inputs) % len(a.outputs) == 0`); `merge(a, b)` sums groups of `a`'s outputs into `b`'s inputs (requires `len(a.outputs) % len(b.inputs) == 0`).
 
 - **GDSP DSL external file imports** -- `name = import "file.gdsp":graph(input=..., param=...)` references a graph defined in another `.gdsp` file and instantiates it as a `Subgraph`, with the same keyword-only argument rules as an in-source subgraph call. The graph name may be omitted when the target file defines exactly one graph. Relative paths resolve against the importing file's directory (the current working directory for string sources); each file is parsed and compiled at most once per top-level compilation (shared module cache, so diamond imports reuse the result); and import cycles -- direct (`a -> a`) or transitive (`a -> b -> a`) -- raise a `GDSPCompileError` reporting the chain instead of recursing without bound. This supersedes the deliberate "external imports are not supported" error added in 0.2.0.

TODO.md

@@ -8,10 +8,13 @@ gen-dsp can be consumed as a library by [dsp-graph](https://github.com/shakfu/ds
 
 ### Web Audio backend follow-ups
 
-- [ ] **Web Audio runtime buffer loading** -- The `webaudio` backend now generates
-  `gen_buffer.h` from `manifest.buffers` (header wiring done), but has no runtime path to
-  fill those buffers. Browser file loading is async and browser-specific; needs a
-  `wa_load_buffer()` Emscripten export + JS-side `fetch()` + `decodeAudioData()` bridge.
+- [x] **Web Audio runtime buffer loading** -- Done: added `wa_load_buffer` /
+  `wa_get_num_buffers` / `wa_get_buffer_name` Emscripten exports backed by a genlib-side
+  `wrapper_load_buffer()` (writes interleaved samples into the `WebaudioBuffer` instances).
+  The worklet (`processor.js`) handles a `load-buffer` message (queued until the WASM is
+  ready), and `index.html` provides a per-buffer file input that decodes audio via
+  `decodeAudioData()` and posts the samples to the worklet. Verified end-to-end (emcc build +
+  Node round-trip) by `test_buffer_loading_rampleplayer`.
 
 - [ ] **Web Audio build integration tests** -- Currently gated by `emcc` availability (skipped
   in CI). Consider adding Emscripten to CI or a lightweight WASM validation step.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gen-dsp"
-version = "0.2.0"
+version = "0.3.0"
 description = "Generate multiple dsp plugin formats from Max gen~ exports"
 readme = "README.md"
 license = "MIT"

src/gen_dsp/platforms/webaudio.py

@@ -123,6 +123,7 @@ def generate_project(
             num_params=str(len(manifest.params)),
             param_descriptors=json.dumps(param_descriptors, indent=4),
             num_outputs_array=num_outputs_array,
+            buffer_names=json.dumps(manifest.buffers),
         )
 
     @staticmethod
@@ -236,6 +237,7 @@ def _write_graph_platform_files(
             num_params=str(len(manifest.params)),
             param_descriptors=json.dumps(param_descriptors, indent=4),
             num_outputs_array=num_outputs_array,
+            buffer_names=json.dumps(manifest.buffers),
         )
 
     def build(

src/gen_dsp/templates/webaudio/Makefile.template

@@ -33,7 +33,7 @@ EMFLAGS = -O2 \
     -s MODULARIZE=1 \
     -s EXPORT_NAME='$export_name' \
     -s ENVIRONMENT='web,worker,node' \
-    -s EXPORTED_FUNCTIONS='["_wa_create","_wa_destroy","_wa_perform","_wa_get_num_inputs","_wa_get_num_outputs","_wa_get_num_params","_wa_set_param","_wa_get_param","_wa_get_param_name","_wa_get_param_min","_wa_get_param_max","_wa_get_param_default","_malloc","_free"]' \
+    -s EXPORTED_FUNCTIONS='["_wa_create","_wa_destroy","_wa_perform","_wa_get_num_inputs","_wa_get_num_outputs","_wa_get_num_params","_wa_set_param","_wa_get_param","_wa_get_param_name","_wa_get_param_min","_wa_get_param_max","_wa_get_param_default","_wa_get_num_buffers","_wa_get_buffer_name","_wa_load_buffer","_malloc","_free"]' \
     -s EXPORTED_RUNTIME_METHODS='["cwrap","UTF8ToString","HEAPU32","HEAPF32"]'
 
 BUILD_DIR = build

src/gen_dsp/templates/webaudio/_ext_webaudio.cpp

@@ -230,4 +230,57 @@ const char* wrapper_buffer_name(int index) {
     return nullptr;
 }
 
+// Pointers to the buffer instances, parallel to buffer_names[] above so that
+// wrapper_load_buffer() can address a buffer by the same index the JS side
+// discovers via wrapper_num_buffers()/wrapper_buffer_name().
+static WebaudioBuffer* buffer_ptrs[] = {
+#ifdef WRAPPER_BUFFER_NAME_0
+    &WRAPPER_BUFFER_NAME_0,
+#endif
+#ifdef WRAPPER_BUFFER_NAME_1
+    &WRAPPER_BUFFER_NAME_1,
+#endif
+#ifdef WRAPPER_BUFFER_NAME_2
+    &WRAPPER_BUFFER_NAME_2,
+#endif
+#ifdef WRAPPER_BUFFER_NAME_3
+    &WRAPPER_BUFFER_NAME_3,
+#endif
+#ifdef WRAPPER_BUFFER_NAME_4
+    &WRAPPER_BUFFER_NAME_4,
+#endif
+#ifdef WRAPPER_BUFFER_NAME_5
+    &WRAPPER_BUFFER_NAME_5,
+#endif
+#ifdef WRAPPER_BUFFER_NAME_6
+    &WRAPPER_BUFFER_NAME_6,
+#endif
+#ifdef WRAPPER_BUFFER_NAME_7
+    &WRAPPER_BUFFER_NAME_7,
+#endif
+    nullptr
+};
+
+// Fill buffer `index` with `frames * channels` interleaved (frame-major) float
+// samples. Reallocates the buffer to the given size; runs on the audio thread
+// between render quanta (the Worklet serializes port messages with process()),
+// so no locking is needed.
+void wrapper_load_buffer(int index, const float* data, long frames, long channels) {
+    if (index < 0 || index >= WRAPPER_BUFFER_COUNT || data == nullptr) {
+        return;
+    }
+    if (frames < 0) frames = 0;
+    if (channels < 1) channels = 1;
+    WebaudioBuffer* buf = buffer_ptrs[index];
+    if (buf == nullptr) {
+        return;
+    }
+    buf->allocate(frames, channels);
+    for (long i = 0; i < frames; i++) {
+        for (long c = 0; c < channels; c++) {
+            buf->write(data[i * channels + c], i, c);
+        }
+    }
+}
+
 } // namespace WRAPPER_NAMESPACE

src/gen_dsp/templates/webaudio/gen_ext_common_webaudio.h

@@ -17,4 +17,12 @@
 // Namespace for wrapper functions (isolates genlib from Emscripten bridge)
 #define WRAPPER_NAMESPACE WRAPPER_FUN2(WEBAUDIO_EXT_NAME, _webaudio)
 
+// Web Audio buffer loading: defined on the genlib side in _ext_webaudio.cpp and
+// called from the Emscripten bridge. Copies `frames * channels` interleaved
+// float32 samples (frame-major) into the buffer at `index`. Declared here so it
+// is visible to both sides without exposing genlib's WebaudioBuffer type.
+namespace WRAPPER_NAMESPACE {
+void wrapper_load_buffer(int index, const float* data, long frames, long channels);
+}
+
 #endif // GEN_EXT_COMMON_WEBAUDIO_H

src/gen_dsp/templates/webaudio/gen_ext_webaudio.cpp.template

@@ -76,4 +76,20 @@ float wa_get_param_default(int state_ptr, int index) {
     return wrapper_get_param((GenState*)(intptr_t)state_ptr, index);
 }
 
+EMSCRIPTEN_KEEPALIVE
+int wa_get_num_buffers() {
+    return wrapper_num_buffers();
+}
+
+EMSCRIPTEN_KEEPALIVE
+const char* wa_get_buffer_name(int index) {
+    return wrapper_buffer_name(index);
+}
+
+EMSCRIPTEN_KEEPALIVE
+void wa_load_buffer(int index, int data_ptr, int frames, int channels) {
+    const float* data = (const float*)(intptr_t)data_ptr;
+    wrapper_load_buffer(index, data, (long)frames, (long)channels);
+}
+
 } // extern "C"

src/gen_dsp/templates/webaudio/index.html.template

@@ -58,18 +58,53 @@ button.active { background: #e94560; border-color: #e94560; color: #fff; }
     <div class="subtitle">$num_inputs in / $num_outputs out | $num_params params | gen-dsp webaudio</div>
     <button id="toggle" onclick="toggleAudio()">Start Audio</button>
     <div id="params"></div>
+    <div id="buffers"></div>
     <div id="status">Click Start to initialize Web Audio.</div>
 </div>
 <script>
 const LIB_NAME = '$lib_name';
 const NUM_INPUTS = $num_inputs;
 const NUM_OUTPUTS = $num_outputs;
 const PARAMS = $param_descriptors;
+const BUFFER_NAMES = $buffer_names;
 
 let ctx = null;
 let workletNode = null;
 let running = false;
 let sourceNode = null;
+// Buffer files chosen before audio starts; applied once the worklet exists.
+const pendingBufferFiles = {};
+
+// Decode an audio file and load it into gen~ buffer `index`. decodeAudioData
+// is main-thread only, so we decode here and post the samples to the worklet.
+async function loadBufferIntoNode(index, file) {
+    if (!ctx || !workletNode) {
+        pendingBufferFiles[index] = file;
+        document.getElementById('status').textContent =
+            'Buffer "' + BUFFER_NAMES[index] + '" queued; loads when audio starts.';
+        return;
+    }
+    const arrayBuf = await file.arrayBuffer();
+    const audioBuf = await ctx.decodeAudioData(arrayBuf);
+    const frames = audioBuf.length;
+    const channels = audioBuf.numberOfChannels;
+    // Interleave (frame-major) to match the gen~ buffer storage layout.
+    const interleaved = new Float32Array(frames * channels);
+    for (let c = 0; c < channels; c++) {
+        const cd = audioBuf.getChannelData(c);
+        for (let i = 0; i < frames; i++) {
+            interleaved[i * channels + c] = cd[i];
+        }
+    }
+    workletNode.port.postMessage(
+        { type: 'load-buffer', index: index, frames: frames,
+          channels: channels, data: interleaved },
+        [interleaved.buffer]
+    );
+    document.getElementById('status').textContent =
+        'Loaded "' + BUFFER_NAMES[index] + '": ' + frames + ' frames, ' +
+        channels + ' ch.';
+}
 
 async function toggleAudio() {
     const btn = document.getElementById('toggle');
@@ -154,6 +189,13 @@ async function toggleAudio() {
                 });
             }
         }
+
+        // Apply any buffer files chosen before audio started.
+        for (const idx of Object.keys(pendingBufferFiles)) {
+            const f = pendingBufferFiles[idx];
+            delete pendingBufferFiles[idx];
+            await loadBufferIntoNode(parseInt(idx, 10), f);
+        }
     } catch (err) {
         document.getElementById('status').textContent = 'Error: ' + err.message;
         console.error(err);
@@ -174,6 +216,27 @@ for (const p of PARAMS) {
         p.defaultValue.toFixed(3) + '</span>';
     paramsDiv.appendChild(div);
 }
+
+// Build buffer file-input UI (one per gen~ buffer)
+const buffersDiv = document.getElementById('buffers');
+for (let i = 0; i < BUFFER_NAMES.length; i++) {
+    const div = document.createElement('div');
+    div.className = 'param';
+    div.innerHTML =
+        '<label>' + BUFFER_NAMES[i] + '</label>' +
+        '<input type="file" accept="audio/*" id="buf-' + i + '">';
+    buffersDiv.appendChild(div);
+    (function(idx) {
+        document.getElementById('buf-' + idx).addEventListener('change', (e) => {
+            if (e.target.files && e.target.files[0]) {
+                loadBufferIntoNode(idx, e.target.files[0]).catch((err) => {
+                    document.getElementById('status').textContent =
+                        'Buffer load error: ' + err.message;
+                });
+            }
+        });
+    })(i);
+}
 </script>
 </body>
 </html>

src/gen_dsp/templates/webaudio/processor.js.template

@@ -32,11 +32,14 @@ class $processor_class extends AudioWorkletProcessor {
         this._inBufs = [];
         this._outBufs = [];
         this._mod = null;
+        this._pendingBuffers = [];
 
-        // Wait for the main thread to send the WASM binary
+        // Wait for the main thread to send the WASM binary and buffer data.
         this.port.onmessage = (e) => {
             if (e.data.type === 'wasm-binary') {
                 this._loadWasm(e.data.binary);
+            } else if (e.data.type === 'load-buffer') {
+                this._loadBuffer(e.data);
             }
         };
     }
@@ -49,12 +52,35 @@ class $processor_class extends AudioWorkletProcessor {
             this._mod = await $export_name({ wasmBinary: wasmBinary });
             this._initDsp();
             this._ready = true;
+            // Apply any buffers that arrived before the module finished loading.
+            const pending = this._pendingBuffers;
+            this._pendingBuffers = [];
+            for (const msg of pending) {
+                this._loadBuffer(msg);
+            }
             this.port.postMessage({ type: 'ready' });
         } catch (err) {
             this.port.postMessage({ type: 'error', message: err.message });
         }
     }
 
+    // Copy interleaved (frame-major) float32 sample data into a gen~ buffer.
+    // Runs on the audio thread between render quanta, so it is safe to
+    // reallocate the buffer here without locking.
+    _loadBuffer(msg) {
+        if (!this._ready) {
+            this._pendingBuffers.push(msg);
+            return;
+        }
+        const m = this._mod;
+        const data = msg.data;
+        if (!data || data.length === 0) return;
+        const ptr = m._malloc(data.length * 4);
+        m.HEAPF32.set(data, ptr / 4);
+        m._wa_load_buffer(msg.index, ptr, msg.frames, msg.channels);
+        m._free(ptr);
+    }
+
     _initDsp() {
         const m = this._mod;
         const sr = sampleRate;