DEV Community: Felix Zeller

Real-Time Breath Detection in the Browser: Spectral Centroid, Dual-Path State Machines, and a Nasty iOS Bug

Felix Zeller — Sun, 12 Apr 2026 20:16:54 +0000

Microphone-based breath detection sounds simple until you actually try it. Energy goes up, energy goes down — that's a breath, right? In practice, you run into continuous breathing with no silence gaps, noisy environments that drift over time, and (on iOS) a Web Audio API that silently returns all zeros. This post walks through how @shiihaa/breath-detection solves each of these problems.

The library was extracted from shii·haa, a breathwork and biofeedback app built by Felix Zeller, a Swiss physician (Intensive Care + Internal Medicine + Diplompsychologe). It's MIT-licensed, zero dependencies, and ships TypeScript types.

Installation

npm install @shiihaa/breath-detection

The Core Idea: Spectral Centroid for Inhale/Exhale Classification

Most breath detectors only measure when breathing occurs — they can't tell you whether a given phase is an inhale or an exhale. This one can, and the reason is grounded in physiology.

When you inhale through your nose, air moves through narrow nasal passages and turbinates. That turbulence generates higher-frequency acoustic energy. When you exhale, airflow is slower and more laminar — the spectral energy shifts down.

Phase	Airflow	Centroid range
Inhale	Turbulent	~800–2500 Hz
Exhale	Laminar	~200–800 Hz

The library computes the spectral centroid from a 4096-point FFT over the 150–2500 Hz band on every tick. If the centroid of phase A is meaningfully higher than phase B, it labels A as inhale and B as exhale. The BreathCycle object even exposes a labelSwapped flag for cases where the centroid evidence flipped the initial threshold-based guess.

The Detection Pipeline

Microphone → FFT → Energy + Centroid → State Machine → Breath Cycles
                                              ↑
                                     Peak Counter (fallback)

State machine (primary path): Energy crosses the calibrated threshold → active phase begins. Energy drops to near-noise-floor → silent phase begins. One active + one silent = one breath cycle. This works well for deliberate breathwork with natural pauses.

Peak fallback (secondary path): Some people breathe continuously without any silence gap — the energy never fully drops. In that case, the library counts energy peaks instead. Two peaks = one breath cycle, with the trough between them treated as the phase boundary. The method field in BreathCycle tells you which path fired: 'threshold' or 'peak'.

Quick Start

import { BreathDetector } from '@shiihaa/breath-detection';

const detector = new BreathDetector({
  thresholdFactor: 0.35,   // 0 = sensitive, 1 = strict
  enableCentroid: true,
  centroidThreshold: 40,   // Hz difference for confident labeling
  minCycleGapSeconds: 2.5,
});

detector.onCycle((cycle) => {
  console.log(`${cycle.inhaleMs}ms in / ${cycle.exhaleMs}ms out`);
  console.log(`Rate: ${(60000 / cycle.cycleMs).toFixed(1)} breaths/min`);
  console.log(`Method: ${cycle.method}`); // 'threshold' or 'peak'
  console.log(`Centroid A: ${cycle.centroidA1}Hz, B: ${cycle.centroidA2}Hz`);
});

detector.onPhase((event) => {
  // fires every tick — useful for live UI feedback
  console.log(`Phase: ${event.phase}, Energy: ${event.energy.toFixed(3)}`);
});

const ok = await detector.start();
if (!ok) { console.error('Mic access denied'); return; }

// 6-second calibration: 2s silence + 4s breathing
const cal = await detector.calibrate();
console.log(`Noise floor: ${cal.noiseFloor.toFixed(4)}`);
console.log(`Breath max: ${cal.breathMax.toFixed(4)}`);

detector.startDetection();

Auto-Recalibration

One underrated problem: users move rooms, switch from earbuds to laptop mic, or the HVAC kicks on. The library re-samples the noise floor every 10 seconds during active detection, so the threshold adapts without requiring a fresh calibration call.

The iOS Problem (and the Fix)

If you're building a Capacitor app, there's a well-known but poorly documented bug: AnalyserNode.getByteFrequencyData() returns all zeros inside WKWebView even when getUserMedia succeeds and the microphone is actually capturing audio.

