@vgai/engine 0.2.0

package/src/audio/musical.ts

@@ -0,0 +1,200 @@
+/**
+ * Musical sounds — rhythmic and melodic elements.
+ *
+ * bassPulse and arpeggio are continuous (play/stop).
+ * stinger is one-shot.
+ */
+
+/** Bass pulse — rhythmic low sine following a beat pattern. */
+export function bassPulse(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { frequency?: number; bpm?: number; volume?: number; pattern?: number[] },
+) {
+  const frequency = options?.frequency ?? 55;
+  const bpm = options?.bpm ?? 120;
+  const volume = options?.volume ?? 0.3;
+  const pattern = options?.pattern ?? [1, 0, 1, 0];
+  const beatInterval = 60 / bpm;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  let osc: OscillatorNode | null = null;
+  let pulseGain: GainNode | null = null;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let step = 0;
+
+  return {
+    play() {
+      if (osc) return;
+      osc = ctx.createOscillator();
+      osc.type = 'sine';
+      osc.frequency.value = frequency;
+      pulseGain = ctx.createGain();
+      pulseGain.gain.value = 0;
+      osc.connect(pulseGain);
+      pulseGain.connect(out);
+      osc.start();
+      step = 0;
+
+      const tick = () => {
+        if (!pulseGain) return;
+        const beat = pattern[step % pattern.length]!;
+        const now = ctx.currentTime;
+        if (beat) {
+          pulseGain.gain.setValueAtTime(1, now);
+          pulseGain.gain.exponentialRampToValueAtTime(0.01, now + beatInterval * 0.8);
+        }
+        step++;
+      };
+
+      tick();
+      timer = setInterval(tick, beatInterval * 1000);
+    },
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (!osc) return;
+      const refs = { osc, pulseGain };
+      osc = null;
+      pulseGain = null;
+      setTimeout(() => {
+        try {
+          refs.osc.stop();
+        } catch {
+          /* already stopped */
+        }
+        refs.osc.disconnect();
+        refs.pulseGain?.disconnect();
+      }, 100);
+    },
+    dispose() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (osc) {
+        try {
+          osc.stop();
+        } catch {
+          /* already stopped */
+        }
+        osc.disconnect();
+      }
+      pulseGain?.disconnect();
+      osc = null;
+      pulseGain = null;
+      out.disconnect();
+    },
+  };
+}
+
+/** Arpeggio — repeating note sequence. */
+export function arpeggio(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: {
+    notes?: number[];
+    bpm?: number;
+    waveform?: OscillatorType;
+    volume?: number;
+  },
+) {
+  const notes = options?.notes ?? [262, 330, 392, 523];
+  const bpm = options?.bpm ?? 140;
+  const waveform = options?.waveform ?? 'triangle';
+  const volume = options?.volume ?? 0.2;
+  const noteInterval = 60 / bpm;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let step = 0;
+
+  function playNote(freq: number) {
+    const now = ctx.currentTime;
+    const osc = ctx.createOscillator();
+    osc.type = waveform;
+    osc.frequency.value = freq;
+
+    const env = ctx.createGain();
+    env.gain.setValueAtTime(0.8, now);
+    env.gain.exponentialRampToValueAtTime(0.001, now + noteInterval * 0.9);
+
+    osc.connect(env);
+    env.connect(out);
+    osc.start(now);
+    osc.stop(now + noteInterval);
+  }
+
+  return {
+    play() {
+      if (timer) return;
+      step = 0;
+      const tick = () => {
+        playNote(notes[step % notes.length]!);
+        step++;
+      };
+      tick();
+      timer = setInterval(tick, noteInterval * 1000);
+    },
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+    dispose() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      out.disconnect();
+    },
+  };
+}
+
+/** Stinger — one-shot ascending note sequence for events. */
+export function stinger(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { notes?: number[]; volume?: number; tempo?: number },
+) {
+  const notes = options?.notes ?? [392, 494, 587, 784];
+  const volume = options?.volume ?? 0.3;
+  const tempo = options?.tempo ?? 0.12;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      for (let i = 0; i < notes.length; i++) {
+        const t = now + i * tempo;
+        const osc = ctx.createOscillator();
+        osc.type = 'triangle';
+        osc.frequency.value = notes[i]!;
+
+        const env = ctx.createGain();
+        env.gain.setValueAtTime(0.8, t);
+        env.gain.exponentialRampToValueAtTime(0.001, t + tempo * 1.5);
+
+        osc.connect(env);
+        env.connect(out);
+        osc.start(t);
+        osc.stop(t + tempo * 1.5 + 0.01);
+      }
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}

package/src/audio/ui-sounds.ts

