supersonic-scsynth 0.4.0 → 0.5.0

package/dist/supersonic.js

@@ -1605,6 +1605,504 @@ var __blockSelfAddress = (dataAddress) => dataAddress > 0 ? dataAddress - SIZEOF
 var NTP_EPOCH_OFFSET = 2208988800;
 var DRIFT_UPDATE_INTERVAL_MS = 15e3;
 
+// js/memory_layout.js
+var MemoryLayout = {
+  /**
+   * Total WebAssembly memory in pages (1 page = 64KB)
+   * Current: 1536 pages = 96MB
+   *
+   * This value is used by build.sh to set -sINITIAL_MEMORY
+   * Must match: totalPages * 65536 = bufferPoolOffset + bufferPoolSize
+   */
+  totalPages: 1536,
+  /**
+   * WASM heap size (implicit, first section of memory)
+   * Not directly configurable here - defined by bufferPoolOffset - ringBufferReserved
+   * Current: 0-32MB (32 * 1024 * 1024 = 33554432 bytes)
+   */
+  // wasmHeapSize is implicitly: bufferPoolOffset - ringBufferReserved
+  /**
+   * Ring buffer reserved space (between WASM heap and buffer pool)
+   * Actual ring buffer usage: IN: 768KB, OUT: 128KB, DEBUG: 64KB = 960KB
+   * Plus control structures: CONTROL_SIZE (40B) + METRICS_SIZE (48B) + NTP_START_TIME_SIZE (8B) ≈ 96B
+   * Total actual usage: ~960KB
+   * Reserved: 1MB (provides ~64KB headroom for alignment and future expansion)
+   * Current: 1MB reserved (starts where WASM heap ends at 32MB)
+   */
+  ringBufferReserved: 1 * 1024 * 1024,
+  // 1MB reserved
+  /**
+   * Buffer pool byte offset from start of SharedArrayBuffer
+   * Audio samples are allocated from this pool using @thi.ng/malloc
+   * Must be after WASM heap + ring buffer area
+   * Current: 33MB offset = after 32MB heap + 1MB ring buffers
+   */
+  bufferPoolOffset: 33 * 1024 * 1024,
+  // 34603008 bytes
+  /**
+   * Buffer pool size in bytes
+   * Used for audio sample storage (loaded files + allocated buffers)
+   * Current: 63MB (enough for ~3.5 minutes of stereo at 48kHz uncompressed)
+   */
+  bufferPoolSize: 63 * 1024 * 1024,
+  // 66060288 bytes
+  /**
+   * Total memory calculation (should equal totalPages * 65536)
+   * wasmHeap (32MB) + ringReserve (1MB) + bufferPool (63MB) = 96MB
+   */
+  get totalMemory() {
+    return this.bufferPoolOffset + this.bufferPoolSize;
+  },
+  /**
+   * Effective WASM heap size (derived)
+   * This is the space available for scsynth C++ allocations
+   */
+  get wasmHeapSize() {
+    return this.bufferPoolOffset - this.ringBufferReserved;
+  }
+};
+
+// js/scsynth_options.js
+var worldOptions = {
+  /**
+   * Maximum number of audio buffers (SndBuf slots)
+   * Each buffer slot: 104 bytes overhead (2x SndBuf + SndBufUpdates structs)
+   * Actual audio data is stored in buffer pool (separate from heap)
+   * Default: 1024 (matching SuperCollider default)
+   * Range: 1-65535 (limited by practical memory constraints)
+   */
+  numBuffers: 1024,
+  /**
+   * Maximum number of synthesis nodes (synths + groups)
+   * Each node: ~200-500 bytes depending on synth complexity
+   * Default: 1024 (matching SuperCollider default)
+   */
+  maxNodes: 1024,
+  /**
+   * Maximum number of synth definitions (SynthDef count)
+   * Each definition: variable size (typically 1-10KB)
+   * Default: 1024 (matching SuperCollider default)
+   */
+  maxGraphDefs: 1024,
+  /**
+   * Maximum wire buffers for internal audio routing
+   * Wire buffers: temporary buffers for UGen connections
+   * Each: bufLength * 8 bytes (128 samples * 8 = 1024 bytes)
+   * Default: 64 (matching SuperCollider default)
+   */
+  maxWireBufs: 64,
+  /**
+   * Number of audio bus channels
+   * Audio buses: real-time audio routing between synths
+   * Memory: bufLength * numChannels * 4 bytes (128 * 128 * 4 = 64KB)
+   * Default: 128 (SuperSonic default, SC uses 1024)
+   */
+  numAudioBusChannels: 128,
+  /**
+   * Number of input bus channels (hardware audio input)
+   * WebAudio/AudioWorklet input
+   * Default: 0 (no input in current SuperSonic implementation)
+   */
+  numInputBusChannels: 0,
+  /**
+   * Number of output bus channels (hardware audio output)
+   * WebAudio/AudioWorklet output
+   * Default: 2 (stereo)
+   */
+  numOutputBusChannels: 2,
+  /**
+   * Number of control bus channels
+   * Control buses: control-rate data sharing between synths
+   * Memory: numChannels * 4 bytes (4096 * 4 = 16KB)
+   * Default: 4096 (SuperSonic default, SC uses 16384)
+   */
+  numControlBusChannels: 4096,
+  /**
+   * Audio buffer length in samples (AudioWorklet quantum)
+   *
+   * FIXED VALUE - DO NOT CHANGE
+   * This MUST be 128 for AudioWorklet compatibility (WebAudio API spec).
+   *
+   * Unlike SuperCollider (where bufLength can be 32, 64, 128, etc.),
+   * SuperSonic is locked to 128 because AudioWorklet has a fixed quantum size.
+   *
+   * This value is kept in the config for:
+   * 1. Documentation (shows what value SuperSonic uses)
+   * 2. Passing to C++ code (required by WorldOptions)
+   * 3. Validation (catches accidental changes)
+   *
+   * If you provide this in your config, it MUST be 128 or initialization will fail.
+   * It's recommended to omit this field entirely and let the default be used.
+   *
+   * Default: 128 (fixed, cannot be changed)
+   */
+  bufLength: 128,
+  /**
+   * Real-time memory pool size in kilobytes
+   * AllocPool for synthesis-time allocations (UGen memory, etc.)
+   * This is the largest single allocation from WASM heap
+   * Memory: realTimeMemorySize * 1024 bytes (16384 * 1024 = 16MB)
+   * Default: 16384 KB (16MB, SuperSonic default, SC uses 8192 = 8MB)
+   */
+  realTimeMemorySize: 16384,
+  /**
+   * Number of random number generators
+   * Each synth can have its own RNG for reproducible randomness
+   * Default: 64 (matching SuperCollider default)
+   */
+  numRGens: 64,
+  /**
+   * Real-time mode flag
+   * false = Non-real-time (NRT) mode, externally driven by AudioWorklet
+   * true = Real-time mode (not used in WebAudio context)
+   * Default: false (SuperSonic always uses NRT mode)
+   */
+  realTime: false,
+  /**
+   * Memory locking (mlock)
+   * Not applicable in WebAssembly/browser environment
+   * Default: false
+   */
+  memoryLocking: false,
+  /**
+   * Auto-load SynthDefs from disk
+   * 0 = don't auto-load (synths sent via /d_recv)
+   * 1 = auto-load from plugin path
+   * Default: 0 (SuperSonic loads synthdefs via network)
+   */
+  loadGraphDefs: 0,
+  /**
+   * Preferred sample rate (if not specified, uses AudioContext.sampleRate)
+   * Common values: 44100, 48000, 96000
+   * Default: 0 (use AudioContext default, typically 48000)
+   */
+  preferredSampleRate: 0,
+  /**
+   * Debug verbosity level
+   * 0 = quiet, 1 = errors, 2 = warnings, 3 = info, 4 = debug
+   * Default: 0
+   */
+  verbosity: 0
+};
+var ScsynthConfig = {
+  memory: MemoryLayout,
+  worldOptions
+};
+
+// js/lib/config_validator.js
+var ConfigValidator = class {
+  /**
+   * Validate worldOptions for common errors
+   * @param {Object} worldOptions - WorldOptions to validate
+   * @param {Object} memoryConfig - Memory layout configuration
+   * @throws {Error} If validation fails with helpful message
+   */
+  static validateWorldOptions(worldOptions2, memoryConfig) {
+    if (!worldOptions2 || typeof worldOptions2 !== "object") {
+      throw new Error("worldOptions must be an object");
+    }
+    const numericFields = [
+      "numBuffers",
+      "maxNodes",
+      "maxGraphDefs",
+      "maxWireBufs",
+      "numAudioBusChannels",
+      "numInputBusChannels",
+      "numOutputBusChannels",
+      "numControlBusChannels",
+      "bufLength",
+      "realTimeMemorySize",
+      "numRGens",
+      "verbosity",
+      "preferredSampleRate",
+      "loadGraphDefs"
+    ];
+    const canBeZero = /* @__PURE__ */ new Set([
+      "numInputBusChannels",
+      // 0 = no audio inputs (valid for synthesis-only)
+      "numOutputBusChannels",
+      // 0 = no audio outputs (unusual but valid)
+      "verbosity",
+      // 0 = no verbose output
+      "preferredSampleRate",
+      // 0 = auto-detect sample rate
+      "loadGraphDefs"
+      // 0 = don't auto-load SynthDefs from disk
+    ]);
+    for (const field of numericFields) {
+      if (field in worldOptions2) {
+        const value = worldOptions2[field];
+        if (!Number.isFinite(value)) {
+          throw new Error(
+            `worldOptions.${field} must be a finite number, got ${typeof value}: ${value}`
+          );
+        }
+        const minValue = canBeZero.has(field) ? 0 : 1;
+        if (value < minValue) {
+          throw new Error(
+            `worldOptions.${field} must be ${minValue > 0 ? "positive" : "non-negative"}, got ${value}`
+          );
+        }
+        const maxValue = this.#getMaxValueFor(field);
+        if (value > maxValue) {
+          throw new Error(
+            `worldOptions.${field} exceeds reasonable maximum.
+  Got: ${value}
+  Max: ${maxValue}
+This may indicate a configuration error.`
+          );
+        }
+      }
+    }
+    if ("bufLength" in worldOptions2 && worldOptions2.bufLength !== 128) {
+      throw new Error(
+        `worldOptions.bufLength must be 128 (AudioWorklet quantum size).
+  Got: ${worldOptions2.bufLength}
+This value cannot be changed as it's defined by the Web Audio API.
+Remove 'bufLength' from your configuration.`
+      );
+    }
+    const booleanFields = ["realTime", "memoryLocking"];
+    for (const field of booleanFields) {
+      if (field in worldOptions2 && typeof worldOptions2[field] !== "boolean") {
+        throw new Error(
+          `worldOptions.${field} must be a boolean, got ${typeof worldOptions2[field]}`
+        );
+      }
+    }
+    if ("preferredSampleRate" in worldOptions2) {
+      const rate = worldOptions2.preferredSampleRate;
+      if (rate !== 0 && !Number.isFinite(rate)) {
+        throw new Error(
+          `worldOptions.preferredSampleRate must be 0 (auto) or a finite number, got ${rate}`
+        );
+      }
+      if (rate !== 0 && (rate < 8e3 || rate > 192e3)) {
+        throw new Error(
+          `worldOptions.preferredSampleRate out of range: ${rate}
+Valid range: 8000-192000 Hz, or 0 for auto`
+        );
+      }
+    }
+    this.#validateCombinations(worldOptions2);
+    if (memoryConfig) {
+      const heapSize = memoryConfig.wasmHeapSize;
+      if (heapSize) {
+        MemoryEstimator.validateHeapFits(worldOptions2, heapSize);
+      }
+    }
+  }
+  /**
+   * Validate memory layout for coherence
+   * @param {Object} memory - Memory configuration
+   * @throws {Error} If layout is invalid
+   */
+  static validateMemoryLayout(memory) {
+    if (!memory || typeof memory !== "object") {
+      throw new Error("memory configuration must be an object");
+    }
+    const { totalPages, bufferPoolOffset, bufferPoolSize, ringBufferReserved } = memory;
+    if (!Number.isFinite(totalPages) || totalPages <= 0) {
+      throw new Error(
+        `memory.totalPages must be a positive number, got ${totalPages}`
+      );
+    }
+    if (!Number.isFinite(bufferPoolOffset) || bufferPoolOffset <= 0) {
+      throw new Error(
+        `memory.bufferPoolOffset must be a positive number, got ${bufferPoolOffset}`
+      );
+    }
+    if (!Number.isFinite(bufferPoolSize) || bufferPoolSize <= 0) {
+      throw new Error(
+        `memory.bufferPoolSize must be a positive number, got ${bufferPoolSize}`
+      );
+    }
+    const totalMemory = totalPages * 65536;
+    const expectedTotal = bufferPoolOffset + bufferPoolSize;
+    if (totalMemory !== expectedTotal) {
+      throw new Error(
+        `Memory layout mismatch:
+  totalPages * 65536 = ${totalMemory} bytes (${(totalMemory / 1024 / 1024).toFixed(0)}MB)
+  bufferPoolOffset + bufferPoolSize = ${expectedTotal} bytes (${(expectedTotal / 1024 / 1024).toFixed(0)}MB)
+These must be equal. Check your memory configuration.`
+      );
+    }
+    const minBufferPoolOffset = ringBufferReserved || 32 * 1024 * 1024;
+    if (bufferPoolOffset < minBufferPoolOffset) {
+      throw new Error(
+        `memory.bufferPoolOffset (${bufferPoolOffset}) is too small.
+  Must be at least: ${minBufferPoolOffset} bytes (${(minBufferPoolOffset / 1024 / 1024).toFixed(0)}MB)
+This is required to avoid collision with WASM heap and ring buffers.`
+      );
+    }
+    if (totalMemory > 512 * 1024 * 1024) {
+      console.warn(
+        `[SuperSonic] Warning: Total memory is ${(totalMemory / 1024 / 1024).toFixed(0)}MB.
+Large memory allocations may cause browser performance issues on some devices.`
+      );
+    }
+    const wasmHeapSize = memory.wasmHeapSize;
+    if (wasmHeapSize && wasmHeapSize < 16 * 1024 * 1024) {
+      console.warn(
+        `[SuperSonic] Warning: WASM heap is only ${(wasmHeapSize / 1024 / 1024).toFixed(0)}MB.
+This may be too small for typical usage. Consider increasing bufferPoolOffset.`
+      );
+    }
+  }
+  /**
+   * Get maximum reasonable value for a field
+   * Based on SuperCollider defaults and reasonable WASM/browser limits
+   * @private
+   */
+  static #getMaxValueFor(field) {
+    const limits = {
+      // SC default: 1024, All uint32 in SC_WorldOptions.h
+      // Limit to prevent excessive memory allocation
+      numBuffers: 65535,
+      maxNodes: 65535,
+      // SC default: 1024
+      maxGraphDefs: 65535,
+      // SC default: 1024
+      maxWireBufs: 2048,
+      // SC default: 64
+      // SC default: 1024 (NOT 128!)
+      // But we use lower for browser context
+      numAudioBusChannels: 4096,
+      numInputBusChannels: 256,
+      // SC default: 8
+      numOutputBusChannels: 256,
+      // SC default: 8
+      // SC default: 16384 (NOT 4096!)
+      numControlBusChannels: 65535,
+      bufLength: 128,
+      // Fixed for AudioWorklet (SC default: 64)
+      // SC default: 8192 KB (8MB)
+      // Limit to 1GB for browser safety
+      realTimeMemorySize: 1048576,
+      // KB (1GB max)
+      numRGens: 1024,
+      // SC default: 64
+      verbosity: 10,
+      preferredSampleRate: 192e3,
+      // Maximum sample rate
+      loadGraphDefs: 1
+      // SC default: 1, 0=off 1=on
+    };
+    return limits[field] || Number.MAX_SAFE_INTEGER;
+  }
+  /**
+   * Validate compatible combinations of options
+   * @private
+   */
+  static #validateCombinations(worldOptions2) {
+    if (worldOptions2.realTimeMemorySize && worldOptions2.realTimeMemorySize < 1024) {
+      console.warn(
+        `[SuperSonic] Warning: realTimeMemorySize is only ${worldOptions2.realTimeMemorySize}KB (${(worldOptions2.realTimeMemorySize / 1024).toFixed(1)}MB).
+This is very small and may cause allocation failures. Recommended minimum: 4096 KB (4MB).`
+      );
+    }
+    if (worldOptions2.numOutputBusChannels && worldOptions2.numOutputBusChannels > 8) {
+      console.warn(
+        `[SuperSonic] Warning: numOutputBusChannels is ${worldOptions2.numOutputBusChannels}.
+Most audio hardware supports 2-8 channels. Verify your AudioContext supports this.`
+      );
+    }
+  }
+};
+var MemoryEstimator = class {
+  /**
+   * Estimate WASM heap usage for given WorldOptions
+   * Returns breakdown of memory usage by component
+   *
+   * Based on actual SuperCollider source code allocations (SC_World.cpp, SC_Graph.cpp)
+   *
+   * @param {Object} worldOptions - Configuration to analyze
+   * @returns {Object} { total, breakdown: {...} }
+   */
+  static estimateHeapUsage(worldOptions2) {
+    const breakdown = {
+      // AllocPool for real-time synthesis (SC_World.cpp:328)
+      // new AllocPool(..., inOptions->mRealTimeMemorySize * 1024, 0)
+      realTimeMemory: worldOptions2.realTimeMemorySize * 1024,
+      // KB → bytes
+      // SndBuf arrays (SC_World.cpp:383-385)
+      // mSndBufs: sizeof(SndBuf) = 48 bytes (SC_SndBuf.h:152-168, WASM32 with 32-bit pointers)
+      // mSndBufsNonRealTimeMirror: sizeof(SndBuf) = 48 bytes
+      // mSndBufUpdates: sizeof(SndBufUpdates) = 8 bytes (2 × int32)
+      // Total: (48 + 48 + 8) * mNumBuffers = 104 bytes per buffer
+      sndBufs: worldOptions2.numBuffers * 104,
+      // Audio buses (SC_World.cpp:376-377)
+      // mAudioBus = zalloc(mBufLength * mNumAudioBusChannels, sizeof(float))
+      audioBuses: worldOptions2.numAudioBusChannels * worldOptions2.bufLength * 4,
+      // Audio bus touched flags (SC_World.cpp:379)
+      // mAudioBusTouched = zalloc(mNumAudioBusChannels, sizeof(int32))
+      audioBusTouched: worldOptions2.numAudioBusChannels * 4,
+      // Control buses (SC_World.cpp:370)
+      // mControlBus = zalloc(mNumControlBusChannels, sizeof(float))
+      controlBuses: worldOptions2.numControlBusChannels * 4,
+      // Control bus touched flags (SC_World.cpp:380)
+      // mControlBusTouched = zalloc(mNumControlBusChannels, sizeof(int32))
+      controlBusTouched: worldOptions2.numControlBusChannels * 4,
+      // Wire buffers (SC_World.cpp:917)
+      // mWireBufSpace = malloc_alig(mMaxWireBufs * mBufLength * sizeof(float))
+      wireBufs: worldOptions2.maxWireBufs * worldOptions2.bufLength * 4,
+      // Random number generators (SC_World.cpp:398)
+      // mRGen = new RGen[mNumRGens]
+      // sizeof(RGen) = 12 bytes (3 × uint32, SC_RGen.h:57-85)
+      rgens: worldOptions2.numRGens * 12,
+      // Node hash table (SC_World.cpp:334)
+      // IntHashTable<Node, AllocPool> with capacity mMaxNodes
+      // Conservative estimate: ~64 bytes per slot for hash table overhead
+      nodes: worldOptions2.maxNodes * 64,
+      // GraphDef hash table (SC_World.cpp:333)
+      // HashTable<GraphDef, Malloc> with capacity mMaxGraphDefs
+      // Conservative estimate: ~128 bytes per slot (varies per GraphDef)
+      graphDefs: worldOptions2.maxGraphDefs * 128,
+      // World struct, HiddenWorld, and other fixed overhead
+      // Includes: World struct, HiddenWorld struct, locks, semaphores, etc.
+      overhead: 2 * 1024 * 1024
+      // 2MB
+    };
+    const total = Object.values(breakdown).reduce((sum, val) => sum + val, 0);
+    return { total, breakdown };
+  }
+  /**
+   * Check if worldOptions fit within available heap
+   * @param {Object} worldOptions
+   * @param {number} heapSize - Available heap in bytes
+   * @throws {Error} If estimated usage exceeds heap
+   */
+  static validateHeapFits(worldOptions2, heapSize) {
+    const { total, breakdown } = this.estimateHeapUsage(worldOptions2);
+    if (total > heapSize) {
+      const totalMB = (total / (1024 * 1024)).toFixed(2);
+      const heapMB = (heapSize / (1024 * 1024)).toFixed(2);
+      const sorted = Object.entries(breakdown).sort(([, a], [, b]) => b - a).slice(0, 3).map(([key, bytes]) => `  ${key}: ${(bytes / (1024 * 1024)).toFixed(2)}MB`).join("\n");
+      throw new Error(
+        `WorldOptions estimated to use ${totalMB}MB but WASM heap is only ${heapMB}MB.
+
+Largest allocations:
+${sorted}
+
+To fix this error:
+1. Reduce realTimeMemorySize (currently ${worldOptions2.realTimeMemorySize}KB)
+2. Reduce numBuffers (currently ${worldOptions2.numBuffers})
+3. Reduce maxNodes (currently ${worldOptions2.maxNodes})
+4. Or: Increase WASM heap size (requires rebuild - see CONFIGURATION_PHASES.md Phase 4)`
+      );
+    }
+    const usagePercent = total / heapSize * 100;
+    if (usagePercent > 80) {
+      console.warn(
+        `[SuperSonic] Warning: Estimated heap usage is ${usagePercent.toFixed(0)}% of available space.
+  Used: ${(total / 1024 / 1024).toFixed(1)}MB
+  Available: ${(heapSize / 1024 / 1024).toFixed(1)}MB
+Consider reducing options or increasing heap size for safety margin.`
+      );
+    }
+  }
+};
+
 // js/supersonic.js
 var BufferManager = class {
   constructor(options) {
@@ -1614,7 +2112,8 @@ var BufferManager = class {
       bufferPool,
       allocatedBuffers,
       resolveAudioPath,
-      registerPendingOp
+      registerPendingOp,
+      maxBuffers = 1024
     } = options;
     this.audioContext = audioContext;
     this.sharedBuffer = sharedBuffer;
@@ -1625,7 +2124,7 @@ var BufferManager = class {
     this.bufferLocks = /* @__PURE__ */ new Map();
     this.GUARD_BEFORE = 3;
     this.GUARD_AFTER = 1;
-    this.MAX_BUFFERS = 1024;
+    this.MAX_BUFFERS = maxBuffers;
   }
   #validateBufferNumber(bufnum) {
     if (!Number.isInteger(bufnum) || bufnum < 0 || bufnum >= this.MAX_BUFFERS) {
@@ -1922,6 +2421,14 @@ var SuperSonic = class _SuperSonic {
     }
     const workerBaseURL = options.workerBaseURL;
     const wasmBaseURL = options.wasmBaseURL;
+    const scsynthConfig = this.#mergeScsynthOptions(options.scsynthOptions || {});
+    try {
+      ConfigValidator.validateWorldOptions(scsynthConfig.worldOptions, scsynthConfig.memory);
+      ConfigValidator.validateMemoryLayout(scsynthConfig.memory);
+    } catch (error) {
+      throw new Error(`SuperSonic configuration validation failed:
+${error.message}`);
+    }
     this.config = {
       wasmUrl: options.wasmUrl || wasmBaseURL + "scsynth-nrt.wasm",
       workletUrl: options.workletUrl || workerBaseURL + "scsynth_audio_worklet.js",
@@ -1931,7 +2438,9 @@ var SuperSonic = class _SuperSonic {
       audioContextOptions: {
         latencyHint: "interactive",
         sampleRate: 48e3
-      }
+      },
+      // scsynth configuration (merged defaults + user overrides)
+      scsynth: scsynthConfig
     };
     this.sampleBaseURL = options.sampleBaseURL || null;
     this.synthdefBaseURL = options.synthdefBaseURL || null;
@@ -1978,27 +2487,54 @@ var SuperSonic = class _SuperSonic {
     }
     return this.capabilities;
   }
+  /**
+   * Merge user-provided scsynth options with defaults
+   * @private
+   */
+  #mergeScsynthOptions(userOptions) {
+    const merged = {
+      memory: { ...ScsynthConfig.memory },
+      worldOptions: { ...ScsynthConfig.worldOptions }
+    };
+    if (userOptions.memory) {
+      Object.assign(merged.memory, userOptions.memory);
+    }
+    if (userOptions.worldOptions) {
+      Object.assign(merged.worldOptions, userOptions.worldOptions);
+    }
+    const topLevelKeys = Object.keys(userOptions).filter(
+      (key) => key !== "memory" && key !== "worldOptions"
+    );
+    if (topLevelKeys.length > 0) {
+      topLevelKeys.forEach((key) => {
+        if (key in merged.worldOptions) {
+          merged.worldOptions[key] = userOptions[key];
+        }
+      });
+    }
+    return merged;
+  }
   /**
    * Initialize shared WebAssembly memory
    */
   #initializeSharedMemory() {
-    const TOTAL_PAGES = 3072;
+    const memConfig = this.config.scsynth.memory;
     this.wasmMemory = new WebAssembly.Memory({
-      initial: TOTAL_PAGES,
-      maximum: TOTAL_PAGES,
+      initial: memConfig.totalPages,
+      maximum: memConfig.totalPages,
       shared: true
     });
     this.sharedBuffer = this.wasmMemory.buffer;
-    const BUFFER_POOL_OFFSET = 64 * 1024 * 1024;
-    const BUFFER_POOL_SIZE = 128 * 1024 * 1024;
     this.bufferPool = new MemPool({
       buf: this.sharedBuffer,
-      start: BUFFER_POOL_OFFSET,
-      size: BUFFER_POOL_SIZE,
+      start: memConfig.bufferPoolOffset,
+      size: memConfig.bufferPoolSize,
       align: 8
       // 8-byte alignment (minimum required by MemPool)
     });
-    console.log("[SuperSonic] Buffer pool initialized: 128MB at offset 64MB");
+    const poolSizeMB = (memConfig.bufferPoolSize / (1024 * 1024)).toFixed(0);
+    const poolOffsetMB = (memConfig.bufferPoolOffset / (1024 * 1024)).toFixed(0);
+    console.log(`[SuperSonic] Buffer pool initialized: ${poolSizeMB}MB at offset ${poolOffsetMB}MB`);
   }
   /**
    * Initialize AudioContext and set up time offset calculation
@@ -2028,7 +2564,8 @@ var SuperSonic = class _SuperSonic {
       bufferPool: this.bufferPool,
       allocatedBuffers: this.allocatedBuffers,
       resolveAudioPath: (path) => this._resolveAudioPath(path),
-      registerPendingOp: (uuid, bufnum, timeoutMs) => this.#createPendingBufferOperation(uuid, bufnum, timeoutMs)
+      registerPendingOp: (uuid, bufnum, timeoutMs) => this.#createPendingBufferOperation(uuid, bufnum, timeoutMs),
+      maxBuffers: this.config.scsynth.worldOptions.numBuffers
     });
   }
   /**
@@ -2079,7 +2616,10 @@ var SuperSonic = class _SuperSonic {
     this.workletNode.port.postMessage({
       type: "loadWasm",
       wasmBytes,
-      wasmMemory: this.wasmMemory
+      wasmMemory: this.wasmMemory,
+      worldOptions: this.config.scsynth.worldOptions,
+      sampleRate: this.audioContext.sampleRate
+      // Pass actual AudioContext sample rate
     });
     await this.#waitForWorkletInit();
   }
@@ -2426,6 +2966,24 @@ var SuperSonic = class _SuperSonic {
       audioContextState: this.audioContext?.state
     };
   }
+  /**
+   * Get current configuration (merged defaults + user overrides)
+   * Useful for debugging and displaying in UI
+   * @returns {Object} Current scsynth configuration
+   * @example
+   * const config = sonic.getConfig();
+   * console.log('Buffer limit:', config.worldOptions.numBuffers);
+   * console.log('Memory layout:', config.memory);
+   */
+  getConfig() {
+    if (!this.config?.scsynth) {
+      return null;
+    }
+    return {
+      memory: { ...this.config.scsynth.memory },
+      worldOptions: { ...this.config.scsynth.worldOptions }
+    };
+  }
   /**
    * Destroy the orchestrator and clean up resources
    */