// ❌ Broken on iOS WKWebView
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const ctx = new AudioContext();
const analyser = ctx.createAnalyser();
ctx.createMediaStreamSource(stream).connect(analyser);

const data = new Uint8Array(analyser.frequencyBinCount);
analyser.getByteFrequencyData(data);
console.log(data); // [0, 0, 0, 0, ...] — even when mic is live

The companion plugin @shiihaa/capacitor-audio-analysis routes microphone capture through native AVAudioEngine in Swift, computes RMS and band energy there, and emits the results as Capacitor events. BreathDetector can then consume those values instead of touching the Web Audio API.

npm install @shiihaa/capacitor-audio-analysis
npx cap sync

import { AudioAnalysis } from '@shiihaa/capacitor-audio-analysis';

await AudioAnalysis.start({ gain: 8.0 });

const handle = await AudioAnalysis.addListener('audioData', (data) => {
  console.log('RMS:', data.rms);         // smoothed 0–1
  console.log('Band energy:', data.bandEnergy); // 150–2500 Hz proxy
});

BreathCycle Object

Every completed cycle delivers:

{
  inhaleMs: number;      // inhale duration
  exhaleMs: number;      // exhale duration
  holdInMs: number;      // breath hold after inhale (0 if none)
  holdOutMs: number;     // breath hold after exhale (0 if none)
  cycleMs: number;       // total cycle duration
  peakEnergy: number;    // 0–1
  confidence: number;    // 0–100
  labelSwapped: boolean; // centroid overrode threshold labeling
  centroidA1: number;    // spectral centroid for phase 1 (Hz)
  centroidA2: number;    // spectral centroid for phase 2 (Hz)
  method: 'threshold' | 'peak';
  timestamp: number;
}

What It's Designed For

The library was built for guided breathwork (box breathing, 4-7-8, coherence breathing) and biofeedback applications where you need reliable per-cycle data with inhale/exhale distinction. It's not a medical device. Confidence scores and the labelSwapped flag give you enough signal to decide whether to trust a given cycle for real-time feedback or discard it.

Beyond the Timer: How Biofeedback Changes Everything About Breathwork Apps

Felix Zeller — Sun, 12 Apr 2026 13:08:39 +0000

You've been here before. Deadline approaching, shoulders up around your ears, chest tight. Someone tells you to take a deep breath. So you try. And then you wonder: did that actually do anything?

Most breathwork apps are glorified timers. They show you an animation, tell you when to inhale and exhale, and leave you to guess whether your nervous system got the memo. shii·haa works differently. Instead of simply telling you when to breathe, it listens — and then shows you what your body is actually doing.

What Makes shii·haa Different

The core insight is simple but significant: breathing exercises only work if your body responds to them. The question was never how to breathe. It was always: is it working?

shii·haa answers that question in real time through two channels.

The first is your microphone. The app detects the sound of your breath — the gentle turbulence of air moving through your nose and mouth — and translates that into a live rhythm signal. No wearable required. Just breathe normally.

The second is your heart. Connect a Bluetooth chest strap — Garmin, Polar, Wahoo, or any standard BLE heart rate monitor — and the app reads your heartbeats one by one. Not an average, but a living, moment-to-moment signal that changes with every breath.

Alone, each signal tells you something. Together, they tell you something remarkable.

The Science: Respiratory Sinus Arrhythmia

Your heart rate is not steady. Even sitting still, your heartbeats speed up slightly when you inhale and slow down when you exhale. This is called Respiratory Sinus Arrhythmia (RSA) — not a medical problem, but a sign of a healthy, flexible nervous system.

The vagus nerve modulates your heart rate in sync with your breathing. When that coupling is strong, your body is in a state of physiological coherence: calm, regulated, resilient. When you're chronically stressed, that coupling weakens. Your heart rate variability flattens.

This is exactly what clinical biofeedback therapists measure — using equipment that costs thousands of euros and sessions at €150–200 each. shii·haa brings that same measurement to your phone.

