@edkimmel/expo-audio-stream 0.3.0 → 0.3.2-beta.0

package/android/src/main/java/expo/modules/audiostream/AudioEffectsManager.kt

@@ -7,12 +7,27 @@ import android.media.audiofx.NoiseSuppressor
 import android.util.Log
 
 /**
- * Manages audio effects for voice recording, including:
- * - Acoustic Echo Cancellation (AEC)
- * - Noise Suppression (NS)
- * - Automatic Gain Control (AGC)
+ * Manages hardware audio effects for voice recording.
+ *
+ * We use VOICE_RECOGNITION as our audio source. The Android CDD (Section 5.4)
+ * mandates that this source delivers unprocessed audio:
+ *   [C-1-2] MUST disable noise reduction by default
+ *   [C-1-3] MUST disable automatic gain control by default
+ *
+ * NS and AGC are therefore off by default to honor the spec. Enabling them
+ * re-introduces the processing the CDD explicitly prohibits for this source
+ * and can cause low-volume capture on many OEMs.
+ *
+ * AEC is the one effect the CDD permits for VOICE_RECOGNITION ("expects a
+ * stream that has an echo cancellation effect if available"), so it is
+ * enabled by default.
  */
-class AudioEffectsManager {
+class AudioEffectsManager(
+    /** Enable hardware noise suppressor. Default false — CDD 5.4 [C-1-2] prohibits it for VOICE_RECOGNITION. */
+    private val enableNS: Boolean = false,
+    /** Enable hardware AGC. Default false — CDD 5.4 [C-1-3] prohibits it for VOICE_RECOGNITION. */
+    private val enableAGC: Boolean = false
+) {
     // Audio effects
     private var acousticEchoCanceler: AcousticEchoCanceler? = null
     private var noiseSuppressor: NoiseSuppressor? = null
@@ -41,11 +56,21 @@ class AudioEffectsManager {
                 Log.d(Constants.TAG, "Acoustic Echo Canceler enabled: ${acousticEchoCanceler?.enabled}")
             }
             
-            // Apply noise suppression
-            enableNoiseSuppression(audioSessionId)
-            
-            // Apply automatic gain control
-            enableAutomaticGainControl(audioSessionId)
+            // NS off by default — CDD 5.4 [C-1-2] prohibits it for VOICE_RECOGNITION.
+            // Enabling it can aggressively attenuate speech on many OEMs.
+            if (enableNS) {
+                enableNoiseSuppression(audioSessionId)
+            } else {
+                Log.d(Constants.TAG, "Noise Suppressor skipped (CDD 5.4 [C-1-2])")
+            }
+
+            // AGC off by default — CDD 5.4 [C-1-3] prohibits it for VOICE_RECOGNITION.
+            // Hardware AGC is also unreliable across devices.
+            if (enableAGC) {
+                enableAutomaticGainControl(audioSessionId)
+            } else {
+                Log.d(Constants.TAG, "Hardware AGC skipped (CDD 5.4 [C-1-3])")
+            }
             
         } catch (e: Exception) {
             Log.e(Constants.TAG, "Error setting up audio effects", e)

package/ios/SharedAudioEngine.swift

@@ -170,8 +170,14 @@ class SharedAudioEngine {
 
         node.pause()
         node.stop()
-        engine.disconnectNodeOutput(node)
-        engine.detach(node)
+
+        // Only disconnect/detach if the node is still attached to this engine.
+        // The node may already have been removed (e.g. engine died, concurrent
+        // teardown, or duplicate disconnect call).
+        if node.engine === engine {
+            engine.disconnectNodeOutput(node)
+            engine.detach(node)
+        }
         attachedNodes.removeAll { $0.node === node }
 
         Logger.debug("[\(SharedAudioEngine.TAG)] Node detached")
@@ -194,8 +200,12 @@ class SharedAudioEngine {
             for info in attachedNodes {
                 info.node.pause()
                 info.node.stop()
-                engine.disconnectNodeOutput(info.node)
-                engine.detach(info.node)
+                // Guard against nodes already removed from engine (e.g. engine
+                // died or node was detached by a concurrent disconnect call).
+                if info.node.engine === engine {
+                    engine.disconnectNodeOutput(info.node)
+                    engine.detach(info.node)
+                }
             }
         }
         attachedNodes.removeAll()
@@ -265,8 +275,10 @@ class SharedAudioEngine {
 
             // 3. Detach all nodes
             for info in attachedNodes {
-                engine.disconnectNodeOutput(info.node)
-                engine.detach(info.node)
+                if info.node.engine === engine {
+                    engine.disconnectNodeOutput(info.node)
+                    engine.detach(info.node)
+                }
             }
             Logger.debug("[\(SharedAudioEngine.TAG)] Nodes detached (\(attachedNodes.count))")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edkimmel/expo-audio-stream",
-  "version": "0.3.0",
+  "version": "0.3.2-beta.0",
   "description": "Expo Play Audio Stream module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -45,5 +45,6 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
-  }
+  },
+  "stableVersion": "0.3.1"
 }

package/docs/superpowers/plans/2026-03-13-frequency-band-analysis.md

@@ -1,1006 +0,0 @@
-# Frequency Band Analysis Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add real-time low/mid/high frequency band analysis to microphone capture and pipeline playback, computed natively using parallel single-pole IIR low-pass filters.
-
-**Architecture:** A shared `FrequencyBandAnalyzer` DSP class on each platform (Swift/Kotlin) runs inline in the audio processing loops. For the microphone path, bands are harvested per-callback and added to the existing `AudioData` event. For the pipeline path, bands are accumulated in the write/schedule loop and harvested by a separate timer that emits a new `PipelineFrequencyBands` event at a configurable interval.
-
-**Tech Stack:** Swift (iOS), Kotlin (Android), TypeScript (API types + event wiring)
-
-**Spec:** `docs/superpowers/specs/2026-03-13-frequency-band-analysis-design.md`
-
----
-
-## Chunk 1: FrequencyBandAnalyzer + TypeScript Types
-
-### Task 1: Create iOS FrequencyBandAnalyzer
-
-**Files:**
-- Create: `ios/FrequencyBandAnalyzer.swift`
-
-- [ ] **Step 1: Create the FrequencyBandAnalyzer class**
-
-```swift
-import Foundation
-
-/// Lightweight IIR-based frequency band analyzer.
-///
-/// Uses two parallel single-pole low-pass filters to split audio into
-/// low / mid / high bands and accumulate RMS energy.
-/// Thread-safe: `processSamples` and `harvest` may be called from
-/// different threads (guarded by an internal lock).
-struct FrequencyBands {
-    let low: Float
-    let mid: Float
-    let high: Float
-
-    static let zero = FrequencyBands(low: 0, mid: 0, high: 0)
-}
-
-class FrequencyBandAnalyzer {
-    // ── Coefficients (immutable after init) ──────────────────────────
-    private let alphaLow: Float
-    private let alphaHigh: Float
-
-    // ── Filter state ─────────────────────────────────────────────────
-    private var lp1: Float = 0       // low-pass accumulator (low crossover)
-    private var lp2: Float = 0       // low-pass accumulator (high crossover)
-
-    // ── Energy accumulators ──────────────────────────────────────────
-    private var lowE: Float = 0
-    private var midE: Float = 0
-    private var highE: Float = 0
-    private var count: Int = 0
-
-    // ── Synchronization ──────────────────────────────────────────────
-    private let lock = NSLock()
-
-    init(sampleRate: Int, lowCrossoverHz: Float = 300, highCrossoverHz: Float = 2000) {
-        let sr = Float(sampleRate)
-        self.alphaLow = min(1, (2 * Float.pi * lowCrossoverHz) / sr)
-        self.alphaHigh = min(1, (2 * Float.pi * highCrossoverHz) / sr)
-    }
-
-    /// Process a batch of PCM16 samples. Accumulates energy — does NOT
-    /// produce output. Call `harvest()` to read and reset.
-    func processSamples(_ samples: UnsafePointer<Int16>, count sampleCount: Int) {
-        lock.lock()
-        defer { lock.unlock() }
-
-        for i in 0..<sampleCount {
-            let s = Float(samples[i]) / 32768.0
-
-            lp1 += alphaLow * (s - lp1)
-            lp2 += alphaHigh * (s - lp2)
-
-            let low = lp1
-            let high = s - lp2
-            let mid = s - low - high
-
-            lowE += low * low
-            midE += mid * mid
-            highE += high * high
-            count += 1
-        }
-    }
-
-    /// Process PCM16 samples from a Data blob (little-endian Int16).
-    func processSamplesFromData(_ data: Data) {
-        data.withUnsafeBytes { rawBuffer in
-            guard let ptr = rawBuffer.baseAddress?.assumingMemoryBound(to: Int16.self) else { return }
-            let sampleCount = data.count / 2
-            processSamples(ptr, count: sampleCount)
-        }
-    }
-
-    /// Read accumulated RMS energy and reset accumulators.
-    func harvest() -> FrequencyBands {
-        lock.lock()
-        defer { lock.unlock() }
-
-        guard count > 0 else { return .zero }
-
-        let n = Float(count)
-        let result = FrequencyBands(
-            low: sqrt(lowE / n),
-            mid: sqrt(midE / n),
-            high: sqrt(highE / n)
-        )
-
-        lowE = 0
-        midE = 0
-        highE = 0
-        count = 0
-
-        return result
-    }
-
-    /// Zero all state (filter accumulators + energy).
-    func reset() {
-        lock.lock()
-        defer { lock.unlock() }
-
-        lp1 = 0
-        lp2 = 0
-        lowE = 0
-        midE = 0
-        highE = 0
-        count = 0
-    }
-}
-```
-
-- [ ] **Step 2: Commit**
-
-```bash
-git add ios/FrequencyBandAnalyzer.swift
-git commit -m "feat: add iOS FrequencyBandAnalyzer DSP component"
-```
-
----
-
-### Task 2: Create Android FrequencyBandAnalyzer
-
-**Files:**
-- Create: `android/src/main/java/expo/modules/audiostream/FrequencyBandAnalyzer.kt`
-
-- [ ] **Step 1: Create the FrequencyBandAnalyzer class**
-
-```kotlin
-package expo.modules.audiostream
-
-import java.util.concurrent.locks.ReentrantLock
-import kotlin.concurrent.withLock
-import kotlin.math.PI
-import kotlin.math.min
-import kotlin.math.sqrt
-
-/**
- * RMS energy per frequency band, range [0, 1].
- */
-data class FrequencyBands(
-    val low: Float,
-    val mid: Float,
-    val high: Float
-) {
-    companion object {
-        val ZERO = FrequencyBands(0f, 0f, 0f)
-    }
-}
-
-/**
- * Lightweight IIR-based frequency band analyzer.
- *
- * Uses two parallel single-pole low-pass filters to split audio into
- * low / mid / high bands and accumulate RMS energy.
- * Thread-safe: [processSamples] and [harvest] may be called from
- * different threads (guarded by an internal lock).
- */
-class FrequencyBandAnalyzer(
-    sampleRate: Int,
-    lowCrossoverHz: Float = 300f,
-    highCrossoverHz: Float = 2000f
-) {
-    // ── Coefficients (immutable after init) ──────────────────────────
-    private val alphaLow: Float = min(1f, (2f * PI.toFloat() * lowCrossoverHz) / sampleRate)
-    private val alphaHigh: Float = min(1f, (2f * PI.toFloat() * highCrossoverHz) / sampleRate)
-
-    // ── Filter state ─────────────────────────────────────────────────
-    private var lp1: Float = 0f
-    private var lp2: Float = 0f
-
-    // ── Energy accumulators ──────────────────────────────────────────
-    private var lowE: Float = 0f
-    private var midE: Float = 0f
-    private var highE: Float = 0f
-    private var count: Int = 0
-
-    // ── Synchronization ──────────────────────────────────────────────
-    private val lock = ReentrantLock()
-
-    /**
-     * Process a batch of PCM16 samples. Accumulates energy — does NOT
-     * produce output. Call [harvest] to read and reset.
-     */
-    fun processSamples(samples: ShortArray, length: Int = samples.size) {
-        lock.withLock {
-            for (i in 0 until length) {
-                val s = samples[i].toFloat() / 32768f
-
-                lp1 += alphaLow * (s - lp1)
-                lp2 += alphaHigh * (s - lp2)
-
-                val low = lp1
-                val high = s - lp2
-                val mid = s - low - high
-
-                lowE += low * low
-                midE += mid * mid
-                highE += high * high
-                count++
-            }
-        }
-    }
-
-    /**
-     * Process PCM16 samples from a ByteArray (little-endian Int16).
-     */
-    fun processSamplesFromBytes(data: ByteArray, length: Int = data.size) {
-        val sampleCount = length / 2
-        val samples = ShortArray(sampleCount)
-        val buf = java.nio.ByteBuffer.wrap(data, 0, length)
-            .order(java.nio.ByteOrder.LITTLE_ENDIAN)
-            .asShortBuffer()
-        buf.get(samples)
-        processSamples(samples, sampleCount)
-    }
-
-    /**
-     * Read accumulated RMS energy and reset accumulators.
-     */
-    fun harvest(): FrequencyBands {
-        lock.withLock {
-            if (count == 0) return FrequencyBands.ZERO
-
-            val n = count.toFloat()
-            val result = FrequencyBands(
-                low = sqrt(lowE / n),
-                mid = sqrt(midE / n),
-                high = sqrt(highE / n)
-            )
-
-            lowE = 0f
-            midE = 0f
-            highE = 0f
-            count = 0
-
-            return result
-        }
-    }
-
-    /**
-     * Zero all state (filter accumulators + energy).
-     */
-    fun reset() {
-        lock.withLock {
-            lp1 = 0f
-            lp2 = 0f
-            lowE = 0f
-            midE = 0f
-            highE = 0f
-            count = 0
-        }
-    }
-}
-```
-
-- [ ] **Step 2: Commit**
-
-```bash
-git add android/src/main/java/expo/modules/audiostream/FrequencyBandAnalyzer.kt
-git commit -m "feat: add Android FrequencyBandAnalyzer DSP component"
-```
-
----
-
-### Task 3: Add TypeScript Types
-
-**Files:**
-- Modify: `src/types.ts` (add FrequencyBands, FrequencyBandConfig; extend AudioDataEvent, RecordingConfig)
-- Modify: `src/pipeline/types.ts` (add PipelineFrequencyBandsEvent; extend ConnectPipelineOptions, PipelineEventMap)
-
-- [ ] **Step 1: Add new types to `src/types.ts`**
-
-Add after the `Encoding` type definition (after line 88):
-
-```typescript
-/** RMS energy per frequency band, range [0, 1]. */
-export interface FrequencyBands {
-  low: number;
-  mid: number;
-  high: number;
-}
-
-/** Crossover frequency configuration for band analysis. */
-export interface FrequencyBandConfig {
-  /** Low/mid crossover in Hz (default 300). */
-  lowCrossoverHz?: number;
-  /** Mid/high crossover in Hz (default 2000). */
-  highCrossoverHz?: number;
-}
-```
-
-- [ ] **Step 2: Extend AudioDataEvent**
-
-In `src/types.ts`, add to the `AudioDataEvent` interface (after the `soundLevel` field at line 137):
-
-```typescript
-  /** Frequency band RMS energy, present when recording is active. */
-  frequencyBands?: FrequencyBands;
-```
-
-- [ ] **Step 3: Extend RecordingConfig**
-
-In `src/types.ts`, add to the `RecordingConfig` interface (after the `onAudioStream` field at line 149):
-
-```typescript
-  /** Optional frequency band crossover configuration. */
-  frequencyBandConfig?: FrequencyBandConfig;
-```
-
-- [ ] **Step 4: Extend pipeline types in `src/pipeline/types.ts`**
-
-Add to `ConnectPipelineOptions` (after the `playbackMode` field, around line 23):
-
-```typescript
-  /** Interval in ms for PipelineFrequencyBands events (default 100). */
-  frequencyBandIntervalMs?: number;
-  /** Optional frequency band crossover configuration. */
-  frequencyBandConfig?: FrequencyBandConfig;
-```
-
-Also add the import at the top of the file (line 6, extend existing import):
-
-```typescript
-import { PlaybackMode, FrequencyBandConfig, FrequencyBands } from "../types";
-```
-
-Add new event type (after `PipelineAudioFocusResumedEvent`, around line 117):
-
-```typescript
-/** Payload for `PipelineFrequencyBands`. */
-export interface PipelineFrequencyBandsEvent extends FrequencyBands {}
-```
-
-Add to `PipelineEventMap` (before the closing brace, around line 131):
-
-```typescript
-  PipelineFrequencyBands: PipelineFrequencyBandsEvent;
-```
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/types.ts src/pipeline/types.ts
-git commit -m "feat: add FrequencyBands TypeScript types and extend events"
-```
-
----
-
-## Chunk 2: Pipeline Integration (iOS + Android)
-
-### Task 4: Add onFrequencyBands to PipelineListener and wire iOS pipeline
-
-**Files:**
-- Modify: `ios/AudioPipeline.swift` — add `onFrequencyBands` to protocol (line 13-21), add analyzer + harvest timer to class
-- Modify: `ios/PipelineIntegration.swift` — add event constant, implement new listener method, parse new config in connect()
-
-- [ ] **Step 1: Add onFrequencyBands to PipelineListener protocol**
-
-In `ios/AudioPipeline.swift`, add to the `PipelineListener` protocol (after `onAudioFocusResumed()` at line 21):
-
-```swift
-    func onFrequencyBands(low: Float, mid: Float, high: Float)
-```
-
-- [ ] **Step 2: Add analyzer and config to AudioPipeline**
-
-In `ios/AudioPipeline.swift`, add new config fields after `targetBufferMs` (line 58):
-
-```swift
-    private let frequencyBandIntervalMs: Int
-    private let lowCrossoverHz: Float
-    private let highCrossoverHz: Float
-```
-
-Add analyzer and timer fields after `zombieTimer` (line 85):
-
-```swift
-    private var frequencyBandTimer: DispatchSourceTimer?
-    private var frequencyBandAnalyzer: FrequencyBandAnalyzer?
-```
-
-Update `init` (line 99) to accept the new parameters:
-
-```swift
-    init(sampleRate: Int, channelCount: Int, targetBufferMs: Int,
-         frequencyBandIntervalMs: Int = 100,
-         lowCrossoverHz: Float = 300, highCrossoverHz: Float = 2000,
-         sharedEngine: SharedAudioEngine, listener: PipelineListener) {
-        self.sampleRate = sampleRate
-        self.channelCount = channelCount
-        self.targetBufferMs = targetBufferMs
-        self.frequencyBandIntervalMs = frequencyBandIntervalMs
-        self.lowCrossoverHz = lowCrossoverHz
-        self.highCrossoverHz = highCrossoverHz
-        self.sharedEngine = sharedEngine
-        self.listener = listener
-        self.frameSizeSamples = max(1, sampleRate * channelCount / 50)
-    }
-```
-
-- [ ] **Step 3: Create analyzer in connect(), destroy in disconnect()**
-
-In `connect()`, after `resetTelemetry()` (line 171), add:
-
-```swift
-            // ── 8. Frequency band analyzer ───────────────────────────────
-            frequencyBandAnalyzer = FrequencyBandAnalyzer(
-                sampleRate: sampleRate,
-                lowCrossoverHz: lowCrossoverHz,
-                highCrossoverHz: highCrossoverHz
-            )
-            startFrequencyBandTimer()
-```
-
-In `disconnect()`, after cancelling `zombieTimer` (line 193-194), add:
-
-```swift
-        frequencyBandTimer?.cancel()
-        frequencyBandTimer = nil
-        frequencyBandAnalyzer = nil
-```
-
-Also add to `engineDidDie` (after `zombieTimer = nil` at line 292):
-
-```swift
-        frequencyBandTimer?.cancel()
-        frequencyBandTimer = nil
-        frequencyBandAnalyzer = nil
-```
-
-- [ ] **Step 4: Call processSamples in scheduleNextBuffer**
-
-In `scheduleNextBuffer()`, after `buf.read(dest: &renderSamples, length: frameSizeSamples)` (line 422) and before the Float32 conversion, add:
-
-```swift
-        // Analyze frequency bands on the raw Int16 samples
-        if !isInterrupted {
-            renderSamples.withUnsafeBufferPointer { bufferPtr in
-                if let baseAddress = bufferPtr.baseAddress {
-                    frequencyBandAnalyzer?.processSamples(baseAddress, count: frameSizeSamples)
-                }
-            }
-        }
-```
-
-- [ ] **Step 5: Reset analyzer on turn boundary**
-
-In `pushAudio()`, inside the turn boundary block (after `setState(.streaming)` at line 338), add:
-
-```swift
-            frequencyBandAnalyzer?.reset()
-```
-
-In `invalidateTurn()`, after `setState(.idle)` (line 379), add:
-
-```swift
-        frequencyBandAnalyzer?.reset()
-```
-
-- [ ] **Step 6: Add frequency band timer method**
-
-Add after `startZombieDetection()` (before the "Internal helpers" section):
-
-```swift
-    // ════════════════════════════════════════════════════════════════════
-    // Frequency band emission
-    // ════════════════════════════════════════════════════════════════════
-
-    private func startFrequencyBandTimer() {
-        let intervalSec = TimeInterval(frequencyBandIntervalMs) / 1000.0
-        let timer = DispatchSource.makeTimerSource(queue: .main)
-        timer.schedule(deadline: .now() + intervalSec, repeating: intervalSec)
-        timer.setEventHandler { [weak self] in
-            guard let self = self, self.running,
-                  let analyzer = self.frequencyBandAnalyzer else { return }
-            let bands = analyzer.harvest()
-            self.listener?.onFrequencyBands(low: bands.low, mid: bands.mid, high: bands.high)
-        }
-        timer.resume()
-        frequencyBandTimer = timer
-    }
-```
-
-- [ ] **Step 7: Wire PipelineIntegration**
-
-In `ios/PipelineIntegration.swift`:
-
-Add event constant after `EVENT_AUDIO_FOCUS_RESUMED` (line 24):
-
-```swift
-    static let EVENT_FREQUENCY_BANDS    = "PipelineFrequencyBands"
-```
-
-Update `connect()` method to parse new options. After the `targetBufferMs` parsing (line 58), add:
-
-```swift
-        let frequencyBandIntervalMs = (options["frequencyBandIntervalMs"] as? NSNumber)?.intValue ?? 100
-        let bandConfig = options["frequencyBandConfig"] as? [String: Any]
-        let lowCrossoverHz = (bandConfig?["lowCrossoverHz"] as? NSNumber)?.floatValue ?? 300
-        let highCrossoverHz = (bandConfig?["highCrossoverHz"] as? NSNumber)?.floatValue ?? 2000
-```
-
-Update the `AudioPipeline` constructor call (line 60-66) to pass the new params:
-
-```swift
-        let p = AudioPipeline(
-            sampleRate: sampleRate,
-            channelCount: channelCount,
-            targetBufferMs: targetBufferMs,
-            frequencyBandIntervalMs: frequencyBandIntervalMs,
-            lowCrossoverHz: lowCrossoverHz,
-            highCrossoverHz: highCrossoverHz,
-            sharedEngine: sharedEngine,
-            listener: self
-        )
-```
-
-Add `onFrequencyBands` implementation (after `onAudioFocusResumed`, around line 207):
-
-```swift
-    func onFrequencyBands(low: Float, mid: Float, high: Float) {
-        sendEvent(PipelineIntegration.EVENT_FREQUENCY_BANDS, [
-            "low": low, "mid": mid, "high": high
-        ])
-    }
-```
-
-- [ ] **Step 8: Register event in ExpoPlayAudioStreamModule.swift**
-
-In `ios/ExpoPlayAudioStreamModule.swift`, add to the Events block (after the last `PipelineIntegration.EVENT_*` entry, around line 66):
-
-```swift
-                PipelineIntegration.EVENT_FREQUENCY_BANDS,
-```
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add ios/AudioPipeline.swift ios/PipelineIntegration.swift ios/ExpoPlayAudioStreamModule.swift
-git commit -m "feat: wire frequency band analysis into iOS pipeline"
-```
-
----
-
-### Task 5: Wire Android pipeline
-
-**Files:**
-- Modify: `android/src/main/java/expo/modules/audiostream/pipeline/AudioPipeline.kt` — add to PipelineListener, add analyzer + harvest timer
-- Modify: `android/src/main/java/expo/modules/audiostream/pipeline/PipelineIntegration.kt` — add event constant, implement listener, parse config
-- Modify: `android/src/main/java/expo/modules/audiostream/ExpoPlayAudioStreamModule.kt` — register event
-
-- [ ] **Step 1: Add onFrequencyBands to PipelineListener interface**
-
-In `android/.../pipeline/AudioPipeline.kt`, add to the `PipelineListener` interface (after `onAudioFocusResumed()` at line 51):
-
-```kotlin
-    fun onFrequencyBands(low: Float, mid: Float, high: Float)
-```
-
-- [ ] **Step 2: Add analyzer config to AudioPipeline constructor and fields**
-
-Update the `AudioPipeline` class constructor (line 82) to accept new params:
-
-```kotlin
-class AudioPipeline(
-    private val context: Context,
-    private val sampleRate: Int,
-    private val channelCount: Int,
-    private val targetBufferMs: Int,
-    private val frequencyBandIntervalMs: Int = 100,
-    private val lowCrossoverHz: Float = 300f,
-    private val highCrossoverHz: Float = 2000f,
-    private val listener: PipelineListener
-)
-```
-
-Add analyzer and timer fields after `lastReportedUnderrunCount` (line 185):
-
-```kotlin
-    // ── Frequency band analysis ──────────────────────────────────────
-    private var frequencyBandAnalyzer: FrequencyBandAnalyzer? = null
-    private var frequencyBandThread: Thread? = null
-```
-
-- [ ] **Step 3: Create analyzer in connect(), destroy in disconnect()**
-
-In `connect()`, after `resetTelemetry()` (line 261), add:
-
-```kotlin
-            // ── 8. Frequency band analyzer ──────────────────────────
-            frequencyBandAnalyzer = FrequencyBandAnalyzer(
-                sampleRate = sampleRate,
-                lowCrossoverHz = lowCrossoverHz,
-                highCrossoverHz = highCrossoverHz
-            )
-            startFrequencyBandTimer()
-```
-
-In `disconnect()`, after `zombieThread = null` (line 285), add:
-
-```kotlin
-        // Stop frequency band timer
-        frequencyBandThread?.interrupt()
-        frequencyBandThread = null
-        frequencyBandAnalyzer = null
-```
-
-- [ ] **Step 4: Call processSamples in writeLoop**
-
-In `writeLoop()`, after `buf.read(frame)` (line 454) and the audio focus silence check, but before `track.write()` (line 463), add:
-
-```kotlin
-            // Analyze frequency bands on the raw Int16 samples
-            if (!audioFocusLost.get()) {
-                frequencyBandAnalyzer?.processSamples(frame, frame.size)
-            }
-```
-
-- [ ] **Step 5: Reset analyzer on turn boundary**
-
-In `pushAudio()`, inside the turn boundary block (after `setState(PipelineState.STREAMING)` at line 359), add:
-
-```kotlin
-                frequencyBandAnalyzer?.reset()
-```
-
-In `invalidateTurn()`, **inside** the `turnLock.withLock` block, after `setState(PipelineState.IDLE)` (line 402) and before the closing brace of the `withLock` block, add:
-
-```kotlin
-            frequencyBandAnalyzer?.reset()
-```
-
-- [ ] **Step 6: Add frequency band timer method**
-
-Add after `startZombieDetection()` (before the VolumeGuard section):
-
-```kotlin
-    // ════════════════════════════════════════════════════════════════════
-    // Frequency band emission
-    // ════════════════════════════════════════════════════════════════════
-
-    private fun startFrequencyBandTimer() {
-        frequencyBandThread = Thread({
-            while (running.get() && !Thread.currentThread().isInterrupted) {
-                try {
-                    Thread.sleep(frequencyBandIntervalMs.toLong())
-                } catch (_: InterruptedException) {
-                    break
-                }
-
-                val analyzer = frequencyBandAnalyzer ?: continue
-                val bands = analyzer.harvest()
-                listener.onFrequencyBands(bands.low, bands.mid, bands.high)
-            }
-        }, "AudioPipeline-FreqBands").apply {
-            isDaemon = true
-            start()
-        }
-    }
-```
-
-- [ ] **Step 7: Wire PipelineIntegration**
-
-In `android/.../pipeline/PipelineIntegration.kt`:
-
-Add event constant (after the last `EVENT_*` constant, around line 94):
-
-```kotlin
-        private const val EVENT_FREQUENCY_BANDS = "PipelineFrequencyBands"
-```
-
-Update `connect()` method to parse new options. After `targetBufferMs` parsing (around line 122), add:
-
-```kotlin
-            val frequencyBandIntervalMs = (options["frequencyBandIntervalMs"] as? Number)?.toInt() ?: 100
-            val bandConfig = options["frequencyBandConfig"] as? Map<*, *>
-            val lowCrossoverHz = (bandConfig?.get("lowCrossoverHz") as? Number)?.toFloat() ?: 300f
-            val highCrossoverHz = (bandConfig?.get("highCrossoverHz") as? Number)?.toFloat() ?: 2000f
-```
-
-Update the `AudioPipeline` constructor call (around line 125) to pass new params:
-
-```kotlin
-            pipeline = AudioPipeline(
-                context = context,
-                sampleRate = sampleRate,
-                channelCount = channelCount,
-                targetBufferMs = targetBufferMs,
-                frequencyBandIntervalMs = frequencyBandIntervalMs,
-                lowCrossoverHz = lowCrossoverHz,
-                highCrossoverHz = highCrossoverHz,
-                listener = this
-            )
-```
-
-Add `onFrequencyBands` implementation (after `onAudioFocusResumed`, around line 304):
-
-```kotlin
-    override fun onFrequencyBands(low: Float, mid: Float, high: Float) {
-        sendEvent(EVENT_FREQUENCY_BANDS, bundleOf(
-            "low" to low, "mid" to mid, "high" to high
-        ))
-    }
-```
-
-- [ ] **Step 8: Register event in ExpoPlayAudioStreamModule.kt**
-
-In `android/.../ExpoPlayAudioStreamModule.kt`, add to the Events block (after the last pipeline event, around line 110):
-
-```kotlin
-                "PipelineFrequencyBands",
-```
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add android/src/main/java/expo/modules/audiostream/pipeline/AudioPipeline.kt \
-    android/src/main/java/expo/modules/audiostream/pipeline/PipelineIntegration.kt \
-    android/src/main/java/expo/modules/audiostream/ExpoPlayAudioStreamModule.kt
-git commit -m "feat: wire frequency band analysis into Android pipeline"
-```
-
----
-
-## Chunk 3: Microphone Integration (iOS + Android)
-
-### Task 6: Wire iOS microphone frequency bands
-
-**Files:**
-- Modify: `ios/MicrophoneDataDelegate.swift` — extend delegate signature
-- Modify: `ios/Microphone.swift` — add analyzer, compute bands, pass to delegate
-- Modify: `ios/ExpoPlayAudioStreamModule.swift` — update delegate implementation to include bands in event
-
-- [ ] **Step 1: Update MicrophoneDataDelegate protocol**
-
-In `ios/MicrophoneDataDelegate.swift`, change the `onMicrophoneData` signature from:
-
-```swift
-    func onMicrophoneData(_ microphoneData: Data, _ soundLevel: Float?)
-```
-
-to:
-
-```swift
-    func onMicrophoneData(_ microphoneData: Data, _ soundLevel: Float?, _ frequencyBands: FrequencyBands?)
-```
-
-- [ ] **Step 2: Add analyzer to Microphone**
-
-In `ios/Microphone.swift`, add a field after `isSilent` (line 29):
-
-```swift
-    private var frequencyBandAnalyzer: FrequencyBandAnalyzer?
-    private var frequencyBandConfig: (lowCrossoverHz: Float, highCrossoverHz: Float)?
-```
-
-- [ ] **Step 3: Create analyzer in startRecording, destroy in stopRecording**
-
-In `startRecording()`, pass config through. Add a parameter:
-
-```swift
-    func startRecording(settings: RecordingSettings, intervalMilliseconds: Int,
-                        frequencyBandConfig: (lowCrossoverHz: Float, highCrossoverHz: Float)? = nil) -> StartRecordingResult? {
-```
-
-After `recordingSettings = newSettings` (line 98), add:
-
-```swift
-        self.frequencyBandConfig = frequencyBandConfig
-        // Analyzer uses the desired (target) sample rate, not hardware rate
-        let targetRate = Int(settings.desiredSampleRate ?? settings.sampleRate)
-        let fbConfig = frequencyBandConfig ?? (lowCrossoverHz: 300, highCrossoverHz: 2000)
-        frequencyBandAnalyzer = FrequencyBandAnalyzer(
-            sampleRate: targetRate,
-            lowCrossoverHz: fbConfig.lowCrossoverHz,
-            highCrossoverHz: fbConfig.highCrossoverHz
-        )
-```
-
-In `stopRecording()`, after `audioEngine.stop()` (line 153), add:
-
-```swift
-        frequencyBandAnalyzer = nil
-```
-
-- [ ] **Step 4: Compute bands in processAudioBuffer**
-
-In `processAudioBuffer()`, after the `data` variable is assigned (after the format conversion block ending around line 213) and before `totalDataSize += ...` (line 215), add:
-
-```swift
-        // Compute frequency bands from the Int16 PCM data
-        let bands: FrequencyBands?
-        if isSilent {
-            bands = .zero
-        } else if let analyzer = frequencyBandAnalyzer {
-            analyzer.processSamplesFromData(data)
-            bands = analyzer.harvest()
-        } else {
-            bands = nil
-        }
-```
-
-Update the delegate call (line 218) from:
-
-```swift
-        self.delegate?.onMicrophoneData(data, powerLevel)
-```
-
-to:
-
-```swift
-        self.delegate?.onMicrophoneData(data, powerLevel, bands)
-```
-
-- [ ] **Step 5: Update ExpoPlayAudioStreamModule delegate implementation**
-
-In `ios/ExpoPlayAudioStreamModule.swift`, update the `onMicrophoneData` implementation (around line 387).
-
-Change the method signature from:
-
-```swift
-    func onMicrophoneData(_ microphoneData: Data, _ soundLevel: Float?) {
-```
-
-to:
-
-```swift
-    func onMicrophoneData(_ microphoneData: Data, _ soundLevel: Float?, _ frequencyBands: FrequencyBands?) {
-```
-
-**Important:** The existing `eventBody` is declared with `let` (immutable). Change `let eventBody: [String: Any]` to `var eventBody: [String: Any]` on line 390. Then after the `soundLevel` entry, add:
-
-```swift
-            if let bands = frequencyBands {
-                eventBody["frequencyBands"] = [
-                    "low": bands.low,
-                    "mid": bands.mid,
-                    "high": bands.high
-                ]
-            }
-```
-
-- [ ] **Step 6: Pass frequency band config from module to microphone**
-
-In `ios/ExpoPlayAudioStreamModule.swift`, in the `startMicrophone` AsyncFunction (line 153), after the `interval` extraction (line 159), add:
-
-```swift
-            let fbConfigDict = options["frequencyBandConfig"] as? [String: Any]
-            let fbConfig: (lowCrossoverHz: Float, highCrossoverHz: Float)? = fbConfigDict.map {
-                (
-                    lowCrossoverHz: ($0["lowCrossoverHz"] as? NSNumber)?.floatValue ?? 300,
-                    highCrossoverHz: ($0["highCrossoverHz"] as? NSNumber)?.floatValue ?? 2000
-                )
-            }
-```
-
-Then update the `startRecording` call at line 179 from:
-
-```swift
-            if let result = self.microphone.startRecording(settings: settings, intervalMilliseconds: interval) {
-```
-
-to:
-
-```swift
-            if let result = self.microphone.startRecording(settings: settings, intervalMilliseconds: interval, frequencyBandConfig: fbConfig) {
-```
-
-Also update the route change handler in `ios/Microphone.swift` (line 57) to pass the stored config:
-
-```swift
-                    _ = startRecording(settings: self.recordingSettings!, intervalMilliseconds: 100, frequencyBandConfig: self.frequencyBandConfig)
-```
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add ios/MicrophoneDataDelegate.swift ios/Microphone.swift ios/ExpoPlayAudioStreamModule.swift
-git commit -m "feat: wire frequency band analysis into iOS microphone"
-```
-
----
-
-### Task 7: Wire Android microphone frequency bands
-
-**Files:**
-- Modify: `android/src/main/java/expo/modules/audiostream/AudioRecorderManager.kt` — add analyzer, compute bands, emit in event
-
-- [ ] **Step 1: Add analyzer field and config**
-
-In `AudioRecorderManager.kt`, add fields after `isSilent` (line 38):
-
-```kotlin
-    private var frequencyBandAnalyzer: FrequencyBandAnalyzer? = null
-```
-
-- [ ] **Step 2: Create analyzer in startRecording, destroy in cleanup**
-
-In `startRecording()`, after `audioRecord?.startRecording()` (line 155) and effect setup, add:
-
-```kotlin
-        // Create frequency band analyzer
-        val bandConfig = options["frequencyBandConfig"] as? Map<*, *>
-        frequencyBandAnalyzer = FrequencyBandAnalyzer(
-            sampleRate = recordingConfig.sampleRate,
-            lowCrossoverHz = (bandConfig?.get("lowCrossoverHz") as? Number)?.toFloat() ?: 300f,
-            highCrossoverHz = (bandConfig?.get("highCrossoverHz") as? Number)?.toFloat() ?: 2000f
-        )
-```
-
-In `cleanupResources()`, after `streamUuid = null` (line 220), add:
-
-```kotlin
-            frequencyBandAnalyzer = null
-```
-
-- [ ] **Step 3: Compute bands in emitAudioData**
-
-In `emitAudioData()`, after `soundLevel` calculation (line 374), add:
-
-```kotlin
-        // Compute frequency bands
-        val bands = if (isSilent) {
-            FrequencyBands.ZERO
-        } else {
-            frequencyBandAnalyzer?.let { analyzer ->
-                analyzer.processSamplesFromBytes(audioData, length)
-                analyzer.harvest()
-            }
-        }
-```
-
-In the event Bundle construction (inside `mainHandler.post`, around line 388), after the `soundLevel` entry, add:
-
-```kotlin
-                        "frequencyBandsLow" to (bands?.low ?: 0f),
-                        "frequencyBandsMid" to (bands?.mid ?: 0f),
-                        "frequencyBandsHigh" to (bands?.high ?: 0f),
-```
-
-Use the nested `bundleOf` pattern for consistency with the iOS side and the TypeScript `FrequencyBands` interface structure:
-
-```kotlin
-                        "frequencyBands" to bundleOf(
-                            "low" to (bands?.low ?: 0f),
-                            "mid" to (bands?.mid ?: 0f),
-                            "high" to (bands?.high ?: 0f)
-                        ),
-```
-
-Remove the flat key alternative shown above — use only the nested pattern.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add android/src/main/java/expo/modules/audiostream/AudioRecorderManager.kt
-git commit -m "feat: wire frequency band analysis into Android microphone"
-```
-
----
-
-### Task 8: Build verification
-
-- [ ] **Step 1: Verify TypeScript compiles**
-
-```bash
-cd /Users/edward.kimmel/Documents/GitHub/expo-audio-stream
-npx tsc --noEmit
-```
-
-Expected: No errors.
-
-- [ ] **Step 2: Verify the module builds**
-
-If an example app exists, build it. Otherwise verify the TypeScript compilation is clean and the native code compiles by checking for syntax errors.
-
-- [ ] **Step 3: Final commit**
-
-```bash
-git add -A
-git status
-# Only commit if there are remaining changes
-git commit -m "feat: frequency band analysis - build verification clean"
-```

package/docs/superpowers/specs/2026-03-13-frequency-band-analysis-design.md

@@ -1,276 +0,0 @@
-# Frequency Band Analysis — Design Spec
-
-## Overview
-
-Add real-time low/mid/high frequency band analysis to both microphone capture and pipeline playback in the expo-audio-stream native module. The analysis uses two parallel single-pole IIR (Infinite Impulse Response) low-pass filters — O(n) per sample, no FFT — to split audio into three bands and compute RMS energy for each.
-
-## Motivation
-
-The JavaScript side of the module does not have visibility into what the native audio engine is actually playing or capturing at the PCM level. Frequency band data must be computed natively where the raw samples are available.
-
-## Requirements
-
-1. **Microphone**: Emit `{low, mid, high}` frequency band RMS values alongside each `AudioData` event (same interval as mic capture).
-2. **Pipeline playback**: Emit `{low, mid, high}` via a new `PipelineFrequencyBands` event at a configurable interval, independent of chunk size or mic config.
-3. When the pipeline is connected but not actively playing audio, emit near-zero values (not silence/no-emit).
-4. Band crossover frequencies (default 300 Hz low/mid, 2000 Hz mid/high) are configurable at connect/start time.
-5. OTA-safe — no native API surface changes that would require a new binary build beyond the module update itself.
-
-## Non-Goals
-
-- FFT-based spectral analysis or arbitrary band counts.
-- Frequency analysis for the SoundPlayer (chunk-based) path — pipeline only.
-- Web platform support (native-only feature).
-
----
-
-## Architecture
-
-### FrequencyBandAnalyzer — Shared DSP Component
-
-A pure-math class on each platform (Swift / Kotlin) encapsulating the IIR filter state and energy accumulation. No threading or platform audio dependencies.
-
-#### State
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `lp1` | Float | Low-pass accumulator 1 (low crossover) |
-| `lp2` | Float | Low-pass accumulator 2 (high crossover) |
-| `alphaLow` | Float | Precomputed coefficient: `min(1, 2*PI*lowCrossover/sampleRate)` |
-| `alphaHigh` | Float | Precomputed coefficient: `min(1, 2*PI*highCrossover/sampleRate)` |
-| `lowE` | Float | Accumulated low-band energy (sum of squares) |
-| `midE` | Float | Accumulated mid-band energy |
-| `highE` | Float | Accumulated high-band energy |
-| `count` | Int | Number of samples processed since last harvest |
-
-#### Methods
-
-| Method | Description |
-|--------|-------------|
-| `init(sampleRate, lowCrossoverHz=300, highCrossoverHz=2000)` | Precompute alpha coefficients from sample rate and crossover frequencies |
-| `processSamples(samples: Int16[], length: Int)` | Run IIR filter over a batch of PCM16 samples, accumulate energy. Called from write/schedule loop. |
-| `harvest() -> {low, mid, high}` | Return RMS values (`sqrt(energy/count)`), reset accumulators to zero. Called from timer or inline. |
-| `reset()` | Zero all state (filter accumulators + energy). Called on turn change / disconnect / stop. |
-
-#### DSP Algorithm (per sample)
-
-```
-s = int16sample / 32768.0          // normalize to [-1, 1] (matches existing codebase convention)
-lp1 += alphaLow * (s - lp1)       // independent low-pass at 300 Hz
-lp2 += alphaHigh * (s - lp2)      // independent low-pass at 2000 Hz
-low  = lp1                         // below 300 Hz
-high = s - lp2                     // above 2000 Hz
-mid  = s - low - high              // 300–2000 Hz (= lp2 - lp1)
-lowE  += low * low
-midE  += mid * mid
-highE += high * high
-count += 1
-```
-
-Note: The two filters operate in parallel on the same input `s` (not cascaded).
-For stereo audio, interleaved samples are processed as a single stream — the filter
-state spans both channels, which is intentional since we only need aggregate energy
-levels, not per-channel analysis.
-
-#### Synchronization
-
-- **Pipeline analyzer**: `processSamples()` runs on write/schedule thread; `harvest()` runs on timer thread. A simple mutex (NSLock / ReentrantLock) guards the accumulator read/reset. Contention is negligible — harvest fires every 50–100ms and takes microseconds.
-- **Microphone analyzer**: No synchronization needed — both `processSamples()` and `harvest()` run in the same callback/thread.
-
----
-
-### Pipeline Integration (Playback Bands)
-
-#### Injection Point — processSamples
-
-- **iOS** (`AudioPipeline.scheduleNextBuffer`): After `buf.read(dest: &renderSamples, ...)` populates the Int16 array, call `analyzer.processSamples(renderSamples, frameSizeSamples)` before the Float32 conversion.
-- **Android** (`AudioPipeline.writeLoop`): After `buf.read(frame)` populates the ShortArray, call `analyzer.processSamples(frame, frame.size)` before `track.write()`.
-
-Both paths already have the Int16 samples in a local variable — zero additional allocation.
-
-#### Harvest Timer
-
-A new timer created in `connect()`, destroyed in `disconnect()`:
-
-- **iOS**: `DispatchSourceTimer` on `.main`, interval from config.
-- **Android**: Daemon thread with `Thread.sleep(intervalMs)`.
-
-The timer calls `analyzer.harvest()` and emits a `PipelineFrequencyBands` event through the `PipelineListener` -> `PipelineIntegration` -> Expo event bridge. This requires adding a new method to the `PipelineListener` protocol (iOS) and interface (Android):
-
-- iOS: `func onFrequencyBands(low: Float, mid: Float, high: Float)`
-- Android: `fun onFrequencyBands(low: Float, mid: Float, high: Float)`
-
-**Default interval**: `frequencyBandIntervalMs` defaults to 100ms. The default is applied in the native `PipelineIntegration.connect()` on both platforms when parsing options (same pattern as `targetBufferMs` defaulting to 80).
-
-#### Idle/Drained Behavior
-
-When the pipeline is connected but idle/drained, the write loop continues running (writing silence from the jitter buffer). The analyzer accumulates near-zero energy from silence samples, so `harvest()` naturally returns values near zero without special-casing.
-
-#### Turn Boundary
-
-On turn change (`pushAudio` with `isFirstChunk` or `invalidateTurn`), call `analyzer.reset()` to clear stale filter state from the previous turn.
-
-#### Lifecycle
-
-| Event | Action |
-|-------|--------|
-| `connect()` | Create analyzer, start harvest timer |
-| `disconnect()` | Stop harvest timer, destroy analyzer |
-| Turn boundary | `analyzer.reset()` |
-| Route change / engine rebuild | Analyzer state preserved (continues accumulating) |
-
----
-
-### Microphone Integration
-
-#### Injection Point
-
-- **iOS** (`Microphone.processAudioBuffer`): After resampling and Int16 conversion (which produces a `Data` object), extract the Int16 samples into a temporary `[Int16]` array (or provide a `processSamplesFromData(_ data: Data)` convenience method on the analyzer that interprets the bytes as little-endian Int16). Call `processSamples()` then `harvest()` inline — each tap callback = one interval.
-- **Android** (`AudioRecorderManager.emitAudioData`): Wrap the raw `audioData: ByteArray` in a `ByteBuffer` with `LITTLE_ENDIAN` order and read as a `ShortArray` (same pattern used in `AudioPipeline.pushAudio`). Call `processSamples()` then `harvest()` inline — each `read()` = one interval.
-
-#### Event Delivery
-
-Add `frequencyBands` fields to the existing `AudioData` event payload:
-
-- iOS: Add to the dictionary passed to `onMicrophoneData` delegate callback
-- Android: Add to the Bundle in `emitAudioData`
-
-#### Silent Mode
-
-When `isSilent` is true, skip frequency analysis and emit `{low: 0, mid: 0, high: 0}`.
-
-#### Lifecycle
-
-| Event | Action |
-|-------|--------|
-| `startRecording()` | Create analyzer with target sample rate and config |
-| `stopRecording()` | Destroy analyzer |
-
----
-
-## TypeScript API Changes
-
-### New Types
-
-```typescript
-/** RMS energy per frequency band, range [0, 1]. */
-export interface FrequencyBands {
-  low: number;
-  mid: number;
-  high: number;
-}
-
-/** Crossover frequency configuration. */
-export interface FrequencyBandConfig {
-  /** Low/mid crossover in Hz (default 300). */
-  lowCrossoverHz?: number;
-  /** Mid/high crossover in Hz (default 2000). */
-  highCrossoverHz?: number;
-}
-```
-
-### Modified Types
-
-#### AudioDataEvent (microphone)
-
-```typescript
-export interface AudioDataEvent {
-  // ... existing fields ...
-  /** Frequency band RMS energy, present when recording is active. */
-  frequencyBands?: FrequencyBands;
-}
-```
-
-#### RecordingConfig (microphone)
-
-```typescript
-export interface RecordingConfig {
-  // ... existing fields ...
-  /** Optional frequency band crossover configuration. */
-  frequencyBandConfig?: FrequencyBandConfig;
-}
-```
-
-#### ConnectPipelineOptions (pipeline)
-
-```typescript
-export interface ConnectPipelineOptions {
-  // ... existing fields ...
-  /** Interval in ms for PipelineFrequencyBands events (default 100). */
-  frequencyBandIntervalMs?: number;
-  /** Optional frequency band crossover configuration. */
-  frequencyBandConfig?: FrequencyBandConfig;
-}
-```
-
-### New Event
-
-```typescript
-/** Payload for PipelineFrequencyBands event. */
-export interface PipelineFrequencyBandsEvent extends FrequencyBands {}
-
-// Added to PipelineEventMap:
-export interface PipelineEventMap {
-  // ... existing events ...
-  PipelineFrequencyBands: PipelineFrequencyBandsEvent;
-}
-```
-
-### Usage Example
-
-```typescript
-// Microphone — bands arrive with each AudioData event
-stream.subscribeToAudioEvents(async (event) => {
-  if (event.frequencyBands) {
-    updateMicVisualization(event.frequencyBands);
-  }
-});
-
-// Pipeline — bands arrive at configured interval
-pipeline.subscribe('PipelineFrequencyBands', (bands) => {
-  updatePlaybackVisualization(bands);
-});
-
-// Configuration
-await pipeline.connect({
-  sampleRate: 24000,
-  frequencyBandIntervalMs: 50,
-  frequencyBandConfig: { lowCrossoverHz: 250, highCrossoverHz: 2500 },
-});
-```
-
----
-
-## File Changes Summary
-
-### New Files
-
-| File | Description |
-|------|-------------|
-| `ios/FrequencyBandAnalyzer.swift` | iOS DSP component |
-| `android/.../FrequencyBandAnalyzer.kt` | Android DSP component |
-
-### Modified Files
-
-| File | Change |
-|------|--------|
-| `ios/AudioPipeline.swift` | Add analyzer field, accept frequency band config in init, call processSamples in scheduleNextBuffer, add harvest timer, reset on turn boundary, add `onFrequencyBands` to PipelineListener protocol |
-| `ios/PipelineIntegration.swift` | Add `PipelineFrequencyBands` event constant, parse new config options in `connect()`, forward from new listener method |
-| `ios/Microphone.swift` | Add analyzer field, compute bands in processAudioBuffer, pass to delegate |
-| `ios/MicrophoneDataDelegate.swift` | Update delegate method signature to include frequency bands |
-| `android/.../pipeline/AudioPipeline.kt` | Add analyzer field, accept frequency band config in constructor, call processSamples in writeLoop, add harvest timer thread, reset on turn boundary, add `onFrequencyBands` to PipelineListener interface |
-| `android/.../pipeline/PipelineIntegration.kt` | Add event constant, parse new config options in `connect()`, forward frequency bands event |
-| `android/.../AudioRecorderManager.kt` | Add analyzer field, compute bands in emitAudioData |
-| `src/types.ts` | Add FrequencyBands, FrequencyBandConfig types; extend AudioDataEvent, RecordingConfig |
-| `src/pipeline/types.ts` | Add PipelineFrequencyBandsEvent; extend ConnectPipelineOptions, PipelineEventMap |
-| `ios/ExpoPlayAudioStreamModule.swift` | Register new PipelineFrequencyBands event name |
-| `android/.../ExpoPlayAudioStreamModule.kt` | Register new PipelineFrequencyBands event name |
-
----
-
-## Edge Cases
-
-1. **Very short buffers** (< 10 samples): `harvest()` returns zeros if `count == 0` to avoid division by zero.
-2. **Sample rate change**: Analyzer is destroyed and recreated — alpha coefficients depend on sample rate.
-3. **Mono vs stereo**: For stereo pipeline audio, process interleaved samples treating L+R as a single stream. The IIR filter state will span both channels, which causes slight cross-channel smearing — acceptable since we need aggregate energy levels, not per-channel analysis.
-4. **Float overflow**: Energy accumulation uses Float (32-bit). At 48kHz with 100ms harvest interval, that's ~4800 samples — well within Float32 precision for sum-of-squares accumulation.