Synheart Session Overview - Synheart Documentation

What is Synheart Session?

Synheart Session is an SDK for running timed biometric sessions. A session buffers heart-rate samples from a pluggable BiosignalProvider in a sliding window, emits a SessionFrame with flat metrics at a fixed interval, and delivers a SessionSummary when the session ends. A BehaviorProvider can add timing-based behavioral signals to each frame. The SDK computes mean heart rate on-device. It does not compute HRV: hr_sdnn_ms, rmssd_ms, and pnn50 come from the host through ingestHsiMetrics() (typically from the Synheart runtime) and are 0.0 until the host supplies them. For real-time data from a smartwatch, Synheart’s companion watch apps (watchOS and Wear OS) run the session on the watch and stream events to the phone. The phone SDKs relay start/stop commands and receive those events. There is no automatic fallback to a phone-side source: if no watch is reachable, the session gets no heart-rate data. See Lifecycle.

Key Features

Session Lifecycle

Configurable sessions: Set mode (focus, breathing, typing), duration, and compute profile
Streaming session frames: Periodic frames with flat metrics during the session
Session summary: A final frame computed when the session ends
Typed event stream: SessionStarted, SessionFrame, BiosignalFrame, SessionSummary, SessionError
Optional raw biosignal streaming: Opt-in includeRawSamples for a live HR trace

Pluggable Providers

BiosignalProvider: HR source — mock (sinusoidal), BLE HRM and Health Connect (Kotlin, via synheart-wear), HealthKit and BLE HRM (Swift, via synheart-wear), companion watch (Flutter)
BehaviorProvider: Optional pull-based behavioral source — mock, or synheart-behavior (bundled wrapper in Kotlin and Swift)
Providers are constructor arguments of SynheartSession and are optional; the Kotlin and Swift default biosignal provider is the mock

Phone-Watch Streaming

Flutter: pass a WatchBiosignalProvider and the SDK sends start/stop commands to the companion app on Apple Watch (WatchConnectivity) or Wear OS (Wearable Data Layer)
Kotlin: WatchSessionRelay drives a session on a Wear OS watch and returns the watch’s events as a Flow<SessionEvent>
Swift: the Swift SDK runs sessions on the device it is linked into (including watchOS); it does not include a phone-side relay

Cross-Platform

Flutter/Dart: SynheartSession() (live) and SynheartSession.mock() (simulated)
Kotlin: SynheartSession returning a SharedFlow<SessionEvent>
Swift: SynheartSession returning an AsyncStream<SessionEvent>
Wire format: every SDK serializes events to the same snake_case map (toJson() / toMap() / toDictionary())

Architecture

Host app
    | startSession(config)
    v
SynheartSession
    |-- BiosignalProvider --> samples --> sliding window (windowSec)
    |-- BehaviorProvider  --> snapshot pulled at each frame
    |-- ingestHsiMetrics() --> HRV values from the host
    v
Stream of SessionEvent
    SessionStarted -> SessionFrame* (+ BiosignalFrame*) -> SessionSummary

With a companion watch, the session on the watch produces the events and the phone receives them:

Phone                                  Watch companion app
  start_session (JSON command)  --->     runs the session
  <--- session events (JSON)             session_started, session_frame, ...
  stop_session (JSON command)   --->     emits session_summary

See Watch Protocol for the message format.

Event Flow

You call startSession(config), which returns a stream of SessionEvents
SessionStarted is emitted immediately
SessionFrame events arrive every emitIntervalSec
If includeRawSamples is true, BiosignalFrame events also arrive every rawEmitIntervalSec (defaults to emitIntervalSec) — Kotlin, Swift, and the Flutter mock engine
When the duration elapses or you call stopSession, a SessionSummary is emitted
The Flutter stream and the Swift stream finish after the summary. The Kotlin SharedFlow never completes, so stop collecting on SessionSummary or SessionErrorEvent

Session Modes

Mode	Description
`focus`	Focus or attention session
`breathing`	Breathing session
`typing`	Typing session: the host brackets a keyboard lifecycle with a watch session

The phone-side engines compute the same metrics in every mode. The mode is carried in the config and forwarded to the watch in the start_session command.