When you breathe slowly — five to six breaths per minute — and your exhale is slightly longer than your inhale, your heart and breathing fall into natural resonance. You can feel it as calm clarity. With shii·haa, you can also see it.

The Stimmungs-Check: Start Where You Are

Before choosing a technique, you need to know where you're starting from. That's the Stimmungs-Check — thirty seconds of free breathing. No instructions, no pattern. Just breathe naturally while the app listens.

It analyzes:

Breathing rate — how many breaths per minute?
Inhale-to-exhale ratio — are your exhales longer, or are you holding without realizing?
Regularity — consistent or erratic and shallow?
Cardiac response — how strongly is your heart responding to each breath?

Then it gives you a personalized recommendation. Not the same sequence every day. A suggestion built on what your body just told it.

Three Signals, One Picture

Sound is the most immediate. The microphone hears the acoustics of your breath and translates it into a rhythm the app can track. It tells the app exactly when you inhale and exhale, down to the second.

Heart rate is the deeper layer. Beat by beat, the app watches how your cardiac rhythm rises and falls with your breathing. This is where the biofeedback becomes genuinely clinical.

Pattern recognition ties it together. The app recognizes the shape of your breathing — peaks, valleys, rhythm — and identifies whether you're moving toward coherence or away from it.

When all three signals agree, the picture is remarkably clear. When your breathing is smooth and your heart rises and falls in step with each breath, you're in coherence — and you can feel it, because that feeling has a name: calm.

How a Session Works

A biofeedback session in shii·haa follows a natural arc — from listening, to understanding, to guided practice.

1. Calibrate

Every session begins with a few seconds of calibration. Hold your phone about 30 cm in front of you. Be still for a moment, then breathe normally. The app learns the difference between silence and your breath — your personal baseline, in this room, right now. If you're wearing a chest strap, it picks up your resting heart rate at the same time.

2. Breathe Freely

Then you breathe — however you want. There's no timer telling you when to inhale or exhale. The app watches and listens, tracking your natural rhythm in real time. The breathing circle expands and contracts with your actual breath. The oscillograph shows your audio signal. If a chest strap is connected, your heart rate pulses alongside it.

This is the exploration phase. You discover your own pattern without being told what it should be.

3. Analyze

After the free session, shii·haa shows you what it observed:

Breathing rate — your actual breaths per minute
I:E ratio — how your inhale compares to your exhale
Regularity — how consistent your rhythm was
HRV metrics — RMSSD, SDNN, and coherence score (with chest strap)
RSA correlation — how tightly your heart followed your breath

These aren't abstract numbers. They're a mirror. You see exactly how your body responded to your breathing — and where there's room to go deeper.

4. Your Rhythm, Your Ratios

Here is where shii·haa does something no other breathwork app does.

Every technique in the app — 4-7-8 relaxation, box breathing, coherence, resonance, and many more — has a defined ratio: the relationship between inhale, hold, exhale, and pause. A 4-7-8 pattern means inhaling for one unit, holding for 1.75 units, and exhaling for two units. That ratio is what creates the physiological effect. Not the absolute duration.

Most apps tell everyone to breathe 4 seconds in, 7 seconds hold, 8 seconds out. But if your natural inhale is 3 seconds, forcing a 4-second inhale creates tension. If your natural rhythm is slower, 4 seconds feels rushed. The technique fights your body instead of working with it.

shii·haa takes a different approach. You start by breathing a technique freely — at your own pace, guided by the ratios but not locked to a metronome. The app observes your natural tempo: how long your inhales actually take, how your body settles into the pattern. It measures your personal base rhythm.

Then, for the guided session, the app adapts the absolute timings to your rhythm. If your natural inhale is 3.2 seconds and the technique calls for a 1:1.75:2 ratio, the guided session becomes 3.2s inhale, 5.6s hold, 6.4s exhale. The ratio stays precise. The tempo becomes yours.

The app corrects the ratios — not your rhythm. If your exhale was too short relative to the pattern, it gently extends it. If your hold was cut short, it adds a moment. But the fundamental pace stays anchored to how you actually breathe.

