@affectively/entrainment-audio 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,589 @@
+/**
+ * Entrainment Audio Types
+ *
+ * TypeScript interfaces and types for brainwave entrainment system
+ */
+/**
+ * Brainwave frequency bands based on EEG classification
+ */
+type BrainwaveBand = 'delta' | 'theta' | 'alpha' | 'low-beta' | 'mid-beta' | 'high-beta' | 'gamma';
+/**
+ * Generator types available in the entrainment engine
+ */
+type GeneratorType = 'binaural' | 'isochronic' | 'monaural' | 'brown-noise' | 'pink-noise';
+/**
+ * Playback state
+ */
+type PlaybackState = 'stopped' | 'playing' | 'paused';
+/**
+ * Brainwave preset configuration
+ */
+interface BrainwavePreset {
+    id: BrainwaveBand;
+    name: string;
+    description: string;
+    frequencyRange: {
+        min: number;
+        max: number;
+    };
+    targetFrequency: number;
+    carrierFrequency: number;
+    color: string;
+    useCase: string;
+}
+/**
+ * Generator configuration
+ */
+interface GeneratorConfig {
+    enabled: boolean;
+    volume: number;
+    type: GeneratorType;
+}
+/**
+ * Binaural generator configuration
+ */
+interface BinauralConfig extends GeneratorConfig {
+    type: 'binaural';
+    carrierFrequency: number;
+    beatFrequency: number;
+}
+/**
+ * Isochronic generator configuration
+ */
+interface IsochronicConfig extends GeneratorConfig {
+    type: 'isochronic';
+    carrierFrequency: number;
+    beatFrequency: number;
+    dutyCycle: number;
+    attackTime: number;
+    releaseTime: number;
+}
+/**
+ * Monaural generator configuration
+ */
+interface MonauralConfig extends GeneratorConfig {
+    type: 'monaural';
+    frequency1: number;
+    frequency2: number;
+    beatFrequency: number;
+}
+/**
+ * Brown noise generator configuration
+ */
+interface BrownNoiseConfig extends GeneratorConfig {
+    type: 'brown-noise';
+    filterStrength: number;
+}
+/**
+ * Pink noise generator configuration
+ */
+interface PinkNoiseConfig extends GeneratorConfig {
+    type: 'pink-noise';
+    filterStrength: number;
+}
+/**
+ * Complete entrainment engine configuration
+ */
+interface EntrainmentConfig {
+    preset?: BrainwaveBand;
+    manualMode: boolean;
+    manualCarrierFrequency?: number;
+    manualBeatFrequency?: number;
+    generators: {
+        binaural: BinauralConfig;
+        isochronic: IsochronicConfig;
+        monaural?: MonauralConfig;
+        brownNoise: BrownNoiseConfig;
+        pinkNoise?: PinkNoiseConfig;
+    };
+    masterVolume: number;
+    progressiveRamping: boolean;
+    rampingDuration: number;
+    mode: 'headphones' | 'speaker';
+    durationSeconds?: number;
+}
+/**
+ * Session information
+ */
+interface SessionInfo {
+    startTime: number;
+    duration: number;
+    currentFrequency: number;
+    targetFrequency: number;
+    state: PlaybackState;
+}
+/**
+ * Safety warnings configuration
+ */
+interface SafetyWarnings {
+    epilepsy: boolean;
+    driving: boolean;
+    pacemakers: boolean;
+    mentalHealth: boolean;
+}
+/**
+ * User settings for persistence
+ */
+interface EntrainmentSettings {
+    lastPreset?: BrainwaveBand;
+    lastManualConfig?: {
+        carrierFrequency: number;
+        beatFrequency: number;
+    };
+    generatorStates: {
+        binaural: boolean;
+        isochronic: boolean;
+        monaural: boolean;
+        brownNoise: boolean;
+    };
+    volumeLevels: {
+        master: number;
+        binaural: number;
+        isochronic: number;
+        monaural: number;
+        brownNoise: number;
+    };
+    mode: 'headphones' | 'speaker';
+    progressiveRamping: boolean;
+}
+
+/**
+ * Brainwave State Presets
+ *
+ * Based on EEG frequency bands and scientific research on brainwave entrainment.
+ * Each preset defines carrier frequency, beat frequency, and recommended applications.
+ */
+
+/**
+ * Delta (0.5-4 Hz): Deep sleep, unconsciousness, restoration
+ * Stage 3-4 NREM sleep. Below human hearing range, must use rhythmic modulation.
+ */
+declare const DELTA_PRESET: BrainwavePreset;
+/**
+ * Theta (4-8 Hz): Deep meditation, creativity, memory encoding
+ * Limbic system and hippocampal regions. Hypnagogic state.
+ */
+declare const THETA_PRESET: BrainwavePreset;
+/**
+ * Alpha (8-12 Hz): Relaxed alertness, "flow" state
+ * Visual cortex idling. Bridge between conscious and subconscious.
+ */
+declare const ALPHA_PRESET: BrainwavePreset;
+/**
+ * Low Beta / SMR (12-15 Hz): Calm focus, stillness
+ * Sensorimotor rhythm. Used in ADHD neurofeedback.
+ */
+declare const LOW_BETA_PRESET: BrainwavePreset;
+/**
+ * Mid Beta (15-20 Hz): Active focus, problem-solving
+ * Active cortical computation. Standard cognitive maintenance.
+ */
+declare const MID_BETA_PRESET: BrainwavePreset;
+/**
+ * High Beta (20-30 Hz): High energy, excitement
+ * Intense metabolic consumption. Can induce anxiety if prolonged.
+ */
+declare const HIGH_BETA_PRESET: BrainwavePreset;
+/**
+ * Gamma (30-100+ Hz): Peak performance, insight
+ * Cross-modal synchronization. Cognitive binding.
+ */
+declare const GAMMA_PRESET: BrainwavePreset;
+/**
+ * All available brainwave presets
+ */
+declare const BRAINWAVE_PRESETS: Record<BrainwaveBand, BrainwavePreset>;
+/**
+ * Get preset by ID
+ */
+declare function getPreset(band: BrainwaveBand): BrainwavePreset;
+/**
+ * Get preset by frequency (finds closest matching preset)
+ */
+declare function getPresetByFrequency(frequency: number): BrainwavePreset | null;
+/**
+ * Validate carrier frequency against Oster Curve (400-500 Hz for binaural beats)
+ */
+declare function validateOsterCurve(carrierFrequency: number): boolean;
+/**
+ * Get recommended carrier frequency (middle of Oster Curve)
+ */
+declare function getRecommendedCarrierFrequency(): number;
+
+/**
+ * Safety Warnings and Contraindications
+ *
+ * Safety protocols for auditory stimulation and brainwave entrainment
+ */
+
+/**
+ * Safety warning messages
+ */
+interface SafetyWarningMessage {
+    id: string;
+    title: string;
+    message: string;
+    severity: 'info' | 'warning' | 'critical';
+}
+/**
+ * Epilepsy warning (especially for visualizers)
+ * Musicogenic epilepsy is rare but non-zero risk
+ */
+declare const EPILEPSY_WARNING: SafetyWarningMessage;
+/**
+ * Driving warning (especially for Alpha/Theta/Delta)
+ * Can induce drowsiness and altered states
+ */
+declare const DRIVING_WARNING: SafetyWarningMessage;
+/**
+ * Pacemaker warning
+ * General headphone warning rather than specific to entrainment
+ */
+declare const PACEMAKER_WARNING: SafetyWarningMessage;
+/**
+ * Mental health warning
+ * Altered states can exacerbate certain conditions
+ */
+declare const MENTAL_HEALTH_WARNING: SafetyWarningMessage;
+/**
+ * Visual strobing warning (3-30 Hz range)
+ * Photosensitive epilepsy trigger
+ */
+declare const STROBING_WARNING: SafetyWarningMessage;
+/**
+ * Get safety warnings based on configuration
+ */
+declare function getSafetyWarnings(config: {
+    hasVisualizer?: boolean;
+    currentPreset?: BrainwaveBand;
+    frequency?: number;
+}): SafetyWarningMessage[];
+/**
+ * Check if frequency is in photosensitive epilepsy trigger range (3-30 Hz)
+ */
+declare function isPhotosensitiveTriggerRange(frequency: number): boolean;
+/**
+ * Get all safety warnings
+ */
+declare function getAllSafetyWarnings(): SafetyWarningMessage[];
+
+/**
+ * Binaural Beat Generator
+ *
+ * Generates binaural beats using hard-panned oscillators (left/right channels).
+ * Requires carrier frequency between 400-500 Hz (Oster Curve) for maximum effectiveness.
+ *
+ * Key Principle:
+ * - Left Ear: Carrier Frequency (e.g., 200 Hz)
+ * - Right Ear: Carrier + Target Beat (e.g., 210 Hz for a 10 Hz Alpha state)
+ *
+ * The brain perceives a wavering beat at the difference frequency (10 Hz) in the Superior Olivary Complex.
+ */
+
+interface BinauralNodes {
+    leftOsc: OscillatorNode;
+    rightOsc: OscillatorNode;
+    leftPan: StereoPannerNode;
+    rightPan: StereoPannerNode;
+    leftGain: GainNode;
+    rightGain: GainNode;
+}
+declare class BinauralGenerator {
+    private ctx;
+    private nodes;
+    private config;
+    constructor(ctx: AudioContext);
+    /**
+     * Start binaural beat generation
+     *
+     * @param config - Binaural generator configuration
+     * @param masterGain - Master gain node to connect to
+     */
+    start(config: BinauralConfig, masterGain: GainNode): void;
+    /**
+     * Update generator parameters
+     */
+    updateConfig(config: Partial<BinauralConfig>): void;
+    /**
+     * Stop binaural beat generation
+     */
+    stop(): void;
+    /**
+     * Check if generator is active
+     */
+    isActive(): boolean;
+}
+
+/**
+ * Isochronic Tone Generator
+ *
+ * Generates isochronic tones with 100% modulation depth.
+ * Uses gain envelopes with 5-10ms attack/release to prevent clicks (spectral splatter).
+ *
+ * Key Principle:
+ * - Single carrier tone is turned on and off at regular intervals
+ * - 100% modulation depth (silence to full volume) creates sharp rhythmic stimulus
+ * - Envelope shaping prevents speaker cone discontinuities that cause clicks
+ */
+
+interface IsochronicNodes {
+    carrier: OscillatorNode;
+    gainNode: GainNode;
+    scheduledEvents: number[];
+}
+declare class IsochronicGenerator {
+    private ctx;
+    private nodes;
+    private config;
+    private isPlaying;
+    private lookaheadTimer;
+    private nextEventTime;
+    private scheduleAheadTime;
+    constructor(ctx: AudioContext);
+    /**
+     * Start isochronic tone generation
+     *
+     * @param config - Isochronic generator configuration
+     * @param masterGain - Master gain node to connect to
+     */
+    start(config: IsochronicConfig, masterGain: GainNode): void;
+    /**
+     * Schedule isochronic pulses using lookahead scheduling
+     * Prevents CPU overload by scheduling 1-2 seconds ahead
+     */
+    private schedulePulses;
+    /**
+     * Update generator parameters
+     */
+    updateConfig(config: Partial<IsochronicConfig>): void;
+    /**
+     * Stop isochronic tone generation
+     */
+    stop(): void;
+    /**
+     * Check if generator is active
+     */
+    isActive(): boolean;
+}
+
+/**
+ * Monaural Beat Generator
+ *
+ * Generates monaural beats using physical interference between two frequencies.
+ * Unlike binaural beats (which require headphones), monaural beats are created by
+ * mixing two frequencies in the same channel, creating a physical beat that can
+ * be heard through speakers.
+ *
+ * Key Principle:
+ * - Frequency 1: Base frequency (e.g., 200 Hz)
+ * - Frequency 2: Base + Beat frequency (e.g., 210 Hz for a 10 Hz Alpha state)
+ * - The two frequencies are mixed, creating a physical interference pattern
+ * - The beat frequency is the difference between the two frequencies
+ */
+
+interface MonauralNodes {
+    osc1: OscillatorNode;
+    osc2: OscillatorNode;
+    gainNode: GainNode;
+}
+declare class MonauralGenerator {
+    private ctx;
+    private nodes;
+    private config;
+    constructor(ctx: AudioContext);
+    /**
+     * Start monaural beat generation
+     *
+     * @param config - Monaural generator configuration
+     * @param masterGain - Master gain node to connect to
+     */
+    start(config: MonauralConfig, masterGain: GainNode): void;
+    /**
+     * Update generator parameters
+     */
+    updateConfig(config: Partial<MonauralConfig>): void;
+    /**
+     * Stop monaural beat generation
+     */
+    stop(): void;
+    /**
+     * Check if generator is active
+     */
+    isActive(): boolean;
+}
+
+/**
+ * Brown Noise Generator
+ *
+ * Generates brown noise (1/f² power density) - the most soothing colored noise.
+ * Power density decreases by 6 dB per octave, heavily attenuating high frequencies.
+ * Results in a deep, rumbling texture similar to distant thunderstorm or large waterfall.
+ *
+ * Algorithm: Integrate white noise
+ * output = (lastOutput + (0.02 * whiteNoise)) / 1.02
+ */
+interface BrownNoiseNodes {
+    bufferSource: AudioBufferSourceNode;
+    gainNode: GainNode;
+}
+declare class BrownNoiseGenerator {
+    private ctx;
+    private nodes;
+    private volume;
+    private buffer;
+    constructor(ctx: AudioContext);
+    /**
+     * Create brown noise buffer
+     * Generates a seamless loop of brown noise
+     */
+    private createBrownNoiseBuffer;
+    /**
+     * Start brown noise generation
+     *
+     * @param volume - Volume level (0.0 to 1.0)
+     * @param masterGain - Master gain node to connect to
+     */
+    start(volume: number, masterGain: GainNode): void;
+    /**
+     * Update volume
+     */
+    updateVolume(volume: number): void;
+    /**
+     * Stop brown noise generation
+     */
+    stop(): void;
+    /**
+     * Check if generator is active
+     */
+    isActive(): boolean;
+}
+
+/**
+ * Pink Noise Generator
+ *
+ * Generates pink noise (1/f power density) - balanced colored noise.
+ * Power density decreases by 3 dB per octave, providing a more balanced
+ * frequency spectrum than brown noise.
+ * Results in a texture similar to steady rain or rustling leaves.
+ *
+ * Algorithm: Filtered white noise with 1/f spectral characteristics
+ */
+interface PinkNoiseNodes {
+    bufferSource: AudioBufferSourceNode;
+    gainNode: GainNode;
+}
+declare class PinkNoiseGenerator {
+    private ctx;
+    private nodes;
+    private volume;
+    private buffer;
+    constructor(ctx: AudioContext);
+    /**
+     * Create pink noise buffer
+     * Generates a seamless loop of pink noise using Voss-McCartney algorithm
+     */
+    private createPinkNoiseBuffer;
+    /**
+     * Start pink noise generation
+     *
+     * @param volume - Volume level (0.0 to 1.0)
+     * @param masterGain - Master gain node to connect to
+     */
+    start(volume: number, masterGain: GainNode): void;
+    /**
+     * Update volume
+     */
+    updateVolume(volume: number): void;
+    /**
+     * Stop pink noise generation
+     */
+    stop(): void;
+    /**
+     * Check if generator is active
+     */
+    isActive(): boolean;
+}
+
+/**
+ * Entrainment Engine
+ *
+ * Main coordinator class for brainwave entrainment system.
+ * Manages AudioContext, master gain, and all audio generators.
+ */
+
+declare class EntrainmentEngine {
+    private ctx;
+    private masterGain;
+    private binauralGenerator;
+    private isochronicGenerator;
+    private monauralGenerator;
+    private brownNoiseGenerator;
+    private pinkNoiseGenerator;
+    private config;
+    private state;
+    private sessionStartTime;
+    private currentFrequency;
+    private targetFrequency;
+    private rampingInterval;
+    /**
+     * Initialize AudioContext
+     * Must be called from user gesture (button click) due to browser autoplay policy
+     */
+    initialize(): Promise<void>;
+    /**
+     * Resume AudioContext if suspended
+     * Required due to browser autoplay policy
+     */
+    resume(): Promise<void>;
+    /**
+     * Start entrainment with configuration
+     */
+    start(config: EntrainmentConfig): Promise<void>;
+    /**
+     * Progressive ramping system for gradual frequency transitions
+     * Prevents jumping too far from current state (entrainment best practice)
+     */
+    private startProgressiveRamp;
+    /**
+     * Start generators with specific frequency
+     */
+    private startGeneratorsWithFrequency;
+    /**
+     * Update frequency in active generators
+     */
+    private updateFrequencyInGenerators;
+    /**
+     * Stop entrainment
+     */
+    stop(): void;
+    /**
+     * Pause entrainment
+     */
+    pause(): void;
+    /**
+     * Resume entrainment
+     */
+    resumePlayback(): Promise<void>;
+    /**
+     * Update configuration (for real-time parameter changes)
+     */
+    updateConfig(config: Partial<EntrainmentConfig>): void;
+    /**
+     * Get current session information
+     */
+    getSessionInfo(): SessionInfo;
+    /**
+     * Get AudioContext (for visualization/analysis)
+     */
+    getContext(): AudioContext | null;
+    /**
+     * Get master gain node (for visualization/analysis)
+     */
+    getMasterGain(): GainNode | null;
+    /**
+     * Cleanup - disconnect all nodes and close AudioContext
+     */
+    cleanup(): void;
+}
+
+export { ALPHA_PRESET, BRAINWAVE_PRESETS, type BinauralConfig, BinauralGenerator, type BinauralNodes, type BrainwaveBand, type BrainwavePreset, type BrownNoiseConfig, BrownNoiseGenerator, type BrownNoiseNodes, DELTA_PRESET, DRIVING_WARNING, EPILEPSY_WARNING, type EntrainmentConfig, EntrainmentEngine, type EntrainmentSettings, GAMMA_PRESET, type GeneratorConfig, type GeneratorType, HIGH_BETA_PRESET, type IsochronicConfig, IsochronicGenerator, type IsochronicNodes, LOW_BETA_PRESET, MENTAL_HEALTH_WARNING, MID_BETA_PRESET, type MonauralConfig, MonauralGenerator, type MonauralNodes, PACEMAKER_WARNING, type PinkNoiseConfig, PinkNoiseGenerator, type PinkNoiseNodes, type PlaybackState, STROBING_WARNING, type SafetyWarningMessage, type SafetyWarnings, type SessionInfo, THETA_PRESET, getAllSafetyWarnings, getPreset, getPresetByFrequency, getRecommendedCarrierFrequency, getSafetyWarnings, isPhotosensitiveTriggerRange, validateOsterCurve };