@affectively/entrainment-audio 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1146 @@
+// src/presets.ts
+var DELTA_PRESET = {
+  id: "delta",
+  name: "Delta",
+  description: "Deep sleep, unconsciousness, restoration. Stage 3-4 NREM sleep.",
+  frequencyRange: {
+    min: 0.5,
+    max: 4
+  },
+  targetFrequency: 2,
+  // Hz - middle of delta range
+  carrierFrequency: 450,
+  // Hz - within Oster Curve (400-500 Hz)
+  color: "#1e3a8a",
+  // Deep indigo/blue
+  useCase: "Sleep aids, deep restoration modules"
+};
+var THETA_PRESET = {
+  id: "theta",
+  name: "Theta",
+  description: "Deep meditation, creativity, memory encoding, hypnagogic state",
+  frequencyRange: {
+    min: 4,
+    max: 8
+  },
+  targetFrequency: 6,
+  // Hz - middle of theta range
+  carrierFrequency: 450,
+  // Hz - within Oster Curve
+  color: "#7c3aed",
+  // Purple/violet
+  useCase: "Meditation guides, creative brainstorming tools"
+};
+var ALPHA_PRESET = {
+  id: "alpha",
+  name: "Alpha",
+  description: 'Relaxed alertness, "flow" state, visual cortex idling',
+  frequencyRange: {
+    min: 8,
+    max: 12
+  },
+  targetFrequency: 10,
+  // Hz - middle of alpha range
+  carrierFrequency: 450,
+  // Hz - within Oster Curve
+  color: "#14b8a6",
+  // Teal/cyan
+  useCase: 'Stress relief, light focus, "calm" modes'
+};
+var LOW_BETA_PRESET = {
+  id: "low-beta",
+  name: "Low Beta (SMR)",
+  description: "Calm focus, stillness, sensorimotor rhythm. Used in ADHD neurofeedback",
+  frequencyRange: {
+    min: 12,
+    max: 15
+  },
+  targetFrequency: 13.5,
+  // Hz - middle of low beta range
+  carrierFrequency: 450,
+  // Hz - within Oster Curve
+  color: "#10b981",
+  // Green
+  useCase: "ADHD support, reading assistants"
+};
+var MID_BETA_PRESET = {
+  id: "mid-beta",
+  name: "Mid Beta",
+  description: "Active focus, problem-solving, sustained attention",
+  frequencyRange: {
+    min: 15,
+    max: 20
+  },
+  targetFrequency: 17.5,
+  // Hz - middle of mid beta range
+  carrierFrequency: 450,
+  // Hz - within Oster Curve
+  color: "#f59e0b",
+  // Yellow/amber
+  useCase: "Productivity timers, study aids"
+};
+var HIGH_BETA_PRESET = {
+  id: "high-beta",
+  name: "High Beta",
+  description: "High energy, excitement, complex thought. Can induce anxiety if prolonged",
+  frequencyRange: {
+    min: 20,
+    max: 30
+  },
+  targetFrequency: 25,
+  // Hz - middle of high beta range
+  carrierFrequency: 450,
+  // Hz - within Oster Curve
+  color: "#f97316",
+  // Orange
+  useCase: "Pre-workout energy; short-term alertness"
+};
+var GAMMA_PRESET = {
+  id: "gamma",
+  name: "Gamma",
+  description: "Peak performance, insight, cognitive binding. Cross-modal synchronization",
+  frequencyRange: {
+    min: 30,
+    max: 100
+  },
+  targetFrequency: 40,
+  // Hz - common gamma entrainment target
+  carrierFrequency: 450,
+  // Hz - within Oster Curve
+  color: "#e0e7ff",
+  // White/light blue
+  useCase: "Cognitive boosters, complex synthesis tasks"
+};
+var BRAINWAVE_PRESETS = {
+  delta: DELTA_PRESET,
+  theta: THETA_PRESET,
+  alpha: ALPHA_PRESET,
+  "low-beta": LOW_BETA_PRESET,
+  "mid-beta": MID_BETA_PRESET,
+  "high-beta": HIGH_BETA_PRESET,
+  gamma: GAMMA_PRESET
+};
+function getPreset(band) {
+  return BRAINWAVE_PRESETS[band];
+}
+function getPresetByFrequency(frequency) {
+  for (const preset of Object.values(BRAINWAVE_PRESETS)) {
+    if (frequency >= preset.frequencyRange.min && frequency <= preset.frequencyRange.max) {
+      return preset;
+    }
+  }
+  return null;
+}
+function validateOsterCurve(carrierFrequency) {
+  return carrierFrequency >= 400 && carrierFrequency <= 500;
+}
+function getRecommendedCarrierFrequency() {
+  return 450;
+}
+
+// src/safety.ts
+var EPILEPSY_WARNING = {
+  id: "epilepsy",
+  title: "Epilepsy Warning",
+  message: "If you have a history of epilepsy or seizures, consult your healthcare provider before using this tool. Flashing visuals synchronized to audio frequencies may trigger seizures in some individuals.",
+  severity: "warning"
+};
+var DRIVING_WARNING = {
+  id: "driving",
+  title: "Do Not Use While Driving",
+  message: "Do not use this tool while operating a vehicle or machinery. Entrainment to low frequencies (Alpha, Theta, Delta) can induce drowsiness and altered states of consciousness, significantly slowing reaction times.",
+  severity: "critical"
+};
+var PACEMAKER_WARNING = {
+  id: "pacemaker",
+  title: "Pacemaker Warning",
+  message: "If you have a pacemaker or other implanted medical device, consult your healthcare provider before using headphones with strong magnetic drivers near the device.",
+  severity: "info"
+};
+var MENTAL_HEALTH_WARNING = {
+  id: "mental-health",
+  title: "Mental Health Considerations",
+  message: "If you have a history of severe mental health disorders (schizophrenia, psychosis, dissociation), use this tool with caution or under supervision. Altered states can sometimes exacerbate symptoms of dissociation or paranoia.",
+  severity: "warning"
+};
+var STROBING_WARNING = {
+  id: "strobing",
+  title: "Visual Strobing Warning",
+  message: "Visual effects synchronized to frequencies between 3-30 Hz may trigger photosensitive epilepsy. This tool uses smooth transitions only, but if you experience any discomfort, stop immediately.",
+  severity: "warning"
+};
+function getSafetyWarnings(config) {
+  const warnings = [];
+  if (config.hasVisualizer) {
+    warnings.push(EPILEPSY_WARNING);
+    warnings.push(STROBING_WARNING);
+  }
+  if (config.currentPreset) {
+    const preset = BRAINWAVE_PRESETS[config.currentPreset];
+    if (preset.id === "delta" || preset.id === "theta" || preset.id === "alpha") {
+      warnings.push(DRIVING_WARNING);
+    }
+  } else if (config.frequency) {
+    if (config.frequency <= 12) {
+      warnings.push(DRIVING_WARNING);
+    }
+  }
+  warnings.push(MENTAL_HEALTH_WARNING);
+  warnings.push(PACEMAKER_WARNING);
+  return warnings;
+}
+function isPhotosensitiveTriggerRange(frequency) {
+  return frequency >= 3 && frequency <= 30;
+}
+function getAllSafetyWarnings() {
+  return [
+    EPILEPSY_WARNING,
+    DRIVING_WARNING,
+    PACEMAKER_WARNING,
+    MENTAL_HEALTH_WARNING,
+    STROBING_WARNING
+  ];
+}
+
+// src/BinauralGenerator.ts
+var BinauralGenerator = class {
+  constructor(ctx) {
+    this.nodes = null;
+    this.config = null;
+    this.ctx = ctx;
+  }
+  /**
+   * Start binaural beat generation
+   *
+   * @param config - Binaural generator configuration
+   * @param masterGain - Master gain node to connect to
+   */
+  start(config, masterGain) {
+    if (!validateOsterCurve(config.carrierFrequency)) {
+      throw new Error(
+        `Binaural beats require carrier frequency between 400-500 Hz (Oster Curve). Got ${config.carrierFrequency} Hz.`
+      );
+    }
+    this.stop();
+    this.config = config;
+    const leftOsc = this.ctx.createOscillator();
+    const rightOsc = this.ctx.createOscillator();
+    leftOsc.frequency.value = config.carrierFrequency;
+    rightOsc.frequency.value = config.carrierFrequency + config.beatFrequency;
+    const leftGain = this.ctx.createGain();
+    const rightGain = this.ctx.createGain();
+    leftGain.gain.value = config.volume;
+    rightGain.gain.value = config.volume;
+    const leftPan = this.ctx.createStereoPanner();
+    const rightPan = this.ctx.createStereoPanner();
+    leftPan.pan.value = -1;
+    rightPan.pan.value = 1;
+    leftOsc.connect(leftGain).connect(leftPan).connect(masterGain);
+    rightOsc.connect(rightGain).connect(rightPan).connect(masterGain);
+    leftOsc.start();
+    rightOsc.start();
+    this.nodes = {
+      leftOsc,
+      rightOsc,
+      leftPan,
+      rightPan,
+      leftGain,
+      rightGain
+    };
+  }
+  /**
+   * Update generator parameters
+   */
+  updateConfig(config) {
+    if (!this.nodes || !this.config) {
+      return;
+    }
+    const newConfig = { ...this.config, ...config };
+    this.config = newConfig;
+    if (config.volume !== void 0) {
+      this.nodes.leftGain.gain.value = config.volume;
+      this.nodes.rightGain.gain.value = config.volume;
+    }
+    if (config.carrierFrequency !== void 0 || config.beatFrequency !== void 0) {
+      const carrierFreq = config.carrierFrequency ?? this.config.carrierFrequency;
+      const beatFreq = config.beatFrequency ?? this.config.beatFrequency;
+      if (!validateOsterCurve(carrierFreq)) {
+        console.warn(
+          `Binaural beats require carrier frequency between 400-500 Hz. Got ${carrierFreq} Hz.`
+        );
+      }
+      this.nodes.leftOsc.frequency.value = carrierFreq;
+      this.nodes.rightOsc.frequency.value = carrierFreq + beatFreq;
+    }
+  }
+  /**
+   * Stop binaural beat generation
+   */
+  stop() {
+    if (this.nodes) {
+      try {
+        this.nodes.leftOsc.stop();
+        this.nodes.rightOsc.stop();
+      } catch {
+      }
+      this.nodes.leftOsc.disconnect();
+      this.nodes.rightOsc.disconnect();
+      this.nodes.leftGain.disconnect();
+      this.nodes.rightGain.disconnect();
+      this.nodes.leftPan.disconnect();
+      this.nodes.rightPan.disconnect();
+      this.nodes = null;
+    }
+    this.config = null;
+  }
+  /**
+   * Check if generator is active
+   */
+  isActive() {
+    return this.nodes !== null;
+  }
+};
+
+// src/IsochronicGenerator.ts
+var IsochronicGenerator = class {
+  // Schedule 100ms ahead
+  constructor(ctx) {
+    this.nodes = null;
+    this.config = null;
+    this.isPlaying = false;
+    this.lookaheadTimer = null;
+    this.nextEventTime = 0;
+    this.scheduleAheadTime = 0.1;
+    this.ctx = ctx;
+  }
+  /**
+   * Start isochronic tone generation
+   *
+   * @param config - Isochronic generator configuration
+   * @param masterGain - Master gain node to connect to
+   */
+  start(config, masterGain) {
+    this.stop();
+    this.config = config;
+    this.isPlaying = true;
+    const carrier = this.ctx.createOscillator();
+    const gainNode = this.ctx.createGain();
+    carrier.frequency.value = config.carrierFrequency;
+    gainNode.gain.value = 0;
+    carrier.connect(gainNode).connect(masterGain);
+    carrier.start();
+    this.nodes = {
+      carrier,
+      gainNode,
+      scheduledEvents: []
+    };
+    this.nextEventTime = this.ctx.currentTime;
+    this.schedulePulses();
+  }
+  /**
+   * Schedule isochronic pulses using lookahead scheduling
+   * Prevents CPU overload by scheduling 1-2 seconds ahead
+   */
+  schedulePulses() {
+    if (!this.nodes || !this.config || !this.isPlaying) {
+      return;
+    }
+    const cycleDuration = 1 / this.config.beatFrequency;
+    const attackTime = this.config.attackTime / 1e3;
+    const releaseTime = this.config.releaseTime / 1e3;
+    const holdTime = cycleDuration * this.config.dutyCycle;
+    while (this.nextEventTime < this.ctx.currentTime + this.scheduleAheadTime) {
+      const pulseStart = this.nextEventTime;
+      const pulseEnd = pulseStart + holdTime;
+      this.nodes.gainNode.gain.setTargetAtTime(
+        this.config.volume,
+        pulseStart,
+        attackTime / 3
+      );
+      this.nodes.gainNode.gain.setTargetAtTime(0, pulseEnd, releaseTime / 3);
+      this.nextEventTime += cycleDuration;
+    }
+    this.lookaheadTimer = setTimeout(() => {
+      this.schedulePulses();
+    }, this.scheduleAheadTime * 1e3);
+  }
+  /**
+   * Update generator parameters
+   */
+  updateConfig(config) {
+    if (!this.nodes || !this.config) {
+      return;
+    }
+    const newConfig = { ...this.config, ...config };
+    this.config = newConfig;
+    if (config.carrierFrequency !== void 0) {
+      this.nodes.carrier.frequency.value = config.carrierFrequency;
+    }
+    if (config.volume !== void 0) {
+      this.nodes.gainNode.gain.setTargetAtTime(
+        config.volume,
+        this.ctx.currentTime,
+        0.01
+        // 10ms transition
+      );
+    }
+  }
+  /**
+   * Stop isochronic tone generation
+   */
+  stop() {
+    this.isPlaying = false;
+    if (this.lookaheadTimer !== null) {
+      clearTimeout(this.lookaheadTimer);
+      this.lookaheadTimer = null;
+    }
+    if (this.nodes) {
+      try {
+        this.nodes.gainNode.gain.setTargetAtTime(0, this.ctx.currentTime, 0.01);
+        setTimeout(() => {
+          if (this.nodes) {
+            try {
+              this.nodes.carrier.stop();
+            } catch {
+            }
+          }
+        }, 20);
+      } catch {
+      }
+      this.nodes.carrier.disconnect();
+      this.nodes.gainNode.disconnect();
+      this.nodes = null;
+    }
+    this.config = null;
+    this.nextEventTime = 0;
+  }
+  /**
+   * Check if generator is active
+   */
+  isActive() {
+    return this.nodes !== null && this.isPlaying;
+  }
+};
+
+// src/MonauralGenerator.ts
+var MonauralGenerator = class {
+  constructor(ctx) {
+    this.nodes = null;
+    this.config = null;
+    this.ctx = ctx;
+  }
+  /**
+   * Start monaural beat generation
+   *
+   * @param config - Monaural generator configuration
+   * @param masterGain - Master gain node to connect to
+   */
+  start(config, masterGain) {
+    this.stop();
+    this.config = config;
+    const frequency1 = config.frequency1;
+    const frequency2 = frequency1 + config.beatFrequency;
+    const osc1 = this.ctx.createOscillator();
+    const osc2 = this.ctx.createOscillator();
+    osc1.frequency.value = frequency1;
+    osc2.frequency.value = frequency2;
+    const gainNode = this.ctx.createGain();
+    gainNode.gain.value = config.volume;
+    osc1.connect(gainNode);
+    osc2.connect(gainNode);
+    gainNode.connect(masterGain);
+    osc1.start();
+    osc2.start();
+    this.nodes = {
+      osc1,
+      osc2,
+      gainNode
+    };
+  }
+  /**
+   * Update generator parameters
+   */
+  updateConfig(config) {
+    if (!this.nodes || !this.config) {
+      return;
+    }
+    const newConfig = { ...this.config, ...config };
+    this.config = newConfig;
+    if (config.volume !== void 0) {
+      this.nodes.gainNode.gain.setTargetAtTime(
+        config.volume,
+        this.ctx.currentTime,
+        0.01
+      );
+    }
+    if (config.frequency1 !== void 0 || config.beatFrequency !== void 0) {
+      const freq1 = config.frequency1 ?? this.config.frequency1;
+      const beatFreq = config.beatFrequency ?? this.config.beatFrequency;
+      const freq2 = freq1 + beatFreq;
+      this.nodes.osc1.frequency.value = freq1;
+      this.nodes.osc2.frequency.value = freq2;
+    }
+  }
+  /**
+   * Stop monaural beat generation
+   */
+  stop() {
+    if (this.nodes) {
+      try {
+        this.nodes.osc1.stop();
+        this.nodes.osc2.stop();
+      } catch {
+      }
+      this.nodes.osc1.disconnect();
+      this.nodes.osc2.disconnect();
+      this.nodes.gainNode.disconnect();
+      this.nodes = null;
+    }
+    this.config = null;
+  }
+  /**
+   * Check if generator is active
+   */
+  isActive() {
+    return this.nodes !== null;
+  }
+};
+
+// src/BrownNoiseGenerator.ts
+var BrownNoiseGenerator = class {
+  constructor(ctx) {
+    this.nodes = null;
+    this.volume = 0.15;
+    // Default subtle volume
+    this.buffer = null;
+    this.ctx = ctx;
+  }
+  /**
+   * Create brown noise buffer
+   * Generates a seamless loop of brown noise
+   */
+  createBrownNoiseBuffer() {
+    const bufferSize = this.ctx.sampleRate * 5;
+    const buffer = this.ctx.createBuffer(1, bufferSize, this.ctx.sampleRate);
+    const data = buffer.getChannelData(0);
+    let lastOut = 0;
+    for (let i = 0; i < bufferSize; i++) {
+      const white = Math.random() * 2 - 1;
+      data[i] = (lastOut + 0.02 * white) / 1.02;
+      lastOut = data[i];
+      data[i] *= 3.5;
+    }
+    return buffer;
+  }
+  /**
+   * Start brown noise generation
+   *
+   * @param volume - Volume level (0.0 to 1.0)
+   * @param masterGain - Master gain node to connect to
+   */
+  start(volume, masterGain) {
+    this.volume = volume;
+    this.stop();
+    if (!this.buffer) {
+      this.buffer = this.createBrownNoiseBuffer();
+    }
+    const bufferSource = this.ctx.createBufferSource();
+    bufferSource.buffer = this.buffer;
+    bufferSource.loop = true;
+    const gainNode = this.ctx.createGain();
+    gainNode.gain.value = volume;
+    bufferSource.connect(gainNode).connect(masterGain);
+    bufferSource.start();
+    this.nodes = {
+      bufferSource,
+      gainNode
+    };
+  }
+  /**
+   * Update volume
+   */
+  updateVolume(volume) {
+    this.volume = volume;
+    if (this.nodes) {
+      this.nodes.gainNode.gain.setTargetAtTime(
+        volume,
+        this.ctx.currentTime,
+        0.01
+      );
+    }
+  }
+  /**
+   * Stop brown noise generation
+   */
+  stop() {
+    if (this.nodes) {
+      try {
+        this.nodes.bufferSource.stop();
+      } catch {
+      }
+      this.nodes.bufferSource.disconnect();
+      this.nodes.gainNode.disconnect();
+      this.nodes = null;
+    }
+  }
+  /**
+   * Check if generator is active
+   */
+  isActive() {
+    return this.nodes !== null;
+  }
+};
+
+// src/PinkNoiseGenerator.ts
+var PinkNoiseGenerator = class {
+  constructor(ctx) {
+    this.nodes = null;
+    this.volume = 0.15;
+    // Default subtle volume
+    this.buffer = null;
+    this.ctx = ctx;
+  }
+  /**
+   * Create pink noise buffer
+   * Generates a seamless loop of pink noise using Voss-McCartney algorithm
+   */
+  createPinkNoiseBuffer() {
+    const bufferSize = this.ctx.sampleRate * 5;
+    const buffer = this.ctx.createBuffer(1, bufferSize, this.ctx.sampleRate);
+    const data = buffer.getChannelData(0);
+    const numRows = 16;
+    const rowValues = new Array(numRows).fill(0);
+    let index = 0;
+    let indexMask = 0;
+    let sum = 0;
+    for (let i = 0; i < numRows; i++) {
+      rowValues[i] = Math.random() * 2 - 1;
+      sum += rowValues[i];
+    }
+    for (let i = 0; i < bufferSize; i++) {
+      index = index + 1 & indexMask;
+      if (index === 0) {
+        indexMask = indexMask << 1 | 1;
+        const numRowsToUpdate = Math.min(
+          numRows,
+          Math.floor(Math.log2(i + 1)) + 1
+        );
+        for (let j = 0; j < numRowsToUpdate; j++) {
+          rowValues[j] = Math.random() * 2 - 1;
+        }
+      }
+      let rowToUpdate = 0;
+      let temp = index;
+      while ((temp & 1) === 0 && rowToUpdate < numRows - 1) {
+        temp >>= 1;
+        rowToUpdate++;
+      }
+      sum -= rowValues[rowToUpdate];
+      rowValues[rowToUpdate] = Math.random() * 2 - 1;
+      sum += rowValues[rowToUpdate];
+      data[i] = sum / numRows;
+      data[i] *= 0.5;
+    }
+    return buffer;
+  }
+  /**
+   * Start pink noise generation
+   *
+   * @param volume - Volume level (0.0 to 1.0)
+   * @param masterGain - Master gain node to connect to
+   */
+  start(volume, masterGain) {
+    this.volume = volume;
+    this.stop();
+    if (!this.buffer) {
+      this.buffer = this.createPinkNoiseBuffer();
+    }
+    const bufferSource = this.ctx.createBufferSource();
+    bufferSource.buffer = this.buffer;
+    bufferSource.loop = true;
+    const gainNode = this.ctx.createGain();
+    gainNode.gain.value = volume;
+    bufferSource.connect(gainNode).connect(masterGain);
+    bufferSource.start();
+    this.nodes = {
+      bufferSource,
+      gainNode
+    };
+  }
+  /**
+   * Update volume
+   */
+  updateVolume(volume) {
+    this.volume = volume;
+    if (this.nodes) {
+      this.nodes.gainNode.gain.setTargetAtTime(
+        volume,
+        this.ctx.currentTime,
+        0.01
+      );
+    }
+  }
+  /**
+   * Stop pink noise generation
+   */
+  stop() {
+    if (this.nodes) {
+      try {
+        this.nodes.bufferSource.stop();
+      } catch {
+      }
+      this.nodes.bufferSource.disconnect();
+      this.nodes.gainNode.disconnect();
+      this.nodes = null;
+    }
+  }
+  /**
+   * Check if generator is active
+   */
+  isActive() {
+    return this.nodes !== null;
+  }
+};
+
+// src/EntrainmentEngine.ts
+var EntrainmentEngine = class {
+  constructor() {
+    this.ctx = null;
+    this.masterGain = null;
+    this.binauralGenerator = null;
+    this.isochronicGenerator = null;
+    this.monauralGenerator = null;
+    this.brownNoiseGenerator = null;
+    this.pinkNoiseGenerator = null;
+    this.config = null;
+    this.state = "stopped";
+    this.sessionStartTime = 0;
+    this.currentFrequency = 0;
+    this.targetFrequency = 0;
+    this.rampingInterval = null;
+  }
+  /**
+   * Initialize AudioContext
+   * Must be called from user gesture (button click) due to browser autoplay policy
+   */
+  async initialize() {
+    if (this.ctx) {
+      return;
+    }
+    const AudioContextClass = window.AudioContext || window.webkitAudioContext;
+    if (!AudioContextClass) {
+      throw new Error("Web Audio API is not supported in this browser");
+    }
+    this.ctx = new AudioContextClass();
+    this.masterGain = this.ctx.createGain();
+    this.masterGain.gain.value = 0.8;
+    this.masterGain.connect(this.ctx.destination);
+    this.binauralGenerator = new BinauralGenerator(this.ctx);
+    this.isochronicGenerator = new IsochronicGenerator(this.ctx);
+    this.monauralGenerator = new MonauralGenerator(this.ctx);
+    this.brownNoiseGenerator = new BrownNoiseGenerator(this.ctx);
+    this.pinkNoiseGenerator = new PinkNoiseGenerator(this.ctx);
+  }
+  /**
+   * Resume AudioContext if suspended
+   * Required due to browser autoplay policy
+   */
+  async resume() {
+    if (!this.ctx) {
+      await this.initialize();
+    }
+    if (this.ctx && this.ctx.state === "suspended") {
+      await this.ctx.resume();
+    }
+  }
+  /**
+   * Start entrainment with configuration
+   */
+  async start(config) {
+    if (!this.ctx || !this.masterGain) {
+      await this.initialize();
+    }
+    if (!this.ctx || !this.masterGain) {
+      throw new Error("AudioContext not initialized");
+    }
+    await this.resume();
+    this.config = config;
+    let newTargetFrequency;
+    if (config.preset && !config.manualMode) {
+      const preset = getPreset(config.preset);
+      newTargetFrequency = preset.targetFrequency;
+    } else if (config.manualBeatFrequency) {
+      newTargetFrequency = config.manualBeatFrequency;
+    } else {
+      throw new Error("No preset or manual frequency specified");
+    }
+    if (config.progressiveRamping && this.currentFrequency > 0) {
+      const frequencyDiff = Math.abs(
+        newTargetFrequency - this.currentFrequency
+      );
+      const maxJump = Math.max(2, this.currentFrequency * 0.2);
+      if (frequencyDiff > maxJump) {
+        this.targetFrequency = newTargetFrequency;
+        this.startProgressiveRamp(config);
+        return;
+      }
+    }
+    this.targetFrequency = newTargetFrequency;
+    this.currentFrequency = newTargetFrequency;
+    if (config.mode === "headphones" && config.generators.binaural.enabled) {
+      const binauralConfig = config.generators.binaural;
+      const carrierFreq = config.manualMode && config.manualCarrierFrequency ? config.manualCarrierFrequency : binauralConfig.carrierFrequency;
+      if (!validateOsterCurve(carrierFreq)) {
+        console.warn(
+          `Binaural beats work best with carrier frequency 400-500 Hz (Oster Curve). Got ${carrierFreq} Hz.`
+        );
+      }
+      this.binauralGenerator.start(
+        {
+          ...binauralConfig,
+          carrierFrequency: carrierFreq,
+          beatFrequency: this.currentFrequency
+        },
+        this.masterGain
+      );
+    } else if (config.mode === "speaker") {
+      if (config.generators.isochronic.enabled) {
+        const isochronicConfig = config.generators.isochronic;
+        const carrierFreq = config.manualMode && config.manualCarrierFrequency ? config.manualCarrierFrequency : isochronicConfig.carrierFrequency || 200;
+        this.isochronicGenerator.start(
+          {
+            ...isochronicConfig,
+            carrierFrequency: carrierFreq,
+            beatFrequency: this.currentFrequency
+          },
+          this.masterGain
+        );
+      } else if (config.generators.monaural?.enabled) {
+        const monauralConfig = config.generators.monaural;
+        const frequency1 = config.manualMode && config.manualCarrierFrequency ? config.manualCarrierFrequency : monauralConfig.frequency1 || 200;
+        this.monauralGenerator.start(
+          {
+            ...monauralConfig,
+            frequency1,
+            frequency2: frequency1 + this.currentFrequency,
+            beatFrequency: this.currentFrequency
+          },
+          this.masterGain
+        );
+      }
+    }
+    if (config.generators.brownNoise.enabled) {
+      this.brownNoiseGenerator.start(
+        config.generators.brownNoise.volume,
+        this.masterGain
+      );
+    }
+    if (config.generators.pinkNoise?.enabled) {
+      this.pinkNoiseGenerator.start(
+        config.generators.pinkNoise.volume,
+        this.masterGain
+      );
+    }
+    this.masterGain.gain.value = config.masterVolume * 0.8;
+    this.state = "playing";
+    this.sessionStartTime = Date.now();
+  }
+  /**
+   * Progressive ramping system for gradual frequency transitions
+   * Prevents jumping too far from current state (entrainment best practice)
+   */
+  startProgressiveRamp(config) {
+    if (this.rampingInterval !== null) {
+      clearInterval(this.rampingInterval);
+    }
+    const startFreq = this.currentFrequency;
+    const endFreq = this.targetFrequency;
+    const duration = config.rampingDuration || 30;
+    const steps = 60;
+    const stepDuration = duration * 1e3 / steps;
+    let currentStep = 0;
+    this.startGeneratorsWithFrequency(config, startFreq);
+    this.rampingInterval = setInterval(() => {
+      currentStep++;
+      const progress = currentStep / steps;
+      this.currentFrequency = startFreq + (endFreq - startFreq) * progress;
+      this.updateFrequencyInGenerators(this.currentFrequency);
+      if (currentStep >= steps) {
+        this.currentFrequency = endFreq;
+        this.updateFrequencyInGenerators(endFreq);
+        if (this.rampingInterval !== null) {
+          clearInterval(this.rampingInterval);
+          this.rampingInterval = null;
+        }
+      }
+    }, stepDuration);
+  }
+  /**
+   * Start generators with specific frequency
+   */
+  startGeneratorsWithFrequency(config, frequency) {
+    if (config.mode === "headphones" && config.generators.binaural.enabled) {
+      const binauralConfig = config.generators.binaural;
+      const carrierFreq = config.manualMode && config.manualCarrierFrequency ? config.manualCarrierFrequency : binauralConfig.carrierFrequency;
+      this.binauralGenerator.start(
+        {
+          ...binauralConfig,
+          carrierFrequency: carrierFreq,
+          beatFrequency: frequency
+        },
+        this.masterGain
+      );
+    } else if (config.mode === "speaker") {
+      if (config.generators.isochronic.enabled) {
+        const isochronicConfig = config.generators.isochronic;
+        const carrierFreq = config.manualMode && config.manualCarrierFrequency ? config.manualCarrierFrequency : isochronicConfig.carrierFrequency || 200;
+        this.isochronicGenerator.start(
+          {
+            ...isochronicConfig,
+            carrierFrequency: carrierFreq,
+            beatFrequency: frequency
+          },
+          this.masterGain
+        );
+      } else if (config.generators.monaural?.enabled) {
+        const monauralConfig = config.generators.monaural;
+        const frequency1 = config.manualMode && config.manualCarrierFrequency ? config.manualCarrierFrequency : monauralConfig.frequency1 || 200;
+        this.monauralGenerator.start(
+          {
+            ...monauralConfig,
+            frequency1,
+            frequency2: frequency1 + frequency,
+            beatFrequency: frequency
+          },
+          this.masterGain
+        );
+      }
+    }
+    if (config.generators.brownNoise.enabled) {
+      this.brownNoiseGenerator.start(
+        config.generators.brownNoise.volume,
+        this.masterGain
+      );
+    }
+    if (config.generators.pinkNoise?.enabled) {
+      this.pinkNoiseGenerator.start(
+        config.generators.pinkNoise.volume,
+        this.masterGain
+      );
+    }
+    this.masterGain.gain.value = config.masterVolume * 0.8;
+  }
+  /**
+   * Update frequency in active generators
+   */
+  updateFrequencyInGenerators(frequency) {
+    if (!this.config) {
+      return;
+    }
+    if (this.binauralGenerator?.isActive()) {
+      this.binauralGenerator.updateConfig({
+        beatFrequency: frequency
+      });
+    }
+    if (this.isochronicGenerator?.isActive()) {
+      this.isochronicGenerator.updateConfig({
+        beatFrequency: frequency
+      });
+    }
+    if (this.monauralGenerator?.isActive()) {
+      this.monauralGenerator.updateConfig({
+        beatFrequency: frequency
+      });
+    }
+  }
+  /**
+   * Stop entrainment
+   */
+  stop() {
+    if (this.rampingInterval !== null) {
+      clearInterval(this.rampingInterval);
+      this.rampingInterval = null;
+    }
+    this.binauralGenerator?.stop();
+    this.isochronicGenerator?.stop();
+    this.monauralGenerator?.stop();
+    this.brownNoiseGenerator?.stop();
+    this.pinkNoiseGenerator?.stop();
+    this.state = "stopped";
+    this.sessionStartTime = 0;
+    this.currentFrequency = 0;
+    this.targetFrequency = 0;
+  }
+  /**
+   * Pause entrainment
+   */
+  pause() {
+    if (this.state === "playing") {
+      if (this.masterGain) {
+        this.masterGain.gain.setTargetAtTime(0, this.ctx.currentTime, 0.1);
+      }
+      this.state = "paused";
+    }
+  }
+  /**
+   * Resume entrainment
+   */
+  async resumePlayback() {
+    if (this.state === "paused" && this.config) {
+      await this.resume();
+      if (this.masterGain) {
+        this.masterGain.gain.setTargetAtTime(
+          this.config.masterVolume * 0.8,
+          this.ctx.currentTime,
+          0.1
+        );
+      }
+      this.state = "playing";
+    }
+  }
+  /**
+   * Update configuration (for real-time parameter changes)
+   */
+  updateConfig(config) {
+    if (!this.config) {
+      return;
+    }
+    const newConfig = { ...this.config, ...config };
+    if (config.masterVolume !== void 0 && this.masterGain) {
+      this.masterGain.gain.setTargetAtTime(
+        config.masterVolume * 0.8,
+        this.ctx.currentTime,
+        0.01
+      );
+    }
+    if (config.generators) {
+      if (config.generators.binaural && this.binauralGenerator?.isActive()) {
+        this.binauralGenerator.updateConfig(config.generators.binaural);
+      }
+      if (config.generators.isochronic && this.isochronicGenerator?.isActive()) {
+        this.isochronicGenerator.updateConfig(config.generators.isochronic);
+      }
+      if (config.generators.monaural) {
+        if (config.generators.monaural.enabled && !this.monauralGenerator?.isActive()) {
+          const monauralConfig = config.generators.monaural;
+          const frequency1 = this.config.manualMode && this.config.manualCarrierFrequency ? this.config.manualCarrierFrequency : monauralConfig.frequency1 || 200;
+          this.monauralGenerator.start(
+            {
+              ...monauralConfig,
+              frequency1,
+              frequency2: frequency1 + this.currentFrequency,
+              beatFrequency: this.currentFrequency
+            },
+            this.masterGain
+          );
+        } else if (!config.generators.monaural.enabled && this.monauralGenerator?.isActive()) {
+          this.monauralGenerator.stop();
+        } else if (this.monauralGenerator?.isActive()) {
+          this.monauralGenerator.updateConfig(config.generators.monaural);
+        }
+      }
+      if (config.generators.brownNoise) {
+        if (config.generators.brownNoise.enabled && !this.brownNoiseGenerator?.isActive()) {
+          this.brownNoiseGenerator.start(
+            config.generators.brownNoise.volume,
+            this.masterGain
+          );
+        } else if (!config.generators.brownNoise.enabled && this.brownNoiseGenerator?.isActive()) {
+          this.brownNoiseGenerator.stop();
+        } else if (config.generators.brownNoise.volume !== void 0) {
+          this.brownNoiseGenerator.updateVolume(
+            config.generators.brownNoise.volume
+          );
+        }
+      }
+      if (config.generators.pinkNoise) {
+        if (config.generators.pinkNoise.enabled && !this.pinkNoiseGenerator?.isActive()) {
+          this.pinkNoiseGenerator.start(
+            config.generators.pinkNoise.volume,
+            this.masterGain
+          );
+        } else if (!config.generators.pinkNoise.enabled && this.pinkNoiseGenerator?.isActive()) {
+          this.pinkNoiseGenerator.stop();
+        } else if (config.generators.pinkNoise.volume !== void 0) {
+          this.pinkNoiseGenerator.updateVolume(
+            config.generators.pinkNoise.volume
+          );
+        }
+      }
+    }
+    this.config = newConfig;
+  }
+  /**
+   * Get current session information
+   */
+  getSessionInfo() {
+    const duration = this.sessionStartTime > 0 ? Math.floor((Date.now() - this.sessionStartTime) / 1e3) : 0;
+    return {
+      startTime: this.sessionStartTime,
+      duration,
+      currentFrequency: this.currentFrequency,
+      targetFrequency: this.targetFrequency,
+      state: this.state
+    };
+  }
+  /**
+   * Get AudioContext (for visualization/analysis)
+   */
+  getContext() {
+    return this.ctx;
+  }
+  /**
+   * Get master gain node (for visualization/analysis)
+   */
+  getMasterGain() {
+    return this.masterGain;
+  }
+  /**
+   * Cleanup - disconnect all nodes and close AudioContext
+   */
+  cleanup() {
+    this.stop();
+    if (this.masterGain) {
+      this.masterGain.disconnect();
+      this.masterGain = null;
+    }
+    if (this.ctx && this.ctx.state !== "closed") {
+      this.ctx.close();
+      this.ctx = null;
+    }
+    this.binauralGenerator = null;
+    this.isochronicGenerator = null;
+    this.monauralGenerator = null;
+    this.brownNoiseGenerator = null;
+    this.pinkNoiseGenerator = null;
+    this.config = null;
+  }
+};
+export {
+  ALPHA_PRESET,
+  BRAINWAVE_PRESETS,
+  BinauralGenerator,
+  BrownNoiseGenerator,
+  DELTA_PRESET,
+  DRIVING_WARNING,
+  EPILEPSY_WARNING,
+  EntrainmentEngine,
+  GAMMA_PRESET,
+  HIGH_BETA_PRESET,
+  IsochronicGenerator,
+  LOW_BETA_PRESET,
+  MENTAL_HEALTH_WARNING,
+  MID_BETA_PRESET,
+  MonauralGenerator,
+  PACEMAKER_WARNING,
+  PinkNoiseGenerator,
+  STROBING_WARNING,
+  THETA_PRESET,
+  getAllSafetyWarnings,
+  getPreset,
+  getPresetByFrequency,
+  getRecommendedCarrierFrequency,
+  getSafetyWarnings,
+  isPhotosensitiveTriggerRange,
+  validateOsterCurve
+};