Compute Profile

The ComputeProfile controls the window size and how often frames are emitted:

Parameter	Default	Description
`windowSec`	60	Size of the sliding window (seconds) for mean HR
`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 Kotlin and Swift engines and the Flutter mock engine emit BiosignalFrame events alongside session frames. The Flutter live engine does not emit BiosignalFrame. Kotlin and Swift samples are maps with these keys:

Key	Type	Description
`timestamp_ms`	`Long` / `Int64`	Unix timestamp in milliseconds
`bpm`	`Double`	Heart rate in BPM
`source`	`String`	Provider tag (`mock`, `ble_hrm`, `health_connect`, `apple_healthkit`, …)
`rr_intervals_ms`	`List<Double>?`	RR intervals in milliseconds, when the provider supplies them
`device_id`	`String?`	Source device, when the provider supplies it

In Dart, BiosignalFrame.samples is a List<BiosignalSample> with timestampMs, bpm, rrIntervalMs, accelerometer, and spo2. The mock engine fills accelerometer with synthetic values.

Available SDKs

Flutter SDK

Cross-platform SDK for iOS and Android with a mock mode for development.

Flutter SDK Documentation

Flutter integration guide

Installation:

dependencies:
  synheart_session: ^0.3.0

Version: 0.3.0 Requirements: Dart >=3.8.0 <4.0.0, Flutter >=3.22.0 Repository: synheart-session-flutter · runnable example

Swift SDK

Native Swift SDK with SynheartSession and 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.3.0")

Version: 0.3.0 Platforms (Swift Package Manager): iOS 13.0+ / macOS 13.0+ / watchOS 8.0+ Repository: synheart-session-swift

Kotlin SDK

Native Kotlin SDK for Android with SynheartSession, pluggable providers (reflection-based wrappers for synheart-wear and synheart-behavior), and WatchSessionRelay for Wear OS.

Kotlin SDK Documentation

Android integration guide

Installation:

dependencies {
    implementation 'ai.synheart:synheart-session:0.4.0'
}

Version: 0.4.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. Kotlin 0.4.0 and Swift 0.3.0 are minor bumps because the new typing mode breaks exhaustive when / switch statements over SessionMode.

Session Frame Structure

Each SessionFrame carries a flat metrics map. When a BehaviorProvider is configured and returns a snapshot, a behavior map is included too:

{
  "type": "session_frame",
  "session_id": "abc-123",
  "seq": 1,
  "emitted_at_ms": 1700000030000,
  "metrics": {
    "hr_mean_bpm": 72.3,
    "hr_sdnn_ms": 0.0,
    "rmssd_ms": 0.0,
    "pnn50": 0.0,
    "sample_count": 30,
    "start_ms": 1700000000000,
    "end_ms": 1700000029000
  }
}

Frame Metrics

Key	Type	Description
`hr_mean_bpm`	`double`	Mean heart rate in BPM over the window, rounded to one decimal
`hr_sdnn_ms`	`double`	SDNN (ms), from `ingestHsiMetrics` key `hrv.sdnn_ms`; `0.0` if not supplied
`rmssd_ms`	`double`	RMSSD (ms), from `ingestHsiMetrics` key `hrv.rmssd_ms`; `0.0` if not supplied
`pnn50`	`double`	pNN50, from `ingestHsiMetrics` key `hrv.pnn50`; `0.0` if not supplied
`sample_count`	`int`	Number of HR samples in the window
`start_ms`	`int`	Timestamp of the first sample in the window (ms since epoch)
`end_ms`	`int`	Timestamp of the last sample in the window (ms since epoch)

Platform differences:

Flutter also puts session_id, mode, and seq inside metrics. The Flutter live engine emits frames even when the window is empty (sample_count 0, hr_mean_bpm 0.0).
Flutter mock engine emits synthetic hr_sdnn_ms and rmssd_ms derived from its generated data, adds "mock": true, and does not emit pnn50.
Kotlin and Swift skip a frame when the window holds no samples.

Events relayed from a companion watch app can include extra metric keys that the watch app adds. The phone SDKs do not produce them.

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.