@affectively/entrainment-audio

Brainwave entrainment audio generators using the Web Audio API. Generate binaural beats, isochronic tones, monaural beats, and colored noise for meditation, focus, and relaxation applications.

Features

• Binaural Beats - Stereo-separated tones that create perceived frequencies in the brain (requires headphones)
• Isochronic Tones - Pulsed tones with 100% modulation depth for speaker playback
• Monaural Beats - Physical interference patterns created by mixing two frequencies
• Brown Noise - Deep, rumbling colored noise (1/f²) for masking and relaxation
• Pink Noise - Balanced colored noise (1/f) like steady rain
• Preset Library - Science-based presets for Delta, Theta, Alpha, Beta, and Gamma states
• Progressive Ramping - Gradual frequency transitions for smoother entrainment
• Safety Warnings - Built-in safety protocols and user warnings

Installation

npm install @affectively/entrainment-audio
# or
bun add @affectively/entrainment-audio
# or
yarn add @affectively/entrainment-audio

Quick Start

import { EntrainmentEngine, BRAINWAVE_PRESETS } from '@affectively/entrainment-audio';

// Create engine instance
const engine = new EntrainmentEngine();

// Initialize (must be called from user gesture due to browser autoplay policy)
await engine.initialize();

// Start alpha wave entrainment (10 Hz) with brown noise
await engine.start({
  preset: 'alpha',
  manualMode: false,
  generators: {
    binaural: {
      enabled: true,
      volume: 0.5,
      type: 'binaural',
      carrierFrequency: 450, // Oster Curve: 400-500 Hz
      beatFrequency: 10,
    },
    isochronic: {
      enabled: false,
      volume: 0.5,
      type: 'isochronic',
      carrierFrequency: 200,
      beatFrequency: 10,
      dutyCycle: 0.5,
      attackTime: 5,
      releaseTime: 5,
    },
    brownNoise: {
      enabled: true,
      volume: 0.15,
      type: 'brown-noise',
      filterStrength: 0.02,
    },
  },
  masterVolume: 0.8,
  progressiveRamping: true,
  rampingDuration: 30,
  mode: 'headphones',
});

// Stop entrainment
engine.stop();

// Cleanup when done
engine.cleanup();

Brainwave Presets

| Preset | Frequency | Use Case | |--------|-----------|----------| | delta | 0.5-4 Hz | Deep sleep, restoration | | theta | 4-8 Hz | Meditation, creativity | | alpha | 8-12 Hz | Relaxed alertness, flow state | | low-beta | 12-15 Hz | Calm focus (SMR) | | mid-beta | 15-20 Hz | Active focus, problem-solving | | high-beta | 20-30 Hz | High energy, alertness | | gamma | 30-100 Hz | Peak performance, insight |

Using Individual Generators

import { BinauralGenerator, IsochronicGenerator, BrownNoiseGenerator } from '@affectively/entrainment-audio';

// Create AudioContext
const ctx = new AudioContext();
const masterGain = ctx.createGain();
masterGain.connect(ctx.destination);

// Binaural beats (requires headphones)
const binaural = new BinauralGenerator(ctx);
binaural.start({
  enabled: true,
  volume: 0.5,
  type: 'binaural',
  carrierFrequency: 450,
  beatFrequency: 10, // Alpha wave
}, masterGain);

// Stop after use
binaural.stop();

Safety Warnings

import { getSafetyWarnings, getAllSafetyWarnings } from '@affectively/entrainment-audio';

// Get warnings for current configuration
const warnings = getSafetyWarnings({
  hasVisualizer: true,
  currentPreset: 'alpha',
});

// All warnings include:
// - Epilepsy warning (for visual effects)
// - Driving warning (for low-frequency presets)
// - Pacemaker warning
// - Mental health considerations
// - Visual strobing warning

The Oster Curve

Binaural beats work best with carrier frequencies between 400-500 Hz (the "Oster Curve"). The library validates this automatically:

import { validateOsterCurve, getRecommendedCarrierFrequency } from '@affectively/entrainment-audio';

validateOsterCurve(450); // true
validateOsterCurve(200); // false

const recommended = getRecommendedCarrierFrequency(); // 450 Hz

API Reference

EntrainmentEngine

Main coordinator class that manages all generators.

• initialize() - Initialize AudioContext (call from user gesture)
• start(config) - Start entrainment with configuration
• stop() - Stop all generators
• pause() - Pause playback
• resumePlayback() - Resume from pause
• updateConfig(config) - Update parameters in real-time
• getSessionInfo() - Get current session state
• cleanup() - Disconnect and close AudioContext

Individual Generators

• BinauralGenerator - Binaural beat generation
• IsochronicGenerator - Isochronic tone generation
• MonauralGenerator - Monaural beat generation
• BrownNoiseGenerator - Brown noise generation
• PinkNoiseGenerator - Pink noise generation

Browser Support

Requires Web Audio API support (all modern browsers).

License

MIT © AFFECTIVELY