@shiihaa/breath-detection 1.0.0

package/dist/index.mjs

@@ -0,0 +1,545 @@
+/**
+ * @shiihaa/breath-detection
+ * Real-time breath cycle detection using microphone energy analysis,
+ * spectral centroid classification, and optional BLE heart rate data.
+ *
+ * © 2026 shii · haa — Felix Zeller
+ * MIT License
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BreathDetector
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class BreathDetector {
+  opts;
+  audioCtx = null;
+  analyser = null;
+  micStream = null;
+  source = null;
+  freqData = null;
+  timeData = null;
+
+  // State
+  running = false;
+  calibrated = false;
+  noiseFloor = 0;
+  breathMax = 0;
+  smoothedEnergy = 0;
+  smoothedCentroid = 500;
+  tickInterval = null;
+
+  // State machine
+  state = 'idle';
+  stateStart = 0;
+  aboveStart = 0;
+  belowStart = 0;
+  peakEnergy = 0;
+  cycleData = {};
+  recentCycleDurations = [];
+  lastCycleEndTime = 0;
+
+  // Centroid tracking per phase
+  centroidSumA1 = 0;
+  centroidCountA1 = 0;
+  centroidSumA2 = 0;
+  centroidCountA2 = 0;
+
+  // Energy trend
+  prevEnergy = 0;
+  energyRising = false;
+  energyFallingStart = 0;
+  energyPeakVal = 0;
+
+  // Peak-based detection
+  peakCount = 0;
+  lastPeakTime = 0;
+  peakCycleStart = 0;
+
+  // Auto-recalibration
+  recentEnergySamples = [];
+  lastRecalTime = 0;
+
+  // Callbacks
+  onCycleCallbacks[] = [];
+  onPhaseCallbacks[] = [];
+  onCalibrationCallbacks[] = [];
+  onEnergyCallbacks[] = [];
+
+  // External data (BLE)
+  externalHR = null;
+  prevHR = null;
+
+  constructor(options?) {
+    this.opts = {
+      fftSize: options?.fftSize ?? 4096,
+      smoothingAlpha: options?.smoothingAlpha ?? 0.25,
+      minCycleGapSeconds: options?.minCycleGapSeconds ?? 2.5,
+      minPhaseSeconds: options?.minPhaseSeconds ?? 1.5,
+      thresholdFactor: options?.thresholdFactor ?? 0.35,
+      freqLow: options?.freqLow ?? 150,
+      freqHigh: options?.freqHigh ?? 2500,
+      enableCentroid: options?.enableCentroid ?? true,
+      centroidThreshold: options?.centroidThreshold ?? 40,
+    };
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────
+
+  /** Start microphone capture and breath detection */
+  async start() {
+    try {
+      this.micStream = await navigator.mediaDevices.getUserMedia({
+        audio: { echoCancellation: false, noiseSuppression: false, autoGainControl: true }
+      });
+      this.audioCtx = new (window.AudioContext || (window).webkitAudioContext)();
+      this.source = this.audioCtx.createMediaStreamSource(this.micStream);
+      this.analyser = this.audioCtx.createAnalyser();
+      this.analyser.fftSize = this.opts.fftSize;
+      this.analyser.smoothingTimeConstant = 0.4;
+      this.source.connect(this.analyser);
+      this.freqData = new Uint8Array(this.analyser.frequencyBinCount);
+      this.timeData = new Uint8Array(this.analyser.fftSize);
+      this.running = true;
+      this.state = 'idle';
+      this.stateStart = Date.now();
+      return true;
+    } catch (e) {
+      console.error('[BreathDetector] Mic error:', e);
+      return false;
+    }
+  }
+
+  /** Stop capture and release resources */
+  stop() {
+    this.running = false;
+    if (this.tickInterval) { clearInterval(this.tickInterval); this.tickInterval = null; }
+    if (this.source) { try { this.source.disconnect(); } catch (_) {} }
+    if (this.micStream) { this.micStream.getTracks().forEach(t => t.stop()); }
+    if (this.audioCtx) { this.audioCtx.close().catch(() => {}); }
+    this.audioCtx = null;
+    this.analyser = null;
+    this.source = null;
+    this.micStream = null;
+    this.calibrated = false;
+    this.smoothedEnergy = 0;
+  }
+
+  /** Calibrate: 2s noise floor + 4s breath samples. Returns when done. */
+  async calibrate() {
+    if (!this.analyser) return { noiseFloor: 0, breathMax: 0, success: false };
+
+    // Phase 1: Noise floor (2s)
+    const noiseSamples = [];
+    await this.sampleFor(2000, () => {
+      this.computeEnergy();
+      noiseSamples.push(this.smoothedEnergy);
+    });
+    this.noiseFloor = noiseSamples.reduce((a, b) => a + b, 0) / noiseSamples.length;
+
+    // Phase 2: Breath samples (4s)
+    const breathSamples = [];
+    await this.sampleFor(4000, () => {
+      this.computeEnergy();
+      breathSamples.push(this.smoothedEnergy);
+    });
+    breathSamples.sort((a, b) => b - a);
+    const top15 = breathSamples.slice(0, Math.max(5, Math.floor(breathSamples.length * 0.15)));
+    this.breathMax = top15.reduce((a, b) => a + b, 0) / top15.length;
+
+    if (this.breathMax - this.noiseFloor < 0.005) {
+      this.breathMax = Math.max(this.noiseFloor * 2.0, this.noiseFloor + 0.02);
+    }
+
+    this.calibrated = true;
+    const result = {
+      noiseFloor: this.noiseFloor,
+      breathMax: this.breathMax,
+      success: true,
+    };
+    this.onCalibrationCallbacks.forEach(cb => cb(result));
+    return result;
+  }
+
+  /** Start the detection loop (call after calibrate) */
+  startDetection() {
+    if (!this.calibrated || !this.running) return;
+    this.resetState();
+    if (this.tickInterval) clearInterval(this.tickInterval);
+    this.tickInterval = setInterval(() => this.tick(), 33); // ~30fps
+  }
+
+  /** Stop detection loop (keeps mic open) */
+  stopDetection() {
+    if (this.tickInterval) { clearInterval(this.tickInterval); this.tickInterval = null; }
+  }
+
+  /** Feed external heart rate for enhanced detection (optional) */
+  setHeartRate(bpm) {
+    this.externalHR = bpm;
+  }
+
+  /** Get current state */
+  getState() {
+    return {
+      running: this.running,
+      calibrated: this.calibrated,
+      phase: this.state,
+      energy: this.getNormalizedEnergy(),
+      centroid: this.smoothedCentroid,
+      noiseFloor: this.noiseFloor,
+      breathMax: this.breathMax,
+    };
+  }
+
+  // ── Event Registration ──────────────────────────────────────────────────
+
+  /** Called when a full breath cycle is detected */
+  onCycle(callback) { this.onCycleCallbacks.push(callback); }
+
+  /** Called on every tick with current phase info */
+  onPhase(callback) { this.onPhaseCallbacks.push(callback); }
+
+  /** Called when calibration completes */
+  onCalibration(callback) { this.onCalibrationCallbacks.push(callback); }
+
+  /** Called on every tick with raw energy + centroid */
+  onEnergy(callback) { this.onEnergyCallbacks.push(callback); }
+
+  // ── Private ─────────────────────────────────────────────────────────────
+
+  resetState() {
+    this.state = 'idle';
+    this.stateStart = Date.now();
+    this.aboveStart = 0;
+    this.belowStart = 0;
+    this.peakEnergy = 0;
+    this.cycleData = {};
+    this.recentCycleDurations = [];
+    this.lastCycleEndTime = 0;
+    this.centroidSumA1 = 0; this.centroidCountA1 = 0;
+    this.centroidSumA2 = 0; this.centroidCountA2 = 0;
+    this.prevEnergy = 0;
+    this.energyRising = false;
+    this.energyFallingStart = 0;
+    this.energyPeakVal = 0;
+    this.peakCount = 0;
+    this.lastPeakTime = 0;
+    this.peakCycleStart = 0;
+    this.recentEnergySamples = [];
+    this.lastRecalTime = 0;
+  }
+
+  computeEnergy() {
+    if (!this.analyser || !this.freqData || !this.timeData) return 0;
+    this.analyser.getByteFrequencyData(this.freqData);
+    this.analyser.getByteTimeDomainData(this.timeData);
+
+    const nyquist = this.audioCtx.sampleRate / 2;
+    const binSize = nyquist / this.analyser.frequencyBinCount;
+    const lowBin = Math.floor(this.opts.freqLow / binSize);
+    const highBin = Math.min(Math.ceil(this.opts.freqHigh / binSize), this.analyser.frequencyBinCount - 1);
+
+    let freqSum = 0;
+    let centroidNum = 0, centroidDen = 0;
+    for (let i = lowBin; i <= highBin; i++) {
+      const mag = this.freqData[i];
+      freqSum += mag;
+      const freq = i * binSize;
+      centroidNum += freq * mag;
+      centroidDen += mag;
+    }
+    const freqEnergy = freqSum / ((highBin - lowBin + 1) * 255);
+
+    if (this.opts.enableCentroid) {
+      const rawCentroid = centroidDen > 0 ? centroidNum / centroidDen : 500;
+      this.smoothedCentroid = 0.2 * rawCentroid + 0.8 * this.smoothedCentroid;
+    }
+
+    let rmsSum = 0;
+    for (let j = 0; j < this.timeData.length; j++) {
+      const v = (this.timeData[j] - 128) / 128;
+      rmsSum += v * v;
+    }
+    const rmsVal = Math.sqrt(rmsSum / this.timeData.length);
+
+    const combined = freqEnergy * 0.7 + rmsVal * 0.3;
+    this.smoothedEnergy = this.smoothedEnergy * (1 - this.opts.smoothingAlpha) + combined * this.opts.smoothingAlpha;
+
+    // Auto-recalibration
+    if (this.calibrated) {
+      this.recentEnergySamples.push(this.smoothedEnergy);
+      if (this.recentEnergySamples.length > 300) this.recentEnergySamples.shift();
+      const now = Date.now();
+      if (now - this.lastRecalTime > 10000 && this.recentEnergySamples.length >= 300) {
+        this.lastRecalTime = now;
+        const sorted = [...this.recentEnergySamples].sort((a, b) => a - b);
+        const newFloor = sorted[Math.floor(sorted.length * 0.15)];
+        const newMax = sorted[Math.floor(sorted.length * 0.90)];
+        if (newFloor > 0 && newMax > newFloor * 1.3) {
+          this.noiseFloor = this.noiseFloor * 0.7 + newFloor * 0.3;
+          this.breathMax = this.breathMax * 0.7 + newMax * 0.3;
+        }
+      }
+    }
+
+    return this.smoothedEnergy;
+  }
+
+  getThreshold() {
+    if (!this.calibrated) return 0.05;
+    const range = this.breathMax - this.noiseFloor;
+    if (range < 0.003) return 0.008;
+    return Math.max(this.noiseFloor + range * Math.max(this.opts.thresholdFactor, 0.06), 0.008);
+  }
+
+  getThresholdLow() {
+    if (!this.calibrated) return 0.02;
+    const range = this.breathMax - this.noiseFloor;
+    if (range < 0.003) return 0.004;
+    return this.noiseFloor + range * 0.20;
+  }
+
+  getNormalizedEnergy() {
+    if (!this.calibrated) return 0;
+    const range = this.breathMax - this.noiseFloor;
+    if (range < 0.001) return 0;
+    return Math.max(0, Math.min(1, (this.smoothedEnergy - this.noiseFloor) / range));
+  }
+
+  tick() {
+    if (!this.running || !this.calibrated) return;
+    const now = Date.now();
+    const energy = this.computeEnergy();
+    const th = this.getThreshold();
+    const thLow = this.getThresholdLow();
+    let aboveTh = this.smoothedEnergy > th;
+    let belowThLow = this.smoothedEnergy < thLow;
+
+    // Energy trend detection
+    const energyDelta = energy - this.prevEnergy;
+    const wasRising = this.energyRising;
+    if (energyDelta > 0) {
+      this.energyRising = true;
+      if (energy > this.energyPeakVal) this.energyPeakVal = energy;
+      this.energyFallingStart = 0;
+    } else if (energyDelta < 0) {
+      if (this.energyRising && !this.energyFallingStart) this.energyFallingStart = now;
+      this.energyRising = false;
+    }
+
+    const significantDrop = this.energyPeakVal > 0 && energy < this.energyPeakVal * 0.6;
+    const fallingLongEnough = this.energyFallingStart > 0 && (now - this.energyFallingStart) > 500;
+    const minStateMs = this.opts.minPhaseSeconds * 1000;
+
+    if (significantDrop && fallingLongEnough) {
+      if ((this.state === 'active1' || this.state === 'active2') && (now - this.stateStart) > minStateMs) {
+        belowThLow = true;
+        this.energyPeakVal = 0;
+        this.energyFallingStart = 0;
+      }
+    }
+    if (!wasRising && this.energyRising && energy > this.noiseFloor * 1.2) {
+      if (this.state === 'silent1' || this.state === 'silent2') aboveTh = true;
+    }
+
+    // Peak-based cycle detection (pauseless breathing fallback)
+    if (wasRising && !this.energyRising && this.energyPeakVal > this.noiseFloor * 1.3) {
+      const timeSinceLastPeak = this.lastPeakTime > 0 ? (now - this.lastPeakTime) : 99999;
+      if (timeSinceLastPeak > 1500) {
+        this.peakCount++;
+        if (this.peakCount === 1) this.peakCycleStart = now;
+        this.lastPeakTime = now;
+        if (this.peakCount >= 2 && this.peakCycleStart > 0) {
+          const peakCycleMs = now - this.peakCycleStart;
+          if (this.state === 'active1' && peakCycleMs > this.opts.minCycleGapSeconds * 1000) {
+            const halfCycle = Math.round(peakCycleMs / 2);
+            this.cycleData = {
+              active1Start: this.peakCycleStart, active1End: this.peakCycleStart + halfCycle,
+              silent1Start: this.peakCycleStart + halfCycle, silent1End: this.peakCycleStart + halfCycle,
+              active2Start: this.peakCycleStart + halfCycle, active2End: now, silent2Start: now,
+            };
+            this.completeCycle(now, 'peak');
+            this.peakCount = 1;
+            this.peakCycleStart = now;
+          } else if (this.state !== 'active1') {
+            this.peakCount = 0;
+            this.peakCycleStart = 0;
+          }
+        }
+      }
+    }
+
+    this.prevEnergy = energy;
+
+    // Centroid tracking
+    if (this.state === 'active1') { this.centroidSumA1 += this.smoothedCentroid; this.centroidCountA1++; }
+    else if (this.state === 'active2') { this.centroidSumA2 += this.smoothedCentroid; this.centroidCountA2++; }
+    if (this.state === 'active1' || this.state === 'active2') {
+      if (energy > this.peakEnergy) this.peakEnergy = energy;
+    }
+
+    // State machine
+    const ACTIVE_MS = 250;
+    const SILENT_MS = 500;
+
+    if (this.state === 'idle') {
+      if (aboveTh) {
+        if (!this.aboveStart) this.aboveStart = now;
+        if (now - this.aboveStart >= ACTIVE_MS) {
+          this.resetCycleData();
+          this.cycleData.active1Start = this.aboveStart;
+          this.aboveStart = 0; this.belowStart = 0;
+          this.changeState('active1', now);
+        }
+      } else { this.aboveStart = 0; }
+    } else if (this.state === 'active1') {
+      if (!belowThLow) { this.belowStart = 0; }
+      else {
+        if (!this.belowStart) this.belowStart = now;
+        if (now - this.belowStart >= SILENT_MS) {
+          this.cycleData.active1End = this.belowStart;
+          this.cycleData.silent1Start = this.belowStart;
+          this.belowStart = 0; this.aboveStart = 0;
+          this.changeState('silent1', now);
+        }
+      }
+    } else if (this.state === 'silent1') {
+      if (!aboveTh) { this.aboveStart = 0; }
+      else {
+        if (!this.aboveStart) this.aboveStart = now;
+        if (now - this.aboveStart >= ACTIVE_MS) {
+          this.cycleData.silent1End = this.aboveStart;
+          this.cycleData.active2Start = this.aboveStart;
+          this.aboveStart = 0; this.belowStart = 0;
+          this.changeState('active2', now);
+        }
+      }
+    } else if (this.state === 'active2') {
+      if (!belowThLow) { this.belowStart = 0; }
+      else {
+        if (!this.belowStart) this.belowStart = now;
+        if (now - this.belowStart >= SILENT_MS) {
+          this.cycleData.active2End = this.belowStart;
+          this.cycleData.silent2Start = this.belowStart;
+          this.belowStart = 0; this.aboveStart = 0;
+          this.changeState('silent2', now);
+          this.completeCycle(now, 'threshold');
+        }
+      }
+    } else if (this.state === 'silent2') {
+      if (!aboveTh) { this.aboveStart = 0; }
+      else {
+        if (!this.aboveStart) this.aboveStart = now;
+        if (now - this.aboveStart >= ACTIVE_MS) {
+          this.resetCycleData();
+          this.cycleData.active1Start = this.aboveStart;
+          this.aboveStart = 0; this.belowStart = 0;
+          this.changeState('active1', now);
+        }
+      }
+    }
+
+    // Emit phase event
+    const norm = this.getNormalizedEnergy();
+    const phaseMap: Record<string, BreathPhaseEvent['phase']> = {
+      idle: 'idle', active1: 'inhale', silent1: 'transition', active2: 'exhale', silent2: 'pause'
+    };
+    this.onPhaseCallbacks.forEach(cb => cb({
+      phase: phaseMap[this.state] || 'idle',
+      energy: norm,
+      centroid: this.smoothedCentroid,
+      phaseTime: now - this.stateStart,
+    }));
+    this.onEnergyCallbacks.forEach(cb => cb(norm, this.smoothedCentroid));
+  }
+
+  changeState(newState, now) {
+    this.state = newState;
+    this.stateStart = now;
+  }
+
+  resetCycleData() {
+    this.cycleData = {};
+    this.peakEnergy = 0;
+    this.centroidSumA1 = 0; this.centroidCountA1 = 0;
+    this.centroidSumA2 = 0; this.centroidCountA2 = 0;
+    this.peakCount = 0;
+    this.peakCycleStart = 0;
+  }
+
+  completeCycle(now, method: 'threshold' | 'peak') {
+    const minGapMs = this.opts.minCycleGapSeconds * 1000;
+    if (this.lastCycleEndTime > 0 && (now - this.lastCycleEndTime) < minGapMs) return;
+
+    const d = this.cycleData;
+    const active1Ms = (d.active1End || 0) - (d.active1Start || 0);
+    const silent1Ms = (d.silent1End || 0) - (d.silent1Start || 0);
+    const active2Ms = (d.active2End || 0) - (d.active2Start || 0);
+    const cycleMs = (d.active2End || now) - (d.active1Start || now);
+
+    if (cycleMs < minGapMs) return;
+
+    let inhaleMs = active1Ms;
+    let exhaleMs = active2Ms;
+    let labelSwapped = false;
+
+    // Spectral centroid classification
+    if (this.opts.enableCentroid) {
+      const c1 = this.centroidCountA1 > 0 ? this.centroidSumA1 / this.centroidCountA1 : 0;
+      const c2 = this.centroidCountA2 > 0 ? this.centroidSumA2 / this.centroidCountA2 : 0;
+      if (c1 > 0 && c2 > 0 && (c1 - c2) < -this.opts.centroidThreshold) {
+        inhaleMs = active2Ms;
+        exhaleMs = active1Ms;
+        labelSwapped = true;
+      }
+    }
+
+    // Duration fallback
+    if (!labelSwapped && active1Ms > active2Ms * 3 && active2Ms < 1000) {
+      const total = active1Ms + silent1Ms + active2Ms;
+      inhaleMs = Math.round(total * 0.5);
+      exhaleMs = Math.round(total * 0.5);
+    }
+
+    const holdInMs = silent1Ms > 1500 ? silent1Ms : 0;
+
+    let confidence = 100;
+    if (active1Ms < 500) confidence -= 20;
+    if (active2Ms < 500) confidence -= 20;
+    if (method === 'peak') confidence -= 10;
+    confidence = Math.max(0, Math.min(100, confidence));
+
+    this.lastCycleEndTime = now;
+    this.recentCycleDurations.push(cycleMs);
+    if (this.recentCycleDurations.length > 8) this.recentCycleDurations.shift();
+
+    const cycle = {
+      inhaleMs, exhaleMs, holdInMs, holdOutMs: 0,
+      cycleMs, peakEnergy: this.peakEnergy,
+      confidence, labelSwapped,
+      centroidA1: Math.round(this.centroidCountA1 > 0 ? this.centroidSumA1 / this.centroidCountA1 : 0),
+      centroidA2: Math.round(this.centroidCountA2 > 0 ? this.centroidSumA2 / this.centroidCountA2 : 0),
+      method, timestamp: now,
+    };
+
+    this.onCycleCallbacks.forEach(cb => cb(cycle));
+  }
+
+  sampleFor(ms, fn: () => void) {
+    return new Promise(resolve => {
+      const start = Date.now();
+      const iv = setInterval(() => {
+        fn();
+        if (Date.now() - start >= ms) { clearInterval(iv); resolve(); }
+      }, 33);
+    });
+  }
+}
+
+// Default export
+export default BreathDetector;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@shiihaa/breath-detection",
+  "version": "1.0.0",
+  "description": "Real-time breath detection using microphone energy analysis, spectral centroid classification, and BLE heart rate data. Works in browsers and Capacitor apps.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "node build.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "breath-detection",
+    "breathing",
+    "breathwork",
+    "biofeedback",
+    "audio-analysis",
+    "web-audio",
+    "capacitor",
+    "microphone",
+    "spectral-centroid",
+    "respiratory",
+    "HRV",
+    "BLE"
+  ],
+  "author": "Felix Zeller <felix@shiihaa.app>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shiihaa-app/breath-detection"
+  },
+  "homepage": "https://github.com/shiihaa-app/breath-detection#readme",
+  "bugs": {
+    "url": "https://github.com/shiihaa-app/breath-detection/issues"
+  }
+}