Breathing module

Overview

The Breathing module wraps the runtime’s breathing-compliance detector. Every R-R interval pushed via CoreRuntimeBridge.pushRr (raw beat data from BLE chest straps and equivalent sources) automatically feeds the detector — this module only configures the target rate / population / window and reads back the verdict. A “compliance” verdict has four pillars (peak frequency match, coherence, RSA amplitude, relative power) and a confidence score in [0, 1]. The detector returns one of three verdicts:

Compliant — user is meeting the target; metrics included
NotCompliant — user is breathing but off-target; reason explains why (frequency, depth, regularity, no breathing signature) — feed into coaching copy
Insufficient — not enough raw R-R data yet; reason explains what’s missing

Configuration

// Kotlin
val breathing = BreathingModule(bridge = coreRuntime)
breathing.setTargetBpm(6.0)                            // resonance breathing
breathing.setWindowSecs(60)                            // 30–120s clamp
breathing.setPopulation(BreathingPopulation.BEGINNER)  // / EXPERIENCED / CLINICAL
breathing.reset()                                      // call before a new exercise

// Swift
let breathing = BreathingModule(bridge: coreRuntime)
breathing.setTargetBpm(6.0)
breathing.setWindowSecs(60)
breathing.setPopulation(.beginner)  // / .experienced / .clinical
breathing.reset()

Evaluate

Call once per UI frame (or at whatever cadence you render coaching):

// Kotlin
when (val v = breathing.evaluate()) {
    is BreathingComplianceResult.Compliant -> showCompliant(v.metrics)
    is BreathingComplianceResult.NotCompliant ->
        showCoaching(BreathingGuidanceCopy.copyFor(v.reason))
    is BreathingComplianceResult.Insufficient -> showWarming(v.reason)
}

// Swift
switch breathing.evaluate() {
case let .compliant(metrics):
    showCompliant(metrics)
case let .notCompliant(_, reason):
    showCoaching(BreathingGuidanceCopy.copyFor(reason))
case let .insufficient(reason):
    showWarming(reason)
}

Metrics

BreathingMetrics (present on Compliant / NotCompliant, nil on Insufficient):

Field	Range	Meaning
`peakHz` / `peakBpm`	Hz / BPM	Detected breathing peak frequency (`peakBpm = peakHz * 60`)
`coherence`	0..1	Peak power / total power in the 0.04–0.26 Hz band
`rsaBpm`	BPM	Mean per-cycle `HR_max − HR_min` — depth of breath
`relativePower`	0..1	Peak power as a fraction of total breathing-band power
`criteriaMet`	0..4	Number of pillars passed
`confidence`	0..1	Mean of normalized pillar scores

NonComplianceReason

Structured reason types — render coaching copy from these instead of free-text from the engine:

Reason	When fired
`WrongFrequency(detectedBpm, targetBpm)`	Cycle frequency missed the target band
`ShallowBreathing(rsaBpm)`	Rhythm is right, RSA too low — breaths aren’t deep enough
`IrregularPattern(coherence)`	Coherence below threshold — uneven cadence
`NoBreathingSignature`	Detector can’t find a respiratory rhythm in the RR signal

BreathingGuidanceCopy.localize is a swappable function for the default English coaching strings — override globally to ship in a different language or tone.

InsufficientReason

Reason	When fired
`NotEnoughBeats(have, need)`	Fewer than `need` (default 50) R-R samples buffered
`WindowTooShort(haveSecs, needSecs)`	Window hasn’t reached the configured length yet
`VendorOnlyTier(device)`	Source provides only summary metrics (no raw R-R intervals) — the detector needs raw beat data
`ExcessiveArtifacts(rejectedPct)`	Too many RR samples failed artifact filtering (motion, missed beats)

Population profile

Adjusts the per-pillar thresholds:

Profile	Use
`Beginner` (default)	First-time users; permissive thresholds, gives wins early
`Experienced`	Returning users with technique; tighter coherence + RSA cutoffs
`Clinical`	Research / clinical settings; strictest thresholds

Cross-language parity

Identical wire format across Flutter / Kotlin / Swift:

Flutter: lib/src/modules/breathing/{breathing_module,breathing_compliance_result,breathing_guidance_copy}.dart
Kotlin: synheart-core/src/main/kotlin/ai/synheart/core/modules/breathing/{BreathingModule,BreathingComplianceResult,BreathingGuidanceCopy}.kt
Swift: SynheartCore/Modules/Breathing/{BreathingModule,BreathingComplianceResult,BreathingGuidanceCopy}.swift

Synheart Core overview
Baselines — the same RR stream feeds longitudinal baselines

Get Started

Setup

CLI

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

Overview

Configuration

Evaluate

Metrics

NonComplianceReason

InsufficientReason

Population profile

Cross-language parity

​Overview

​Configuration

​Evaluate

​Metrics

​NonComplianceReason

​InsufficientReason

​Population profile

​Cross-language parity

​Related

Overview

Configuration

Evaluate

Metrics

NonComplianceReason

InsufficientReason

Population profile

Cross-language parity

Related