> ## 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. # Synheart Session Overview > Real-time session capture with on-device HR metrics and behavioral signal fusion across phone and watch ## What is Synheart Session? Synheart Session is a real-time biometric session SDK that captures heart rate data from wearable sensors, computes session metrics on-device, and optionally fuses timing-based behavioral signals alongside HR data. It supports timed sessions with configurable modes, streaming session frames at regular intervals, and delivers a final session summary when complete. The watch runs `SessionEngine` locally, computes session frames with flat HR/HRV metrics (and optional motion metrics), and streams them back to the phone in real time via WatchConnectivity (iOS) or Wearable Data Layer (Android). When no watch is available, the SDK falls back to a local engine transparently. ## Key Features ### Session Lifecycle * **Configurable sessions**: Set mode (focus, breathing), duration, and compute profile * **Streaming session frames**: Receive periodic session frames with flat metrics during the session * **Session summary**: Get a final computation covering the full session duration * **Typed event stream**: `SessionStarted`, `SessionFrame`, `BiosignalFrame`, `SessionSummary`, `SessionError` * **Optional raw biosignal streaming**: Opt-in `includeRawSamples` for live HR trace, RR intervals, and accelerometer data * **Motion metrics on watch**: Watch companion apps stream per-frame `motion_rms_g` and `motion_sample_count` alongside HR metrics (iOS also includes `active_energy_kcal`) ### Pluggable Providers * **BiosignalProvider**: Pluggable HR source — mock (sinusoidal), BLE HRM (via synheart-wear), HealthKit, Health Connect * **BehaviorProvider**: Optional pull-based behavioral signal source — mock (stable mid-range values), synheart-behavior SDK (typing, scrolling, taps, app switches, idle gaps, stability/fragmentation indices) * **Backward compatible**: All providers are optional with sensible defaults — existing code works unchanged ### Phone-Watch Streaming * **WatchConnectivity relay**: Phone sends session commands to the watch via `WCSession` * **Watch-side engine**: SessionEngine runs on watchOS with direct sensor access * **Real-time streaming**: Session frames stream from watch to phone as they are computed * **Transparent fallback**: If the watch is not reachable, the SDK falls back to a local engine automatically ### Cross-Platform * **Flutter/Dart**: Cross-platform mobile SDK with mock and native modes * **Swift**: Native iOS and watchOS SDK with SessionEngine and pluggable providers * **Kotlin**: Native Android SDK with SessionEngine and reflection-based provider wrappers * **Mock mode**: Built-in mock engine for development and testing without hardware ## Architecture ```text theme={null} Flutter App (Dart) | startSession(config) v SynheartSessionPlugin (iOS native) | |-- Watch reachable? --> WatchSessionRelay | | WCSession.sendMessage | v | PhoneSessionRelay (watchOS) | | SessionEngine.start | v | Session frames stream back via WCSession | |-- Watch not reachable? --> Local SessionEngine (fallback) | v EventChannel --> Flutter Stream | v SessionStarted -> SessionFrame* (+ BiosignalFrame*) -> SessionSummary ``` ### Event Flow 1. You call `startSession(config)` which returns a `Stream` 2. The stream emits `SessionStarted` when the engine begins 3. `SessionFrame` events arrive at the configured `emitIntervalSec` 4. If `includeRawSamples: true`, `BiosignalFrame` events also arrive at `rawEmitIntervalSec` (defaults to `emitIntervalSec`) 5. When the session ends (duration elapsed or you call `stopSession`), a `SessionSummary` is emitted 6. The stream closes automatically after summary or error ## Session Modes | Mode | Description | | ----------- | ------------------------------------------------------------- | | `focus` | Steady-state measurement for attention and cognitive sessions | | `breathing` | Guided breathing sessions with HRV-focused computation | ## Compute Profile The `ComputeProfile` controls how often session frames are emitted and the window size for computation: | Parameter | Default | Description | | -------------------- | ------- | ------------------------------------------------------------------------------------------- | | `windowSec` | 60 | Size of the sliding window (seconds) for HR/HRV computation | | `emitIntervalSec` | 5 | How often to emit a session frame (seconds) | | `rawEmitIntervalSec` | `null` | How often to emit raw biosignal frames (seconds). Defaults to `emitIntervalSec` when `null` | ### Raw Biosignal Streaming When `includeRawSamples` is enabled in `SessionConfig`, the engine emits `BiosignalFrame` events alongside session frames. Each `BiosignalFrame` contains an array of `BiosignalSample` objects with: | Field | Type | Description | | --------------- | ------------ | ---------------------------------------- | | `timestampMs` | `int` | Unix timestamp in milliseconds | | `bpm` | `double` | Instantaneous heart rate in BPM | | `rrIntervalMs` | `double?` | Inter-beat (RR) interval in milliseconds | | `accelerometer` | `{x, y, z}?` | 3-axis accelerometer reading | | `spo2` | `double?` | SpO2 percentage (0-100) when available | This is useful for live HR trace display, RR interval visualization, and motion artifact detection. Session frames continue to emit normally — raw biosignal data is additive. ## Available SDKs ### Flutter SDK Cross-platform SDK for iOS and Android apps with mock mode for development. Supports optional `BehaviorProvider` in mock mode; in production, behavioral data flows from the native `SessionEngine` automatically. Flutter integration guide **Installation:** ```yaml theme={null} dependencies: synheart_session: ^0.2.0 ``` **Version**: 0.2.0 **Min OS**: iOS 13+ / Android API 21+ **Repository:** [synheart-session-flutter](https://github.com/synheart-ai/synheart-session-flutter) · [runnable example](https://github.com/synheart-ai/synheart-session-flutter/tree/main/example) ### Swift SDK Native Swift SDK for iOS and watchOS with SessionEngine, pluggable `BiosignalProvider` and `BehaviorProvider`. Swift and watchOS integration guide **Installation:** ```swift theme={null} .package(url: "https://github.com/synheart-ai/synheart-session-swift.git", from: "0.2.0") ``` **Version**: 0.2.0 **Min OS**: iOS 13.0+ / macOS 10.15+ / watchOS 6.0+ / tvOS 13.0+ **Repository:** [synheart-session-swift](https://github.com/synheart-ai/synheart-session-swift) ### Kotlin SDK Native Kotlin SDK for Android with SessionEngine, pluggable `BiosignalProvider` and `BehaviorProvider` (reflection-based wrappers). **Installation:** ```groovy theme={null} dependencies { implementation 'ai.synheart:synheart-session:0.2.0' } ``` **Version**: 0.2.0 **Min OS**: Android API 21+ (Android 5.0) **Repository:** [synheart-session-kotlin](https://github.com/synheart-ai/synheart-session-kotlin) ## Stability Synheart Session is **pre-1.0**. Minor version bumps may include breaking API changes — pin exact versions in production, and read the CHANGELOG before upgrading. The on-watch `SessionEngine` and the phone-side bridge are versioned together; check the watch protocol page if you're shipping a custom watch companion. ## Session Frame Structure Each `SessionFrame` contains a flat `metrics` dictionary with HR, HRV, and optional motion metrics. When a `BehaviorProvider` is configured, an optional `behavior` map is also included: ```json theme={null} { "type": "session_frame", "session_id": "abc-123", "seq": 1, "emitted_at_ms": 1700000030000, "metrics": { "hr_mean_bpm": 72.3, "hr_sdnn_ms": 45.12, "rmssd_ms": 36.10, "sample_count": 60, "start_ms": 1700000000000, "end_ms": 1700000060000, "motion_rms_g": 1.02, "motion_sample_count": 125, "active_energy_kcal": 12.5 } } ``` ### Frame Metrics | Key | Type | Platforms | Description | | --------------------- | -------- | --------- | ---------------------------------------------------------------- | | `hr_mean_bpm` | `double` | All | Mean heart rate in BPM over the window | | `hr_sdnn_ms` | `double` | All | Standard deviation of NN intervals (ms) | | `rmssd_ms` | `double` | All | Root mean square of successive RR differences (ms) | | `sample_count` | `int` | All | Number of HR samples in the window | | `start_ms` | `int` | All | Window start timestamp (ms since epoch) | | `end_ms` | `int` | All | Window end timestamp (ms since epoch) | | `motion_rms_g` | `double` | Watch | RMS acceleration magnitude in g-force (optional) | | `motion_sample_count` | `int` | Watch | Number of accelerometer samples in the frame interval (optional) | | `active_energy_kcal` | `double` | watchOS | Cumulative active energy burned in kcal (optional, iOS only) | `motion_rms_g` and `motion_sample_count` are present when the wearable has an accelerometer. `active_energy_kcal` is iOS-only (from `HKLiveWorkoutBuilder`). All motion/energy keys are optional — absent if the sensor is unavailable. ## Next Steps Flutter integration guide Swift and watchOS guide Android integration guide ## Community * **GitHub**: [github.com/synheart-ai](https://github.com/synheart-ai) — every Session SDK lives in its per-language repo (`synheart-session-flutter`, `synheart-session-kotlin`, `synheart-session-swift`). * **Issues**: file against the relevant per-language repo.