This matters more than most people realize. The ratio between inhale and exhale determines the autonomic effect: a longer exhale activates the parasympathetic nervous system (calming), equal phases create balance (focus), emphasis on the inhale activates the sympathetic system (energy). The absolute seconds are just a vehicle for the ratio. Your body doesn't care whether you breathe in for 4 seconds or 3.2 seconds. It cares about the Gestalt of the breath.

And with the biofeedback running throughout, you can verify it in real time. Watch your HRV improve, your coherence score rise, your heart-breath coupling strengthen — all at a pace that feels natural, not forced.

That's the difference between following a timer and being guided by your own body. Proof, not hope. Your rhythm, not someone else's.

Who This Is For

Anyone who wants to know if their breathing practice is actually working.

People with anxiety who want evidence that "just breathe" actually helps. Athletes who track HRV for performance. Meditators who want to watch their nervous system settle. People with insomnia who use breathwork before bed. And curious humans who want to understand how their body works.

You don't need a clinical diagnosis. You just need to be a person with a nervous system.

Built by a Doctor, Not a Startup

shii·haa was created by Dr. Felix Zeller — an intensive care physician, emergency doctor, and clinical psychologist based in Zürich.

Felix built this because he saw what clinical biofeedback could do for patients in real distress — and then watched those same patients go home without any way to continue. The equipment was too expensive. The sessions too infrequent. The gap between clinical insight and everyday life too wide.

shii·haa is his attempt to close that gap. Not a simplified version of biofeedback, but a genuine measurement tool that happens to live in your pocket.

Try It

shiihaa.app — runs in Chrome, no install needed. iOS and Android apps also available.

A Bluetooth chest strap is optional but recommended for full biofeedback. Any standard BLE heart rate monitor works. Dana pricing — pay what you wish.

The next time you take a deep breath, you don't have to wonder if it worked. Your body will show you.

Felix Zeller is an intensive care physician, emergency doctor, and clinical psychologist based in Zürich. He built shii·haa — a breathwork and biofeedback app — with Perplexity Computer. Try it at shiihaa.app.

How We Solved iOS Audio Analysis for Breathwork Biofeedback

Felix Zeller — Sun, 12 Apr 2026 13:05:48 +0000

Real-time breath detection sounds straightforward until you try to ship it on iOS. Our app, shii·haa, guides users through breathwork and provides live biofeedback — it needs to hear you breathe and respond, frame by frame. In the browser, this is about twenty lines of Web Audio API code. On iOS inside a Capacitor app, it turned into a three-month rabbit hole that ended with us writing a native Swift plugin and open-sourcing it.

This is the story of that journey.

Plugin links:

The Challenge

shii·haa is a breathwork and biofeedback app built with Ionic, Capacitor, and Vue 3, running as a progressive web app, an iOS app, and an Android app from a single codebase. One of its core features is real-time audio analysis: the app listens to the user's breathing through the microphone, computes the energy envelope of the signal, and uses that to detect inhale and exhale phases.

On the web, this works beautifully. The Web Audio API's AnalyserNode gives you a frequency-domain or time-domain buffer every animation frame. You compute the RMS (root mean square) of the time-domain signal, apply a short rolling average, and you have a breath curve. Clinical-grade signal processing in a weekend.

Then we packaged the app for iOS. That's when things stopped working.

The Bug

Inside a Capacitor iOS app, the web content runs in a WKWebView. Apple's WKWebView supports getUserMedia — the API that gives you access to the microphone — starting with iOS 14.5. So microphone access works. The stream arrives. The AudioContext creates. No errors are thrown.

But the AnalyserNode returns garbage.

Specifically: getByteTimeDomainData() fills its array entirely with 128 — the silence value in an unsigned 8-bit PCM encoding. getByteFrequencyData() returns all zeros. No matter how loudly you breathe into the phone, the data never changes.

This is a known WebKit bug. The audio stream from getUserMedia inside WKWebView is not actually routed into the Web Audio graph the way it is in Safari. The MediaStreamSourceNode receives the stream, no exception is raised, but the audio samples delivered to the AnalyserNode are silent placeholders. The signal is there at the OS level — iOS is capturing your microphone — but the bridge between the native audio session and the WebView's audio rendering process is broken for analysis purposes.

Related reports:

