@affectively/entrainment-audio 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-01-25
+
+### Added
+
+- Initial release
+- `EntrainmentEngine` - Main coordinator class
+- `BinauralGenerator` - Binaural beats with Oster Curve validation
+- `IsochronicGenerator` - Isochronic tones with envelope shaping
+- `MonauralGenerator` - Monaural beats for speaker playback
+- `BrownNoiseGenerator` - Brown noise (1/f²)
+- `PinkNoiseGenerator` - Pink noise (1/f)
+- Brainwave presets: Delta, Theta, Alpha, Low/Mid/High Beta, Gamma
+- Progressive frequency ramping
+- Safety warnings system
+- Full TypeScript support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AFFECTIVELY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# @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
+
+```bash
+npm install @affectively/entrainment-audio
+# or
+bun add @affectively/entrainment-audio
+# or
+yarn add @affectively/entrainment-audio
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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