Synheart Session - Kotlin SDK - Synheart Documentation

Overview

The Synheart Session Kotlin SDK provides SynheartSession, a timer-driven session engine that buffers heart-rate samples from a BiosignalProvider, emits typed SessionEvents on a SharedFlow, and delivers a SessionSummary when the session ends. An optional BehaviorProvider adds behavioral signals to each frame. The bundled wrappers for synheart-wear and synheart-behavior use reflection, so those libraries are only needed at runtime. WatchSessionRelay runs a session on a companion Wear OS watch instead and streams the watch’s events back.

The SDK computes mean HR locally. HRV (hr_sdnn_ms, rmssd_ms, pnn50) is supplied by the host through ingestHsiMetrics() and is 0.0 until then.

Installation

Maven Central

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

kotlinx-coroutines-core is an api dependency, so Flow and SharedFlow are available to your code without adding it yourself.

Local Module

// settings.gradle
include ':synheart-session'
project(':synheart-session').projectDir = new File('../synheart-session-kotlin')

// build.gradle
dependencies {
    implementation project(':synheart-session')
}

Requirements

Android API 21+ (minSdk 21)
Java 17 bytecode
The library is built with Kotlin 2.3.0 and depends on kotlin-stdlib 2.3.0

Quick Start

Mock Mode (Development)

import ai.synheart.session.*
import android.util.Log
import androidx.lifecycle.lifecycleScope
import java.util.UUID
import kotlinx.coroutines.flow.transformWhile
import kotlinx.coroutines.launch

val session = SynheartSession() // MockBiosignalProvider by default

val config = SessionConfig(
    sessionId = UUID.randomUUID().toString(),
    mode = SessionMode.FOCUS,
    durationSec = 300,
    profile = ComputeProfile(windowSec = 60, emitIntervalSec = 5)
)

lifecycleScope.launch {
    session.startSession(config)
        // The SharedFlow never completes: stop after the terminal event.
        .transformWhile { event ->
            emit(event)
            event !is SessionSummary && event !is SessionErrorEvent
        }
        .collect { event ->
            when (event) {
                is SessionStarted -> Log.d("Session", "Started")
                is SessionFrame -> Log.d("Session", "HR: ${event.metrics["hr_mean_bpm"]} bpm")
                is BiosignalFrame -> Log.d("Session", "Raw samples: ${event.samples.size}")
                is SessionSummary -> Log.d("Session", "Complete: ${event.durationActualSec}s")
                is SessionErrorEvent -> Log.e("Session", "Error [${event.code.value}]: ${event.message}")
            }
        }
}

// Stop early (optional) — emits SessionSummary
session.stopSession(config.sessionId)

startSession returns a hot SharedFlow<SessionEvent> that replays up to 1024 events, so a collector that subscribes after the start still sees SessionStarted. The flow never completes on its own; end collection on SessionSummary or SessionErrorEvent (for example with transformWhile, as above).

Real BLE Heart Rate Data

import ai.synheart.session.*

// bleHrmProvider is a connected synheart-wear BleHrmProvider (passed as Any, read via reflection)
val provider = WearBiosignalProvider(bleHrmProvider)
val session = SynheartSession(provider)

val events = session.startSession(config)
// Same event handling — metrics are now computed from real HR data

If the BLE HRM is not connected when the session starts, the session emits a SessionErrorEvent with SENSOR_UNAVAILABLE and ends.

Health Connect Heart Rate Data

import ai.synheart.session.*

// healthConnectAdapter is an initialized synheart-wear HealthConnectAdapter
val provider = HealthConnectBiosignalProvider(healthConnectAdapter, context)

if (provider.isAvailable) {
    val session = SynheartSession(provider)
    val events = session.startSession(config)
}

The provider polls the adapter’s readSnapshot() every 2 seconds by default (pollIntervalMs). Each sample’s rr_intervals_ms is derived from BPM (60000 / bpm), not measured.

Session Configuration

val config = SessionConfig(
    sessionId = UUID.randomUUID().toString(),
    mode = SessionMode.FOCUS,        // FOCUS, BREATHING, or TYPING
    durationSec = 60,                // session duration in seconds
    profile = ComputeProfile(
        windowSec = 10,              // sliding window size
        emitIntervalSec = 3          // session frame interval
    )
)

SessionConfig

Parameter	Type	Required	Default	Description
`sessionId`	`String`	Yes	-	Unique session identifier
`mode`	`SessionMode`	Yes	-	`FOCUS`, `BREATHING`, or `TYPING`
`durationSec`	`Int`	Yes	-	Session duration in seconds
`profile`	`ComputeProfile`	No	60s/5s	Window and emit configuration
`windowLabel`	`String?`	No	`null`	Optional label for the session window
`includeRawSamples`	`Boolean`	No	`false`	Enable raw biosignal frames

ComputeProfile

Parameter	Type	Default	Description
`windowSec`	`Int`	60	Sliding window size in seconds
`emitIntervalSec`	`Int`	5	Session frame emission interval in seconds
`rawEmitIntervalSec`	`Int?`	`null`	Raw biosignal frame interval (defaults to `emitIntervalSec`)