The fundamental problem is architectural. WKWebView runs the web content in a separate process (the WebKit renderer process) for security and stability. When you call getUserMedia, the microphone permission is granted to the host app process, not the renderer. Audio gets bridged across the process boundary, but in a way that works for playback and WebRTC — not for AnalyserNode tap-style analysis. The audio just doesn't arrive at the right place.

What We Tried (and Failed)

Adjusting getUserMedia constraints

Our first hypothesis was that the audio processing pipeline needed specific hints. We tried every combination of constraints imaginable:

const stream = await navigator.mediaDevices.getUserMedia({
  audio: {
    echoCancellation: false,
    noiseSuppression: false,
    autoGainControl: false,
    sampleRate: 44100,
    channelCount: 1,
  }
});

Result: same silent data. The constraints affect what the OS attempts to configure, but the sampling gap happens downstream of that.

ScriptProcessorNode

ScriptProcessorNode is deprecated but still works in most browsers. It fires an onaudioprocess callback every buffer, letting you inspect raw samples in JavaScript. We wired it in as an alternative to AnalyserNode:

const processor = audioContext.createScriptProcessor(2048, 1, 1);
processor.onaudioprocess = (e) => {
  const inputData = e.inputBuffer.getChannelData(0);
  // inputData was all zeros on iOS WKWebView
};

Same problem. The audio samples reaching the callback were flat. This confirmed the issue isn't specific to AnalyserNode — the entire getUserMedia-to-WebAudio pipeline is broken for analysis in WKWebView.

cordova-plugin-audioinput

This Cordova plugin routes audio through a native capture path and delivers PCM data to JavaScript via Cordova events. Some community members reported it working as a workaround. We tried bridging it into our Capacitor project.

It partially worked — we could receive audio data — but the integration was fragile. The plugin's timing model didn't align cleanly with our animation-frame-based rendering loop, latency was unpredictable, and the plugin is effectively unmaintained. More critically, we couldn't control the capture format cleanly enough for our RMS computation to be reliable.

GainNode amplification

One forum suggestion was that the signal was present but too quiet. We added a GainNode with a gain of 50:

const gainNode = audioContext.createGain();
gainNode.gain.value = 50;
source.connect(gainNode);
gainNode.connect(analyser);

No change. When the input buffer is all zeros, amplifying it by 50 still gives you zeros.

We were stuck.

The Solution: A Native Capacitor Plugin with AVAudioEngine

The insight we needed: the microphone is working in the iOS app. The OS is happily capturing audio. The problem is purely about getting that data into JavaScript. We didn't need the Web Audio API at all — we needed to bypass WKWebView's broken bridge entirely.

The solution was to write a native Capacitor plugin in Swift that:

Opens the microphone using AVAudioEngine — Apple's native, fully-featured audio graph framework
Installs a tap on the input node that fires on every audio buffer
Computes the RMS of each buffer in Swift (fast, low-overhead)
Emits the result back to JavaScript via Capacitor's event system

The architecture looks like this:

[iOS Microphone]
       ↓
[AVAudioEngine InputNode]
       ↓  (installTap callback, runs on audio thread)
[RMS computation in Swift]
       ↓
[Capacitor notifyListeners()]
       ↓
[JavaScript event handler]
       ↓
[Breath detection logic / UI update]

No getUserMedia. No AnalyserNode. No broken bridge. The audio never touches the WebView's audio graph.

The Swift core

@objc func startListening(_ call: CAPPluginCall) {
    let engine = AVAudioEngine()
    let inputNode = engine.inputNode
    let format = inputNode.outputFormat(forBus: 0)

    inputNode.installTap(onBus: 0, bufferSize: 1024, format: format) { [weak self] buffer, _ in
        guard let channelData = buffer.floatChannelData?[0] else { return }
        let frameCount = Int(buffer.frameLength)

        // Compute RMS
        var sum: Float = 0
        for i in 0..<frameCount {
            let sample = channelData[i]
            sum += sample * sample
        }
        let rms = sqrt(sum / Float(frameCount))

        self?.notifyListeners("audioLevel", data: ["rms": rms])
    }

    do {
        try engine.start()
        call.resolve()
    } catch {
        call.reject("Failed to start audio engine: \(error.localizedDescription)")
    }
}

