Synheart Session Overview - Synheart Documentation

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

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<SessionEvent>
    |
    v
SessionStarted -> SessionFrame* (+ BiosignalFrame*) -> SessionSummary

Event Flow

You call startSession(config) which returns a Stream<SessionEvent>
The stream emits SessionStarted when the engine begins
SessionFrame events arrive at the configured emitIntervalSec
If includeRawSamples: true, BiosignalFrame events also arrive at rawEmitIntervalSec (defaults to emitIntervalSec)
When the session ends (duration elapsed or you call stopSession), a SessionSummary is emitted
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 SDK Documentation

Flutter integration guide

Installation:

dependencies:
  synheart_session: ^0.2.0

Version: 0.2.0 Min OS: iOS 13+ / Android API 21+ Repository: synheart-session-flutter · runnable example

Swift SDK

Native Swift SDK for iOS and watchOS with SessionEngine, pluggable BiosignalProvider and BehaviorProvider.

Swift SDK Documentation

Swift and watchOS integration guide

Installation:

.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

Kotlin SDK

Native Kotlin SDK for Android with SessionEngine, pluggable BiosignalProvider and BehaviorProvider (reflection-based wrappers). Installation:

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

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:

{
  "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 SDK

Flutter integration guide

Swift SDK

Swift and watchOS guide

Kotlin SDK

Android integration guide

Community

GitHub: 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.

​What is Synheart Session?

​Key Features

​Session Lifecycle

​Pluggable Providers

​Phone-Watch Streaming

​Cross-Platform

​Architecture

​Event Flow

​Session Modes

​Compute Profile

​Raw Biosignal Streaming

​Available SDKs

​Flutter SDK

Flutter SDK Documentation

​Swift SDK

Swift SDK Documentation

​Kotlin SDK

​Stability

​Session Frame Structure

​Frame Metrics

​Next Steps

Flutter SDK

Swift SDK

Kotlin SDK

​Community

What is Synheart Session?

Key Features

Session Lifecycle

Pluggable Providers

Phone-Watch Streaming

Cross-Platform

Architecture

Event Flow

Session Modes

Compute Profile

Raw Biosignal Streaming

Available SDKs

Flutter SDK

Swift SDK

Kotlin SDK

Stability

Session Frame Structure

Frame Metrics

Next Steps

Community