Session Events

SessionEvent is a sealed class. Every subclass has sessionId and toMap(), which returns the snake_case wire map shared with the other SDKs.

SessionStarted

Emitted immediately by startSession.

Field	Type	Description
`sessionId`	`String`	Session identifier
`startedAtMs`	`Long`	Unix timestamp in milliseconds

SessionFrame

Emitted every emitIntervalSec while the window holds at least one sample (frames are skipped while it is empty).

is SessionFrame -> {
    val hr = event.metrics["hr_mean_bpm"] as? Double
    val rmssd = event.metrics["rmssd_ms"] as? Double  // 0.0 unless ingested
    val behavior = event.behavior                      // null without a BehaviorProvider
}

Field	Type	Description
`sessionId`	`String`	Session identifier
`seq`	`Int`	Frame sequence number (1-based)
`emittedAtMs`	`Long`	Unix timestamp in milliseconds
`metrics`	`Map<String, Any>`	Flat metrics (see below)
`behavior`	`Map<String, Any?>?`	Behavioral snapshot, when a `BehaviorProvider` returns one

metrics keys:

Key	Type	Description
`hr_mean_bpm`	`Double`	Mean heart rate (BPM), one decimal
`hr_sdnn_ms`	`Double`	From `ingestHsiMetrics` (`hrv.sdnn_ms`), else `0.0`
`rmssd_ms`	`Double`	From `ingestHsiMetrics` (`hrv.rmssd_ms`), else `0.0`
`pnn50`	`Double`	From `ingestHsiMetrics` (`hrv.pnn50`), else `0.0`
`sample_count`	`Int`	Number of HR samples in the window
`start_ms`	`Long`	First sample timestamp in the window (ms)
`end_ms`	`Long`	Last sample timestamp in the window (ms)

BiosignalFrame

Emitted every rawEmitIntervalSec when includeRawSamples = true and the window is not empty. seq is a separate counter from SessionFrame.seq.

is BiosignalFrame -> event.samples.forEach { sample ->
    val bpm = sample["bpm"] as? Double
    @Suppress("UNCHECKED_CAST")
    val rr = sample["rr_intervals_ms"] as? List<Double>  // plural, list of ms
    val source = sample["source"] as? String
}

Each sample map has timestamp_ms, bpm, source, and, when the provider supplies them, rr_intervals_ms and device_id.

SessionSummary

Emitted once when the duration elapses or stopSession is called.

Field	Type	Description
`sessionId`	`String`	Session identifier
`durationActualSec`	`Int`	Actual session duration in seconds
`metrics`	`Map<String, Any>`	Metrics over the final window (same keys as `SessionFrame`)
`behavior`	`Map<String, Any?>?`	Behavioral snapshot taken at the end

SessionErrorEvent

Emitted instead of a summary when the session ends abnormally — for example when the provider throws from startStreaming, which ends the session with SENSOR_UNAVAILABLE.

Field	Type	Description
`sessionId`	`String`	Session identifier
`code`	`SessionErrorCode`	Error code
`message`	`String`	Human-readable message

On the wire (toMap()), the code is under error_code. Error codes (SessionErrorCode):

Value	Wire string	Description
`PERMISSION_DENIED`	`permission_denied`	Health data permissions not granted
`SENSOR_UNAVAILABLE`	`sensor_unavailable`	Heart rate sensor not available
`INVALID_STATE`	`invalid_state`	Invalid session state
`LOW_BATTERY`	`low_battery`	Device battery too low
`OS_TERMINATED`	`os_terminated`	Operating system terminated the session

API misuse throws instead: startSession throws SessionError.InvalidState if any session is already running (whatever its id) or the instance is disposed, and stopSession throws it if no session is running or the id does not match. See Errors.

HRV Metrics

session.ingestHsiMetrics(config.sessionId, mapOf(
    "hrv.sdnn_ms" to 48.2,
    "hrv.rmssd_ms" to 36.5,
    "hrv.pnn50" to 14.0,
))

The latest map replaces the previous one and is used for every following frame and the summary. The call is a no-op after dispose() or when sessionId does not match the running session.

Behavioral Signals

SynheartSession accepts an optional BehaviorProvider. The engine pulls a snapshot at each frame and once more for the summary.

Mock Behavior (Development)

val session = SynheartSession(behaviorProvider = MockBehaviorProvider())

lifecycleScope.launch {
    session.startSession(config)
        .transformWhile { emit(it); it !is SessionSummary && it !is SessionErrorEvent }
        .collect { event ->
            if (event is SessionFrame) {
                Log.d("Session", "Stability: ${event.behavior?.get("stability_index")}")
            }
        }
}

Production (via synheart-behavior)

// Wrap a synheart-behavior SynheartBehavior instance (reflection-based)
val behaviorProvider = BehaviorSdkProvider(behaviorSdkInstance)
val session = SynheartSession(behaviorProvider = behaviorProvider)