AVAudioEngine handles all the session management, permission checking, and hardware configuration. The installTap callback runs on Apple's internal audio thread and fires every ~23ms at 44.1 kHz with a buffer size of 1024 frames — low enough latency for real-time biofeedback.

The TypeScript API

Install the plugin:

npm install @shiihaa/capacitor-audio-analysis
npx cap sync

Then use it:

import { AudioAnalysis } from '@shiihaa/capacitor-audio-analysis';

// Request microphone permission
await AudioAnalysis.requestPermission();

// Listen for audio level events
await AudioAnalysis.addListener('audioLevel', (data: { rms: number }) => {
  const level = data.rms; // 0.0 (silence) to ~0.5 (loud breathing)
  updateBreathCurve(level);
});

// Start capture
await AudioAnalysis.startListening();

// Stop when done
await AudioAnalysis.stopListening();
await AudioAnalysis.removeAllListeners();

The rms value is a floating-point number between 0.0 (complete silence) and roughly 0.3–0.5 for a loud inhale. We apply a short rolling window average in JavaScript and threshold-detect peaks for inhale/exhale phase segmentation.

On Android and web, the plugin gracefully falls back to the standard getUserMedia + AnalyserNode path — those platforms don't have the WKWebView limitation, so the native layer isn't needed.

The Result

After integrating the plugin, real-time breath detection on iOS worked immediately. The RMS signal from AVAudioEngine is clean, low-latency, and reliable across device generations from iPhone 8 to iPhone 16 Pro.

But we didn't stop at audio. shii·haa uses a three-signal approach for breath phase detection:

Signal 1 — Microphone energy (via this plugin): The RMS envelope of breathing sounds, filtered with a 300ms rolling average to smooth out noise transients.

Signal 2 — Heart rate variability via BLE: We connect to Garmin, Polar, and Wahoo chest straps over Bluetooth Low Energy and stream real-time R-R intervals. During inhalation, heart rate naturally accelerates; during exhalation, it decelerates. This is Respiratory Sinus Arrhythmia (RSA) — a well-characterized physiological coupling that can serve as an independent breath-phase signal, confirmed in published cardiorespiratory research.

Signal 3 — Threshold analysis: A configurable amplitude threshold that the user can calibrate to their breathing pattern and environment.

When all three signals agree on a phase transition, the biofeedback is accurate enough for clinical-grade guidance. This matters because shii·haa is designed by Dr. Felix Zeller — an intensive care physician and clinical psychologist — not just as a wellness app, but as a precision tool.

The biofeedback loop is now live: breathe in, watch the indicator climb, reach the target zone, shift to exhale. The app guides users through resonance frequency breathing (around 5–6 breath cycles per minute), the rhythm that maximally amplifies RSA and activates the parasympathetic nervous system. All of this running on a phone, with a chest strap, with sub-100ms feedback latency.

Open Source

We've open-sourced the plugin because this is a problem every Capacitor developer building audio analysis features on iOS will hit, and the existing workarounds are insufficient.

The plugin is MIT-licensed. Get it here:

npm: npmjs.com/package/@shiihaa/capacitor-audio-analysis
GitHub: github.com/shiihaa-app/capacitor-audio-analysis

Contributions welcome — especially:

Android native path: Currently falls back to Web Audio on Android, but a native AudioRecord-based path could improve latency
Additional metrics: Zero-crossing rate, spectral centroid, or other features for more sophisticated breath classification
Background audio support: Keeping the session alive when the app is backgrounded (requires UIBackgroundModes: audio in Info.plist)
Testing: Real-device testing across iOS versions — the WKWebView audio stack changes between releases

If you're building a meditation app, a voice analysis tool, a pitch detector, or anything else that needs real microphone data on iOS inside a Capacitor app, this plugin removes the biggest obstacle.

Dr. Felix Zeller is an intensive care physician, emergency doctor, and clinical psychologist based in Zürich. He built shii·haa — a breathwork and biofeedback app — with Perplexity Computer. Try it at shiihaa.app.