Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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):
FieldRangeMeaning
peakHz / peakBpmHz / BPMDetected breathing peak frequency (peakBpm = peakHz * 60)
coherence0..1Peak power / total power in the 0.04–0.26 Hz band
rsaBpmBPMMean per-cycle HR_max − HR_min — depth of breath
relativePower0..1Peak power as a fraction of total breathing-band power
criteriaMet0..4Number of pillars passed
confidence0..1Mean of normalized pillar scores

​
NonComplianceReason

Structured reason types — render coaching copy from these instead of free-text from the engine:
ReasonWhen 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
NoBreathingSignatureDetector 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

ReasonWhen 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:
ProfileUse
Beginner (default)First-time users; permissive thresholds, gives wins early
ExperiencedReturning users with technique; tighter coherence + RSA cutoffs
ClinicalResearch / 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