BehaviorSdkProvider reports isAvailable from the SDK’s isInitialized() and reads getCurrentStats() at each frame. The behavior field is only present when a BehaviorProvider is configured, reports isAvailable, and returns a snapshot.

Companion Watch Sessions (Wear OS)

WatchSessionRelay drives a session on a paired Wear OS watch over the Wearable Data Layer. The watch’s companion app runs the session; the relay sends commands and decodes the watch’s events into SessionEvents. It is independent of SynheartSession. The Play Services libraries are compileOnly in the SDK, so a host that uses the relay must add them itself:

dependencies {
    implementation 'ai.synheart:synheart-session:0.4.0'
    implementation 'com.google.android.gms:play-services-wearable:18.2.0'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.7.3'
}

The relay uses await() from kotlinx-coroutines-play-services. Without play-services-wearable (or on a device without Google Play services), status() reports supported = false and startSession emits a SessionErrorEvent rather than crashing.

import ai.synheart.session.*
import kotlinx.coroutines.launch

val relay = WatchSessionRelay(context)

lifecycleScope.launch {
    val status = relay.status()
    if (!status.canStartSession) return@launch

    // Completes after the watch's SessionSummary or SessionErrorEvent.
    relay.startSession(config).collect { event ->
        when (event) {
            is SessionFrame -> Log.d("Watch", "HR: ${event.metrics["hr_mean_bpm"]}")
            is SessionErrorEvent -> Log.e("Watch", event.message)
            else -> Unit
        }
    }
}

// Later, from a coroutine:
// relay.stopSession(config.sessionId)

Member	Description
`suspend fun status(): WatchStatus`	Connectivity snapshot. Never throws
`fun startSession(config): Flow<SessionEvent>`	Sends `start_session` to every connected node and emits the watch’s events. Completes on the watch’s `SessionSummary` or `SessionErrorEvent`
`suspend fun stopSession(sessionId)`	Sends `stop_session`. Best-effort; the watch also stops on its own duration timer
`fun hrSamples(): Flow<WatchHrSample>`	Heart-rate readings the watch sends (`timestampMs`, `bpm`), independent of the session flow

startSession emits a SessionErrorEvent with SENSOR_UNAVAILABLE instead of throwing when Play Services is unavailable, when no node accepts the command, or when the watch sends nothing within 10 seconds. A node can accept the message while no app answers it — the Data Layer delivers only between apps with the same package name and signing certificate. WatchStatus has supported, reachable, paired, installed, and canStartSession (supported && reachable). Wear OS gives no separate paired/installed signal, so paired and installed track reachable. The message format is described in Watch Protocol.

Architecture

SynheartSession(provider: BiosignalProvider = MockBiosignalProvider(), behaviorProvider: BehaviorProvider? = null)
  |
  +-- BiosignalProvider                (interface, callback-based)
  |     +-- MockBiosignalProvider       (sinusoidal mock, 1 Hz)
  |     +-- WearBiosignalProvider       (wraps synheart-wear BleHrmProvider, reflection-based)
  |     +-- HealthConnectBiosignalProvider (wraps synheart-wear HealthConnectAdapter, reflection-based)
  |
  +-- BehaviorProvider                 (interface, pull-based)
  |     +-- MockBehaviorProvider        (stable mid-range values)
  |     +-- BehaviorSdkProvider         (wraps synheart-behavior, reflection-based)
  |
  +-- SampleRingBuffer           (thread-safe sliding window)
  +-- SessionError               (sealed exception class with 5 subclasses)

WatchSessionRelay(context)     (Wear OS companion sessions over the Wearable Data Layer)

Custom Provider

Any class implementing BiosignalProvider can drive the session:

class MyProvider : BiosignalProvider {
    override val isAvailable = true
    override val name = "my_source"

    override fun startStreaming(onSample: (BiosignalSample) -> Unit) {
        // Push samples into the callback, e.g.
        // onSample(BiosignalSample(timestampMs = now, bpm = 72.0, source = name))
    }

    override fun stopStreaming() { }
}

val session = SynheartSession(MyProvider())

API Reference

SynheartSession

Constructor	Description
`SynheartSession()`	Default `MockBiosignalProvider`, no behavior
`SynheartSession(provider)`	Custom biosignal provider
`SynheartSession(provider, behaviorProvider)`	Custom biosignal + behavioral providers
`SynheartSession(behaviorProvider = bp)`	Default mock biosignal + behavioral provider

Method	Description
`startSession(config): SharedFlow<SessionEvent>`	Start a session. Throws `SessionError.InvalidState` if a session is already running or the instance is disposed
`stopSession(sessionId)`	Stop the running session and emit `SessionSummary`. Throws `SessionError.InvalidState` if no session is running or the id does not match. No-op after `dispose()`
`getStatus(): SessionStatus?`	`SessionStatus(sessionId, active, lastSeq)`, or `null` if no session is running
`ingestHsiMetrics(sessionId, hsiMetrics)`	Supply HRV values for the running session
`dispose()`	Stop timers and the provider and release state. Later `startSession` calls throw

Resources

Repository: synheart-session-kotlin
Issues: GitHub Issues