@guinetik/gcanvas 1.0.0

package/src/sound/synth.effects.js

@@ -0,0 +1,207 @@
+/**
+ * SynthEffects - Audio effects processing
+ * @module sound/synth.effects
+ */
+export class SynthEffects {
+  static #_ctx = null;
+  static #_output = null;
+
+  /**
+   * Initialize the effects module
+   * @param {AudioContext} ctx - Audio context
+   * @param {AudioNode} output - Output node
+   */
+  static init(ctx, output) {
+    this.#_ctx = ctx;
+    this.#_output = output;
+  }
+
+  /**
+   * Get the audio context
+   * @returns {AudioContext}
+   */
+  static get ctx() {
+    return this.#_ctx;
+  }
+
+  /**
+   * Create a filter node
+   * @param {string} [type='lowpass'] - Filter type
+   * @param {number} [frequency=1000] - Cutoff frequency
+   * @param {number} [q=1] - Q factor (resonance)
+   * @returns {BiquadFilterNode}
+   */
+  static filter(type = "lowpass", frequency = 1000, q = 1) {
+    const filter = this.#_ctx.createBiquadFilter();
+    filter.type = type;
+    filter.frequency.value = frequency;
+    filter.Q.value = q;
+    return filter;
+  }
+
+  /**
+   * Create a delay effect
+   * @param {number} [time=0.3] - Delay time in seconds
+   * @param {number} [feedback=0.4] - Feedback amount (0-1)
+   * @param {number} [mix=0.5] - Wet/dry mix (0-1)
+   * @returns {Object} Delay effect controller
+   */
+  static delay(time = 0.3, feedback = 0.4, mix = 0.5) {
+    const delay = this.#_ctx.createDelay(5);
+    const feedbackGain = this.#_ctx.createGain();
+    const wetGain = this.#_ctx.createGain();
+    const dryGain = this.#_ctx.createGain();
+    const input = this.#_ctx.createGain();
+    const output = this.#_ctx.createGain();
+
+    delay.delayTime.value = time;
+    feedbackGain.gain.value = feedback;
+    wetGain.gain.value = mix;
+    dryGain.gain.value = 1 - mix;
+
+    // Signal flow
+    input.connect(delay);
+    input.connect(dryGain);
+    delay.connect(feedbackGain);
+    feedbackGain.connect(delay);
+    delay.connect(wetGain);
+    wetGain.connect(output);
+    dryGain.connect(output);
+
+    return {
+      input,
+      output,
+      setTime: (t) =>
+        delay.delayTime.setValueAtTime(t, this.#_ctx.currentTime),
+      setFeedback: (f) =>
+        feedbackGain.gain.setValueAtTime(f, this.#_ctx.currentTime),
+      setMix: (m) => {
+        wetGain.gain.setValueAtTime(m, this.#_ctx.currentTime);
+        dryGain.gain.setValueAtTime(1 - m, this.#_ctx.currentTime);
+      },
+    };
+  }
+
+  /**
+   * Create a simple reverb using convolution
+   * @param {number} [duration=2] - Reverb duration
+   * @param {number} [decay=2] - Decay rate
+   * @returns {ConvolverNode}
+   */
+  static reverb(duration = 2, decay = 2) {
+    const convolver = this.#_ctx.createConvolver();
+    const sampleRate = this.#_ctx.sampleRate;
+    const length = sampleRate * duration;
+    const impulse = this.#_ctx.createBuffer(2, length, sampleRate);
+
+    for (let channel = 0; channel < 2; channel++) {
+      const channelData = impulse.getChannelData(channel);
+      for (let i = 0; i < length; i++) {
+        channelData[i] =
+          (Math.random() * 2 - 1) * Math.pow(1 - i / length, decay);
+      }
+    }
+
+    convolver.buffer = impulse;
+    return convolver;
+  }
+
+  /**
+   * Create a distortion effect
+   * @param {number} [amount=50] - Distortion amount (0-100)
+   * @returns {WaveShaperNode}
+   */
+  static distortion(amount = 50) {
+    const shaper = this.#_ctx.createWaveShaper();
+    const k = amount;
+    const samples = 44100;
+    const curve = new Float32Array(samples);
+
+    for (let i = 0; i < samples; i++) {
+      const x = (i * 2) / samples - 1;
+      curve[i] =
+        ((3 + k) * x * 20 * (Math.PI / 180)) / (Math.PI + k * Math.abs(x));
+    }
+
+    shaper.curve = curve;
+    shaper.oversample = "4x";
+    return shaper;
+  }
+
+  /**
+   * Create a tremolo effect
+   * @param {number} [rate=5] - Tremolo rate in Hz
+   * @param {number} [depth=0.5] - Tremolo depth (0-1)
+   * @returns {Object} Tremolo effect controller
+   */
+  static tremolo(rate = 5, depth = 0.5) {
+    const lfo = this.#_ctx.createOscillator();
+    const lfoGain = this.#_ctx.createGain();
+    const outputGain = this.#_ctx.createGain();
+
+    lfo.frequency.value = rate;
+    lfoGain.gain.value = depth * 0.5;
+    outputGain.gain.value = 1 - depth * 0.5;
+
+    lfo.connect(lfoGain);
+    lfoGain.connect(outputGain.gain);
+    lfo.start();
+
+    return {
+      input: outputGain,
+      output: outputGain,
+      lfo,
+      setRate: (r) =>
+        lfo.frequency.setValueAtTime(r, this.#_ctx.currentTime),
+      setDepth: (d) =>
+        lfoGain.gain.setValueAtTime(d * 0.5, this.#_ctx.currentTime),
+      stop: () => lfo.stop(),
+    };
+  }
+
+  /**
+   * Create a compressor
+   * @param {Object} options - Compressor options
+   * @returns {DynamicsCompressorNode}
+   */
+  static compressor(options = {}) {
+    const {
+      threshold = -24,
+      knee = 30,
+      ratio = 12,
+      attack = 0.003,
+      release = 0.25,
+    } = options;
+
+    const compressor = this.#_ctx.createDynamicsCompressor();
+    compressor.threshold.value = threshold;
+    compressor.knee.value = knee;
+    compressor.ratio.value = ratio;
+    compressor.attack.value = attack;
+    compressor.release.value = release;
+
+    return compressor;
+  }
+
+  /**
+   * Create a stereo panner
+   * @param {number} [pan=0] - Pan value (-1 left, 0 center, 1 right)
+   * @returns {StereoPannerNode}
+   */
+  static panner(pan = 0) {
+    const panner = this.#_ctx.createStereoPanner();
+    panner.pan.value = pan;
+    return panner;
+  }
+
+  /**
+   * Create a gain node
+   * @param {number} [volume=1] - Volume level
+   * @returns {GainNode}
+   */
+  static gain(volume = 1) {
+    const gain = this.#_ctx.createGain();
+    gain.gain.value = volume;
+    return gain;
+  }
+}

package/src/sound/synth.envelope.js

@@ -0,0 +1,59 @@
+/**
+ * SynthEnvelope - ADSR envelope utilities
+ * @module sound/synth.envelope
+ */
+export class SynthEnvelope {
+  /**
+   * Apply ADSR envelope to an AudioParam
+   * @param {AudioParam} param - The parameter to modulate
+   * @param {Object} options - Envelope options
+   * @param {number} [options.attack=0.01] - Attack time in seconds
+   * @param {number} [options.decay=0.1] - Decay time in seconds
+   * @param {number} [options.sustain=0.7] - Sustain level (0-1)
+   * @param {number} [options.release=0.2] - Release time in seconds
+   * @param {number} [options.startTime=0] - Start time
+   * @param {number} [options.duration=1] - Total duration
+   * @param {number} [options.peakVolume=1] - Peak volume level
+   */
+  static applyADSR(param, options = {}) {
+    const {
+      attack = 0.01,
+      decay = 0.1,
+      sustain = 0.7,
+      release = 0.2,
+      startTime = 0,
+      duration = 1,
+      peakVolume = 1,
+    } = options;
+
+    const sustainLevel = peakVolume * sustain;
+    const sustainDuration = Math.max(0, duration - attack - decay);
+
+    param.setValueAtTime(0, startTime);
+    param.linearRampToValueAtTime(peakVolume, startTime + attack);
+    param.linearRampToValueAtTime(sustainLevel, startTime + attack + decay);
+    param.setValueAtTime(
+      sustainLevel,
+      startTime + attack + decay + sustainDuration
+    );
+    param.linearRampToValueAtTime(0, startTime + duration + release);
+  }
+
+  /**
+   * Create envelope presets for common sounds
+   * @returns {Object} Preset envelope configurations
+   */
+  static get presets() {
+    return {
+      pluck: { attack: 0.001, decay: 0.2, sustain: 0.0, release: 0.1 },
+      pad: { attack: 0.5, decay: 0.3, sustain: 0.8, release: 1.0 },
+      organ: { attack: 0.01, decay: 0.0, sustain: 1.0, release: 0.05 },
+      perc: { attack: 0.001, decay: 0.1, sustain: 0.0, release: 0.05 },
+      string: { attack: 0.1, decay: 0.2, sustain: 0.7, release: 0.3 },
+      brass: { attack: 0.05, decay: 0.1, sustain: 0.8, release: 0.2 },
+      blip: { attack: 0.001, decay: 0.05, sustain: 0.0, release: 0.02 },
+      laser: { attack: 0.001, decay: 0.15, sustain: 0.0, release: 0.05 },
+      explosion: { attack: 0.001, decay: 0.3, sustain: 0.2, release: 0.5 },
+    };
+  }
+}

package/src/sound/synth.js

@@ -0,0 +1,229 @@
+/**
+ * Synth - Static utility class for procedural audio generation
+ * Provides a clean API for Web Audio operations with GCanvas integration
+ *
+ * Similar to Painter for canvas, Synth abstracts Web Audio complexity
+ * @module sound/synth
+ */
+import { SynthOscillators } from "./synth.oscillators.js";
+import { SynthEffects } from "./synth.effects.js";
+import { SynthEnvelope } from "./synth.envelope.js";
+import { SynthNoise } from "./synth.noise.js";
+import { SynthMusical } from "./synth.musical.js";
+import { SynthAnalyzer } from "./synth.analyzer.js";
+
+export class Synth {
+  static #_ctx = null;
+  static #_masterGain = null;
+  static #_initialized = false;
+
+  /**
+   * Initialize the audio system
+   * @param {Object} options - Configuration options
+   * @param {number} [options.masterVolume=0.5] - Master volume (0-1)
+   * @param {number} [options.sampleRate=44100] - Sample rate
+   * @param {boolean} [options.enableAnalyzer=false] - Enable audio analyzer
+   */
+  static init(options = {}) {
+    if (this.#_initialized) {
+      console.warn("[Synth] Already initialized");
+      return;
+    }
+
+    const { masterVolume = 0.5, sampleRate = 44100, enableAnalyzer = false } = options;
+
+    try {
+      this.#_ctx = new (window.AudioContext || window.webkitAudioContext)({
+        sampleRate,
+      });
+
+      this.#_masterGain = this.#_ctx.createGain();
+      this.#_masterGain.gain.value = masterVolume;
+      this.#_masterGain.connect(this.#_ctx.destination);
+
+      // Initialize sub-modules
+      SynthOscillators.init(this.#_ctx, this.#_masterGain);
+      SynthEffects.init(this.#_ctx, this.#_masterGain);
+
+      if (enableAnalyzer) {
+        SynthAnalyzer.init(this.#_ctx, this.#_masterGain);
+      }
+
+      this.#_initialized = true;
+      console.log("[Synth] Audio system initialized");
+    } catch (e) {
+      console.error("[Synth] Failed to initialize audio:", e);
+    }
+  }
+
+  /**
+   * Check if audio is initialized
+   * @returns {boolean}
+   */
+  static get isInitialized() {
+    return this.#_initialized;
+  }
+
+  /**
+   * Get the AudioContext
+   * @returns {AudioContext|null}
+   */
+  static get ctx() {
+    return this.#_ctx;
+  }
+
+  /**
+   * Get the master gain node
+   * @returns {GainNode|null}
+   */
+  static get master() {
+    return this.#_masterGain;
+  }
+
+  /**
+   * Get oscillator utilities
+   * @returns {typeof SynthOscillators}
+   */
+  static get osc() {
+    return SynthOscillators;
+  }
+
+  /**
+   * Get effects utilities
+   * @returns {typeof SynthEffects}
+   */
+  static get fx() {
+    return SynthEffects;
+  }
+
+  /**
+   * Get envelope utilities
+   * @returns {typeof SynthEnvelope}
+   */
+  static get env() {
+    return SynthEnvelope;
+  }
+
+  /**
+   * Get noise utilities
+   * @returns {typeof SynthNoise}
+   */
+  static get noise() {
+    return SynthNoise;
+  }
+
+  /**
+   * Get musical utilities
+   * @returns {typeof SynthMusical}
+   */
+  static get music() {
+    return SynthMusical;
+  }
+
+  /**
+   * Get analyzer utilities
+   * @returns {typeof SynthAnalyzer}
+   */
+  static get analyzer() {
+    return SynthAnalyzer;
+  }
+
+  /**
+   * Resume audio context (required after user interaction)
+   * @returns {Promise<void>}
+   */
+  static async resume() {
+    if (this.#_ctx && this.#_ctx.state === "suspended") {
+      await this.#_ctx.resume();
+      console.log("[Synth] Audio context resumed");
+    }
+  }
+
+  /**
+   * Suspend audio context
+   * @returns {Promise<void>}
+   */
+  static async suspend() {
+    if (this.#_ctx && this.#_ctx.state === "running") {
+      await this.#_ctx.suspend();
+    }
+  }
+
+  /**
+   * Get current audio time (for scheduling)
+   * @returns {number}
+   */
+  static get now() {
+    return this.#_ctx ? this.#_ctx.currentTime : 0;
+  }
+
+  /**
+   * Get audio context state
+   * @returns {string} 'suspended' | 'running' | 'closed'
+   */
+  static get state() {
+    return this.#_ctx ? this.#_ctx.state : "closed";
+  }
+
+  /**
+   * Set master volume
+   * @param {number} value - Volume (0-1)
+   */
+  static set volume(value) {
+    if (this.#_masterGain) {
+      this.#_masterGain.gain.setValueAtTime(
+        Math.max(0, Math.min(1, value)),
+        this.#_ctx.currentTime
+      );
+    }
+  }
+
+  /**
+   * Get master volume
+   * @returns {number}
+   */
+  static get volume() {
+    return this.#_masterGain ? this.#_masterGain.gain.value : 0;
+  }
+
+  /**
+   * Create a custom audio node chain
+   * @param {...AudioNode} nodes - Nodes to connect in sequence
+   * @returns {Object} First and last node references
+   */
+  static chain(...nodes) {
+    for (let i = 0; i < nodes.length - 1; i++) {
+      nodes[i].connect(nodes[i + 1]);
+    }
+    return {
+      first: nodes[0],
+      last: nodes[nodes.length - 1],
+      connectTo: (target) => nodes[nodes.length - 1].connect(target),
+    };
+  }
+
+  /**
+   * Schedule a function to run at a specific audio time
+   * @param {Function} fn - Function to execute
+   * @param {number} time - Audio time to execute at
+   * @returns {number} setTimeout ID for cancellation
+   */
+  static schedule(fn, time) {
+    const delay = Math.max(0, (time - this.now) * 1000);
+    return setTimeout(fn, delay);
+  }
+
+  /**
+   * Close the audio context and cleanup
+   */
+  static async close() {
+    if (this.#_ctx) {
+      SynthAnalyzer.dispose();
+      await this.#_ctx.close();
+      this.#_ctx = null;
+      this.#_masterGain = null;
+      this.#_initialized = false;
+      console.log("[Synth] Audio system closed");
+    }
+  }
+}

package/src/sound/synth.musical.js

@@ -0,0 +1,160 @@
+/**
+ * SynthMusical - Musical scales, notes, and chord generation
+ * @module sound/synth.musical
+ */
+export class SynthMusical {
+  static NOTE_FREQUENCIES = {
+    C: 16.35,
+    "C#": 17.32,
+    Db: 17.32,
+    D: 18.35,
+    "D#": 19.45,
+    Eb: 19.45,
+    E: 20.6,
+    F: 21.83,
+    "F#": 23.12,
+    Gb: 23.12,
+    G: 24.5,
+    "G#": 25.96,
+    Ab: 25.96,
+    A: 27.5,
+    "A#": 29.14,
+    Bb: 29.14,
+    B: 30.87,
+  };
+
+  static SCALES = {
+    major: [0, 2, 4, 5, 7, 9, 11],
+    minor: [0, 2, 3, 5, 7, 8, 10],
+    pentatonic: [0, 2, 4, 7, 9],
+    pentatonicMinor: [0, 3, 5, 7, 10],
+    blues: [0, 3, 5, 6, 7, 10],
+    dorian: [0, 2, 3, 5, 7, 9, 10],
+    mixolydian: [0, 2, 4, 5, 7, 9, 10],
+    chromatic: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
+    wholeTone: [0, 2, 4, 6, 8, 10],
+    diminished: [0, 2, 3, 5, 6, 8, 9, 11],
+  };
+
+  static CHORDS = {
+    major: [0, 4, 7],
+    minor: [0, 3, 7],
+    diminished: [0, 3, 6],
+    augmented: [0, 4, 8],
+    sus2: [0, 2, 7],
+    sus4: [0, 5, 7],
+    major7: [0, 4, 7, 11],
+    minor7: [0, 3, 7, 10],
+    dom7: [0, 4, 7, 10],
+    dim7: [0, 3, 6, 9],
+    add9: [0, 4, 7, 14],
+    power: [0, 7],
+  };
+
+  /**
+   * Convert note name to frequency
+   * @param {string} note - Note name (e.g., 'A4', 'C#3')
+   * @returns {number} Frequency in Hz
+   */
+  static noteToFreq(note) {
+    const match = note.match(/^([A-G][#b]?)(\d+)$/);
+    if (!match) throw new Error(`Invalid note: ${note}`);
+
+    const [, noteName, octave] = match;
+    const baseFreq = this.NOTE_FREQUENCIES[noteName];
+    if (baseFreq === undefined) throw new Error(`Unknown note: ${noteName}`);
+    return baseFreq * Math.pow(2, parseInt(octave));
+  }
+
+  /**
+   * Get frequencies for a scale
+   * @param {string} root - Root note (e.g., 'C4')
+   * @param {string} [scaleName='major'] - Scale name
+   * @param {number} [octaves=1] - Number of octaves
+   * @returns {number[]} Array of frequencies
+   */
+  static scale(root, scaleName = "major", octaves = 1) {
+    const rootFreq = this.noteToFreq(root);
+    const intervals = this.SCALES[scaleName];
+    if (!intervals) throw new Error(`Unknown scale: ${scaleName}`);
+
+    const frequencies = [];
+
+    for (let oct = 0; oct < octaves; oct++) {
+      for (const interval of intervals) {
+        frequencies.push(rootFreq * Math.pow(2, (interval + oct * 12) / 12));
+      }
+    }
+
+    return frequencies;
+  }
+
+  /**
+   * Get frequencies for a chord
+   * @param {string} root - Root note
+   * @param {string} [chordType='major'] - Chord type
+   * @returns {number[]} Array of frequencies
+   */
+  static chord(root, chordType = "major") {
+    const rootFreq = this.noteToFreq(root);
+    const intervals = this.CHORDS[chordType];
+    if (!intervals) throw new Error(`Unknown chord type: ${chordType}`);
+    return intervals.map((i) => rootFreq * Math.pow(2, i / 12));
+  }
+
+  /**
+   * Map a value (0-1) to a frequency in a scale
+   * @param {number} value - Value between 0 and 1
+   * @param {string} [root='C4'] - Root note
+   * @param {string} [scaleName='pentatonic'] - Scale name
+   * @param {number} [octaves=2] - Number of octaves
+   * @returns {number} Frequency in Hz
+   */
+  static mapToScale(value, root = "C4", scaleName = "pentatonic", octaves = 2) {
+    const frequencies = this.scale(root, scaleName, octaves);
+    const clampedValue = Math.max(0, Math.min(1, value));
+    const index =
+      Math.floor(clampedValue * frequencies.length) % frequencies.length;
+    return frequencies[index];
+  }
+
+  /**
+   * Convert MIDI note number to frequency
+   * @param {number} midi - MIDI note number (0-127)
+   * @returns {number} Frequency in Hz
+   */
+  static midiToFreq(midi) {
+    return 440 * Math.pow(2, (midi - 69) / 12);
+  }
+
+  /**
+   * Convert frequency to MIDI note number
+   * @param {number} freq - Frequency in Hz
+   * @returns {number} MIDI note number
+   */
+  static freqToMidi(freq) {
+    return Math.round(12 * Math.log2(freq / 440) + 69);
+  }
+
+  /**
+   * Get a random note from a scale
+   * @param {string} [root='C4'] - Root note
+   * @param {string} [scaleName='pentatonic'] - Scale name
+   * @param {number} [octaves=2] - Number of octaves
+   * @returns {number} Frequency in Hz
+   */
+  static randomNote(root = "C4", scaleName = "pentatonic", octaves = 2) {
+    const frequencies = this.scale(root, scaleName, octaves);
+    return frequencies[Math.floor(Math.random() * frequencies.length)];
+  }
+
+  /**
+   * Get frequency with cents offset
+   * @param {number} freq - Base frequency
+   * @param {number} cents - Cents offset (-100 to 100 typical)
+   * @returns {number} Adjusted frequency
+   */
+  static detune(freq, cents) {
+    return freq * Math.pow(2, cents / 1200);
+  }
+}