package/dist/wasm/manifest.json

@@ -1,6 +1,6 @@
 {
   "wasmFile": "scsynth-nrt.wasm",
-  "buildId": "20251118-093603",
-  "buildTime": "2025-11-18T09:36:03Z",
-  "gitHash": "d43c4be"
+  "buildId": "20251120-122240",
+  "buildTime": "2025-11-20T12:22:40Z",
+  "gitHash": "5c5371aa09"
 }

package/dist/workers/scsynth_audio_worklet.js

@@ -143,6 +143,38 @@ class ScsynthProcessor extends AudioWorkletProcessor {
 
     }
 
+    // Write worldOptions to SharedArrayBuffer for C++ to read
+    // WorldOptions are written after ring buffer storage (65536 bytes)
+    writeWorldOptionsToMemory() {
+        if (!this.worldOptions || !this.wasmMemory) {
+            return;
+        }
+
+        // WorldOptions location: ringBufferBase + 65536 (after ring_buffer_storage)
+        const WORLD_OPTIONS_OFFSET = this.ringBufferBase + 65536;
+        const uint32View = new Uint32Array(this.wasmMemory.buffer, WORLD_OPTIONS_OFFSET, 32);
+        const float32View = new Float32Array(this.wasmMemory.buffer, WORLD_OPTIONS_OFFSET, 32);
+
+        // Write worldOptions as uint32/float32 values
+        // Order must match C++ reading code in audio_processor.cpp
+        uint32View[0] = this.worldOptions.numBuffers || 1024;
+        uint32View[1] = this.worldOptions.maxNodes || 1024;
+        uint32View[2] = this.worldOptions.maxGraphDefs || 1024;
+        uint32View[3] = this.worldOptions.maxWireBufs || 64;
+        uint32View[4] = this.worldOptions.numAudioBusChannels || 128;
+        uint32View[5] = this.worldOptions.numInputBusChannels || 0;
+        uint32View[6] = this.worldOptions.numOutputBusChannels || 2;
+        uint32View[7] = this.worldOptions.numControlBusChannels || 4096;
+        uint32View[8] = this.worldOptions.bufLength || 128;
+        uint32View[9] = this.worldOptions.realTimeMemorySize || 16384;
+        uint32View[10] = this.worldOptions.numRGens || 64;
+        uint32View[11] = this.worldOptions.realTime ? 1 : 0;
+        uint32View[12] = this.worldOptions.memoryLocking ? 1 : 0;
+        uint32View[13] = this.worldOptions.loadGraphDefs || 0;
+        uint32View[14] = this.worldOptions.preferredSampleRate || 0;
+        uint32View[15] = this.worldOptions.verbosity || 0;
+    }
+
     // Write debug message to SharedArrayBuffer DEBUG ring buffer
     js_debug(message) {
         if (!this.uint8View || !this.atomicView || !this.CONTROL_INDICES || !this.ringBufferBase) {
@@ -217,6 +249,10 @@ class ScsynthProcessor extends AudioWorkletProcessor {
                     // Save memory reference for later use (WASM imports memory, doesn't export it)
                     this.wasmMemory = memory;
 
+                    // Store worldOptions and sampleRate for C++ initialization
+                    this.worldOptions = data.worldOptions || {};
+                    this.sampleRate = data.sampleRate || 48000;  // Fallback to 48000 if not provided
+
                     // Import object for WASM
                     // scsynth with pthread support requires these imports
                     // (pthread stubs are no-ops - AudioWorklet is single-threaded)
@@ -271,9 +307,13 @@ class ScsynthProcessor extends AudioWorkletProcessor {
 
                         this.calculateBufferIndices(this.ringBufferBase);
 
+                        // Write worldOptions to SharedArrayBuffer for C++ to read
+                        this.writeWorldOptionsToMemory();
+
                         // Initialize WASM memory
                         if (this.wasmInstance.exports.init_memory) {
-                            this.wasmInstance.exports.init_memory(48000.0);
+                            // Pass actual sample rate from AudioContext (not hardcoded!)
+                            this.wasmInstance.exports.init_memory(this.sampleRate);
 
                             this.isInitialized = true;
 
@@ -299,9 +339,13 @@ class ScsynthProcessor extends AudioWorkletProcessor {
 
                         this.calculateBufferIndices(this.ringBufferBase);
 
+                        // Write worldOptions to SharedArrayBuffer for C++ to read
+                        this.writeWorldOptionsToMemory();
+
                         // Initialize WASM memory
                         if (this.wasmInstance.exports.init_memory) {
-                            this.wasmInstance.exports.init_memory(48000.0);
+                            // Pass actual sample rate from AudioContext (not hardcoded!)
+                            this.wasmInstance.exports.init_memory(this.sampleRate);
 
                             this.isInitialized = true;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supersonic-scsynth",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "SuperCollider scsynth WebAssembly port for AudioWorklet - Run SuperCollider synthesis in the browser",
   "main": "dist/supersonic.js",
   "unpkg": "dist/supersonic.js",