@@ -0,0 +1,171 @@
+/**
+ * UI sounds — short tonal feedback for interface interactions.
+ *
+ * All one-shot: call play() to trigger, dispose() to clean up.
+ */
+
+/** Click — short sine pip. */
+export function uiClick(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number },
+) {
+  const pitch = options?.pitch ?? 800;
+  const volume = options?.volume ?? 0.2;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const osc = ctx.createOscillator();
+      osc.type = 'sine';
+      osc.frequency.value = pitch;
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(1, now);
+      env.gain.exponentialRampToValueAtTime(0.001, now + 0.04);
+
+      osc.connect(env);
+      env.connect(out);
+      osc.start(now);
+      osc.stop(now + 0.05);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Hover — softer, higher sine pip. */
+export function uiHover(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number },
+) {
+  const pitch = options?.pitch ?? 1200;
+  const volume = options?.volume ?? 0.1;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const osc = ctx.createOscillator();
+      osc.type = 'sine';
+      osc.frequency.value = pitch;
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(1, now);
+      env.gain.exponentialRampToValueAtTime(0.001, now + 0.03);
+
+      osc.connect(env);
+      env.connect(out);
+      osc.start(now);
+      osc.stop(now + 0.04);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Success — two ascending tones (major third interval). */
+export function uiSuccess(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number },
+) {
+  const pitch = options?.pitch ?? 500;
+  const volume = options?.volume ?? 0.3;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+
+      // First note
+      const osc1 = ctx.createOscillator();
+      osc1.type = 'sine';
+      osc1.frequency.value = pitch;
+      const env1 = ctx.createGain();
+      env1.gain.setValueAtTime(1, now);
+      env1.gain.exponentialRampToValueAtTime(0.001, now + 0.15);
+      osc1.connect(env1);
+      env1.connect(out);
+      osc1.start(now);
+      osc1.stop(now + 0.16);
+
+      // Second note — major third above, delayed 0.1s
+      const osc2 = ctx.createOscillator();
+      osc2.type = 'sine';
+      osc2.frequency.value = pitch * (5 / 4);
+      const env2 = ctx.createGain();
+      env2.gain.setValueAtTime(0.001, now);
+      env2.gain.setValueAtTime(1, now + 0.1);
+      env2.gain.exponentialRampToValueAtTime(0.001, now + 0.25);
+      osc2.connect(env2);
+      env2.connect(out);
+      osc2.start(now);
+      osc2.stop(now + 0.26);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Error — two descending tones (minor second). */
+export function uiError(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number },
+) {
+  const pitch = options?.pitch ?? 400;
+  const volume = options?.volume ?? 0.3;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+
+      // First note
+      const osc1 = ctx.createOscillator();
+      osc1.type = 'sine';
+      osc1.frequency.value = pitch;
+      const env1 = ctx.createGain();
+      env1.gain.setValueAtTime(1, now);
+      env1.gain.exponentialRampToValueAtTime(0.001, now + 0.15);
+      osc1.connect(env1);
+      env1.connect(out);
+      osc1.start(now);
+      osc1.stop(now + 0.16);
+
+      // Second note — minor second below, delayed 0.1s
+      const osc2 = ctx.createOscillator();
+      osc2.type = 'sine';
+      osc2.frequency.value = pitch * 0.9;
+      const env2 = ctx.createGain();
+      env2.gain.setValueAtTime(0.001, now);
+      env2.gain.setValueAtTime(1, now + 0.1);
+      env2.gain.exponentialRampToValueAtTime(0.001, now + 0.25);
+      osc2.connect(env2);
+      env2.connect(out);
+      osc2.start(now);
+      osc2.stop(now + 0.26);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}

package/src/audio/vehicle.ts

