Respiro: A Contact-Free Android Biofeedback Companion Built with Presage SmartSpectra
What I Built
Most breathing and meditation apps are blind. They play a fixed rhythm at you and have no idea whether your nervous system is actually responding. Respiro checks.
Respiro is a native Android biofeedback companion built with Kotlin, Jetpack Compose, and the Presage SmartSpectra rPPG SDK. Instead of requiring a smartwatch, chest strap, or finger clip, it uses your phone's front-facing camera to measure arterial pulse rate and breathing rate directly from subtle facial micro-pulsations. It then feeds those live vitals into a closed-loop adaptive pacing engine that adjusts your breathing cadence in real time to guide you toward cardiovascular resonance (0.1 Hz, or roughly 6 breaths per minute).
Here is what happens during a session:
Contact-free sensing: CameraX streams front-camera frames at 30 FPS into the SmartSpectra SDK to extract pulse (BPM) and respiration (RPM) on the fly.
Closed-loop adaptive pacing: The app starts with a 20-second baseline intake, then smoothly ramps your breathing target down toward 6 BPM. If it detects an acute sympathetic surge (>= +8 BPM above baseline), it automatically shifts into a 2:1 exhale-to-inhale braking protocol to engage parasympathetic deceleration.
Real-time visual feedback: A dynamic breathing orb expands and contracts with your phase, six vertical capsule bars animate continuously on the dashboard hero card, and dual 30 Hz canvases render your arterial PPG waveform (including systolic peak and dicrotic notch) alongside your sinusoidal respiratory wave.
Autonomic telemetry: Live readouts track Pulse (BPM), Respiration (RPM), Heart Rate Variability (HRV RMSSD), Baevsky Stress Index, and a rolling Respiratory Sinus Arrhythmia (RSA) coherence score from 0% to 100%.
Four breathing protocols: Resonance 6 BPM, Adaptive, Box 4-4-4-4, and 4-7-8 Calming.
Built-in simulation fallback: If a user denies camera permission or wants to test in poor lighting, they can run the full physiological pipeline using a deterministic 30 Hz synthetic emitter with 4 stress scenarios.
Demo
Here is Respiro running live on a Samsung Galaxy S24 Ultra (Android 14 / One UI 6.1) with the front camera streaming live signals through SmartSpectra:
Direct video link: Watch the Respiro Demo on Vimeo
Source Code: github.com/lawal12345/Respiro
Release APK (v1.0.0): Download Respiro.apk
How I Used the Presage SmartSpectra SDK
Respiro integrates the official Android SmartSpectra SDK inside SmartSpectraLiveSource.kt (app/src/main/kotlin/com/presage/biofeedback/signal/SmartSpectraLiveSource.kt), initialized at startup in PresageBiofeedbackApp.kt.
The live pipeline works as follows:
Optical Capture (CameraX): Front-facing camera frames are captured at 30 FPS and routed via a CameraX SurfaceProvider to the SmartSpectra SDK. Ambient light penetrates the epidermis and is absorbed by oxygenated hemoglobin in facial capillaries; each cardiac stroke alters light reflection slightly.
Signal Extraction: SmartSpectra detects facial landmarks, selects regions of interest across the forehead and cheeks, isolates chrominance channels, filters optical noise, and emits real-time telemetry alongside signal quality states (OPTIMAL, TOO_DARK, NO_FACE).
Derived Autonomic Metrics: From the incoming pulse and respiration streams, Respiro's pure-Kotlin domain layer computes:
HRV RMSSD: Root Mean Square of Successive Differences between successive beat intervals to reflect immediate parasympathetic vagal tone.
Baevsky Stress Index: A geometric histogram calculation categorizing autonomic load (< 50 relaxed, 50-150 balanced/resonant, > 150 elevated sympathetic stress).
RSA Coherence (0-100%): A rolling mathematical correlation between the respiratory sine wave and instantaneous heart rate acceleration/deceleration.
Closed-Loop Pacing (AdaptiveBreathingEngine.kt): Rather than locking users into a static timer, the engine observes the first 20 seconds to establish a personal baseline, calculates continuous phase transitions via RespiratoryWaveformGenerator.kt, and triggers extended exhalations whenever a sympathetic pulse spike occurs.
Architecture and Engineering Highlights
Respiro follows Clean Architecture with an MVI/MVVM unidirectional state flow (SessionViewModel -> StateFlow). The entire domain/ package is pure Kotlin with zero Android or Firebase dependencies.
+-------------------------------------------------------------------+
| Presentation Layer (Jetpack Compose + Material 3) |
| Consent -> Mode Select -> Active Session -> Summary -> History |
+---------------------------------+---------------------------------+
| StateFlow / Intents
+---------------------------------v---------------------------------+
| ViewModel Layer (SessionViewModel, 30 Hz Waveform Buffers) |
+----------------+--------------------------------+-----------------+
| |
+----------------v--------------+ +---------------v-----------------+
| Domain Layer (Pure Kotlin) | | Data Layer (4-Tier Persistence) |
| - AdaptiveBreathingEngine | | 1. InMemorySessionRepository |
| - RespiratoryWaveformGenerator| | 2. Local Disk JSON Cache |
| - BiofeedbackMetrics / HRV | | 3. Firebase RTDB (2.5s timeout) |
+----------------+--------------+ | 4. Cloud Firestore (< 10 KB) |
| +---------------------------------+
+----------------v--------------+
| Signal Sources |
| - SmartSpectraLiveSource |
| - SimulatedSignalEmitter |
+-------------------------------+
4-Tier Offline-First Persistence
Biofeedback sessions should never hang on a spinning loader when a phone is offline. CompositeSessionRepository layers four storage tiers:
In-Memory Reactive Cache: Shared StateFlow for zero-latency UI updates across screens.
Local Disk Storage: Private internal JSON (cached_sessions.json) that survives app kills, reboots, and airplane mode.
Firebase Realtime Database: Non-blocking sync wrapped in withTimeoutOrNull(2500L) so an unreachable backend never blocks the UI.
Cloud Firestore: Structured longitudinal history with SnapshotDownsampler, which clamps embedded time-series arrays to <= 100 data points so every document stays strictly under 10 KB.
Testing and Hardware Verification
To keep the math and edge cases solid, I built a standalone JVM test harness (test_harness/runner.jar) that runs 61 automated tests across 10 suites covering resonance math, Baevsky index thresholds, sympathetic surge braking, downsampling limits, and offline fallback flows (61/61 passing).
Because offline JVM tests only prove that the logic and simulated signals work, I also built the release APK and verified the live CameraX + SmartSpectra integration physically on a Samsung Galaxy S24 Ultra (Android 14, API 34) via ADB, confirming smooth 60 FPS Compose rendering, live rPPG streaming, and zero crashes or ANRs.
Consent, Privacy, and Data Handling
Physiological camera apps require clear boundaries and user control. Respiro enforces the following guardrails:
Explicit first-launch consent: Before the camera ever activates, ConsentScreen.kt presents a clear non-medical wellness disclaimer (Respiro is for relaxation and general wellness, not clinical diagnosis or treatment) and explains how camera frames are used.
Zero video or biometric retention: Raw camera frames and video buffers are processed strictly in memory for real-time signal extraction. No video or images are ever written to disk, cached, or uploaded. No video exists after the session, period.
Graceful permission denial: Say no to the camera and you still get full access to the Simulation Demo mode with no nagging loops.
Database-level ethical guardrails: Every saved SessionDocument requires disclaimerAcknowledged == true, which is enforced declaratively in firestore.rules alongside strict per-user tenancy rules. Only aggregate session summaries and downsampled numeric curves (< 10 KB) are stored, and users can delete any past session from local disk and cloud simultaneously.
SDK telemetry note: Respiro itself does not collect third-party analytics or ad tracking. For details on standard licensing and operational telemetry handled by the underlying SmartSpectra Android SDK, please refer to the official Presage Technologies documentation and privacy policy.
Setup and Running Locally
Prerequisites
Android Studio (Ladybug or newer) with JDK 17+
Android device running Android 9.0+ (minSdk 28, targetSdk 35)
A Presage SmartSpectra API key from the Presage developer portal
Build and Install
Clone the repository:
git clone github.com/lawal12345/R…
cd Respiro
Configure your Presage API key in your local environment / build configuration as documented in the repository README.md (no API keys are committed to the repo).
Connect an Android device with USB debugging enabled and build/install:
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
Or install the pre-built release artifact (Respiro.apk) from the v1.0.0 release page.
Optional: run the 61-test JVM verification suite:
java -jar test_harness/runner.jar
What I Learned
Building a real-time camera biofeedback app on mobile taught me two big lessons:
Camera stability and UX feedback matter as much as the math. rPPG works well on a modern phone camera like the S24 Ultra, but ambient lighting and face framing make or break signal quality. Adding an immediate quality status pill (OPTIMAL, TOO_DARK, NO_FACE) made a huge difference in helping users get a clean lock within seconds.
Keep live signals local and persistence resilient. Streaming 30 Hz physiological waveforms to a cloud database is a recipe for latency and battery drain. Separating the real-time in-memory DSP pipeline from the 4-tier offline-first summary repository kept the UI locked at 60 FPS even with spotty connectivity.
## Prize Categories
**Best Thoughtful Real-World Use**
Most people who want biofeedback for stress or focus hit a wall: either spend hundreds of dollars on a smartwatch or chest strap, or settle for a generic breathing timer that has no idea whether their heart rate is actually coming down. Respiro removes the hardware barrier by turning the front-facing camera on a phone they already own into a closed-loop autonomic pacing tool.
It is built for everyday people dealing with acute stress, study burnout, or high-pressure workdays who need a quick, practical way to down-regulate without extra gear or friction. Every design choice was made around real-world usability:
* **Works offline without stalling:** Sessions save instantly to local disk (`cached_sessions.json`) and sync to Firebase in the background with a 2.5-second timeout, so a weak connection never freezes the app or loses a session.
* **Immediate camera guidance:** Because ambient lighting and framing make or break rPPG readings, a live quality pill (`OPTIMAL`, `TOO_DARK`, `NO_FACE`) tells users how to adjust in seconds instead of failing silently.
* **Respects user boundaries:** If someone does not want to grant camera access, or is in a dark room, they can still run the full pacing experience via Simulation Demo mode with zero nagging loops.
* **Lightweight footprint:** Time-series data is downsampled to <= 100 points (< 10 KB per session) before cloud sync, keeping data usage and storage minimal.