@@ -0,0 +1,235 @@
+/**
+ * Vehicle sounds — continuous sounds with real-time parameter control.
+ *
+ * Each returns play/stop/setX/dispose. Parameters use setTargetAtTime for smooth ramping.
+ */
+
+function createNoiseBuffer(ctx: AudioContext, duration = 2): AudioBuffer {
+  const length = ctx.sampleRate * duration;
+  const buffer = ctx.createBuffer(1, length, ctx.sampleRate);
+  const data = buffer.getChannelData(0);
+  for (let i = 0; i < length; i++) data[i] = Math.random() * 2 - 1;
+  return buffer;
+}
+
+/** Engine drone — sawtooth oscillator with throttle-driven pitch and volume. */
+export function engineDrone(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { baseFreq?: number; volume?: number },
+) {
+  const baseFreq = options?.baseFreq ?? 60;
+  const maxVol = options?.volume ?? 0.4;
+
+  const out = ctx.createGain();
+  out.gain.value = 0;
+  out.connect(dest);
+
+  // Subtle waveshaping for grit
+  const shaper = ctx.createWaveShaper();
+  const curve = new Float32Array(256);
+  for (let i = 0; i < 256; i++) {
+    const x = (i / 128 - 1) * 1.5;
+    curve[i] = Math.tanh(x);
+  }
+  shaper.curve = curve;
+  shaper.connect(out);
+
+  let osc: OscillatorNode | null = null;
+
+  return {
+    play() {
+      if (osc) return;
+      osc = ctx.createOscillator();
+      osc.type = 'sawtooth';
+      osc.frequency.value = baseFreq;
+      osc.connect(shaper);
+      osc.start();
+      out.gain.setTargetAtTime(0.1, ctx.currentTime, 0.05);
+    },
+    stop() {
+      if (!osc) return;
+      out.gain.setTargetAtTime(0, ctx.currentTime, 0.05);
+      const ref = osc;
+      osc = null;
+      setTimeout(() => {
+        try {
+          ref.stop();
+        } catch {
+          /* already stopped */
+        }
+        ref.disconnect();
+      }, 200);
+    },
+    /** Set throttle 0–1. Adjusts pitch (1x–3x base) and volume. */
+    setThrottle(t: number) {
+      if (!osc) return;
+      const clamped = Math.max(0, Math.min(1, t));
+      osc.frequency.setTargetAtTime(baseFreq + clamped * baseFreq * 2, ctx.currentTime, 0.05);
+      out.gain.setTargetAtTime(0.1 + clamped * maxVol, ctx.currentTime, 0.05);
+    },
+    dispose() {
+      if (osc) {
+        try {
+          osc.stop();
+        } catch {
+          /* already stopped */
+        }
+        osc.disconnect();
+        osc = null;
+      }
+      shaper.disconnect();
+      out.disconnect();
+    },
+  };
+}
+
+/** Brake squeal — high-frequency oscillator with LFO tremolo. */
+export function brakeSqueal(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number },
+) {
+  const pitch = options?.pitch ?? 2000;
+  const maxVol = options?.volume ?? 0.3;
+
+  const out = ctx.createGain();
+  out.gain.value = 0;
+  out.connect(dest);
+
+  let osc: OscillatorNode | null = null;
+  let lfo: OscillatorNode | null = null;
+  let lfoGain: GainNode | null = null;
+
+  return {
+    play() {
+      if (osc) return;
+      osc = ctx.createOscillator();
+      osc.type = 'sine';
+      osc.frequency.value = pitch;
+
+      // LFO for tremolo effect
+      lfo = ctx.createOscillator();
+      lfo.type = 'sine';
+      lfo.frequency.value = 30;
+      lfoGain = ctx.createGain();
+      lfoGain.gain.value = 0.3;
+      lfo.connect(lfoGain);
+      lfoGain.connect(out.gain);
+
+      osc.connect(out);
+      osc.start();
+      lfo.start();
+    },
+    stop() {
+      if (!osc) return;
+      out.gain.setTargetAtTime(0, ctx.currentTime, 0.02);
+      const refs = { osc, lfo, lfoGain };
+      osc = null;
+      lfo = null;
+      lfoGain = null;
+      setTimeout(() => {
+        try {
+          refs.osc.stop();
+        } catch {
+          /* already stopped */
+        }
+        refs.osc.disconnect();
+        try {
+          refs.lfo?.stop();
+        } catch {
+          /* already stopped */
+        }
+        refs.lfo?.disconnect();
+        refs.lfoGain?.disconnect();
+      }, 100);
+    },
+    /** Set brake intensity 0–1. */
+    setIntensity(i: number) {
+      out.gain.setTargetAtTime(Math.max(0, Math.min(1, i)) * maxVol, ctx.currentTime, 0.02);
+    },
+    dispose() {
+      if (osc) {
+        try {
+          osc.stop();
+        } catch {
+          /* already stopped */
+        }
+        osc.disconnect();
+      }
+      if (lfo) {
+        try {
+          lfo.stop();
+        } catch {
+          /* already stopped */
+        }
+        lfo.disconnect();
+      }
+      lfoGain?.disconnect();
+      osc = null;
+      lfo = null;
+      lfoGain = null;
+      out.disconnect();
+    },
+  };
+}
+
+/** Tire skid — filtered looping noise with intensity control. */
+export function tireSkid(ctx: AudioContext, dest: AudioNode, options?: { volume?: number }) {
+  const maxVol = options?.volume ?? 0.3;
+  const noiseBuffer = createNoiseBuffer(ctx, 2);
+
+  const out = ctx.createGain();
+  out.gain.value = 0;
+  out.connect(dest);
+
+  const filter = ctx.createBiquadFilter();
+  filter.type = 'bandpass';
+  filter.frequency.value = 800;
+  filter.Q.value = 1.5;
+  filter.connect(out);
+
+  let src: AudioBufferSourceNode | null = null;
+
+  return {
+    play() {
+      if (src) return;
+      src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+      src.loop = true;
+      src.connect(filter);
+      src.start();
+    },
+    stop() {
+      if (!src) return;
+      out.gain.setTargetAtTime(0, ctx.currentTime, 0.02);
+      const ref = src;
+      src = null;
+      setTimeout(() => {
+        try {
+          ref.stop();
+        } catch {
+          /* already stopped */
+        }
+        ref.disconnect();
+      }, 100);
+    },
+    /** Set skid intensity 0–1. */
+    setIntensity(i: number) {
+      out.gain.setTargetAtTime(Math.max(0, Math.min(1, i)) * maxVol, ctx.currentTime, 0.02);
+    },
+    dispose() {
+      if (src) {
+        try {
+          src.stop();
+        } catch {
+          /* already stopped */
+        }
+        src.disconnect();
+      }
+      src = null;
+      filter.disconnect();
+      out.disconnect();
+    },
+  };
+}