Synheart Session - Swift SDK - Synheart Documentation

Overview

The Synheart Session Swift SDK provides SynheartSession, a timer-driven session engine that buffers heart-rate samples from a BiosignalProvider, emits typed SessionEvents on an AsyncStream, and delivers a .sessionSummary when the session ends. An optional BehaviorProvider adds behavioral signals to each frame. It runs on iOS, macOS, and watchOS.

The SDK computes mean HR locally from sampled biosignals. HRV (rmssd_ms, hr_sdnn_ms, pnn50) is produced upstream (typically by the Synheart runtime) and supplied with ingestHsiMetrics(sessionId:hsiMetrics:). Without that call, HRV fields are 0.0.

Installation

Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/synheart-ai/synheart-session-swift.git", from: "0.3.0")
]

Or in Xcode:

File > Add Packages…
Enter: https://github.com/synheart-ai/synheart-session-swift.git

The package has four library products:

Product	Contents
`SynheartSession`	Core engine, types, mock providers (no external dependencies)
`SynheartSessionWear`	`WearBiosignalProvider` (BLE heart-rate monitor via synheart-wear-swift)
`SynheartSessionHealthKit`	`HealthKitBiosignalProvider` (HealthKit via synheart-wear-swift)
`SynheartSessionBehavior`	`BehaviorSdkProvider` (synheart-behavior-swift)

Requirements

iOS 13.0+ / macOS 13.0+ / watchOS 8.0+
Swift 5.9+ (swift-tools-version 5.9)

Quick Start

import SynheartSession

let session = SynheartSession() // MockBiosignalProvider by default

let config = SessionConfig(
    sessionId: UUID().uuidString,
    mode: .focus,
    durationSec: 30,
    profile: ComputeProfile(windowSec: 10, emitIntervalSec: 3)
)

let events = try session.startSession(config: config)

Task {
    for await event in events {
        switch event {
        case .sessionStarted(_, let startedAtMs):
            print("Session started at \(startedAtMs)")
        case .sessionFrame(_, let seq, _, let metrics, _):
            let hr = metrics["hr_mean_bpm"] as? Double ?? 0
            print("#\(seq) HR: \(hr) bpm")
        case .biosignalFrame(_, _, _, let samples):
            print("Raw samples: \(samples.count)")
        case .sessionSummary(_, let durationActualSec, _, _):
            print("Session complete: \(durationActualSec)s")
        case .sessionError(_, let code, let message):
            print("Error [\(code.rawValue)]: \(message)")
        }
    }
    // The stream finishes after .sessionSummary or .sessionError.
}

// Stop early — emits .sessionSummary
try session.stopSession(sessionId: config.sessionId)

The stream buffers events emitted before you start iterating, so .sessionStarted is not lost. The engine schedules its timers on RunLoop.main, and MockBiosignalProvider schedules its timer on the current run loop, so start sessions from the main thread.

Types

SessionConfig

let config = SessionConfig(
    sessionId: UUID().uuidString,      // unique session identifier
    mode: .focus,                       // .focus, .breathing, or .typing
    durationSec: 60,                   // session duration in seconds
    profile: ComputeProfile(
        windowSec: 10,                 // sliding window size
        emitIntervalSec: 3             // frame emission interval
    ),
    windowLabel: "morning-check"       // optional label
)

Set includeRawSamples: true to emit .biosignalFrame events alongside session frames:

let config = SessionConfig(
    sessionId: UUID().uuidString,
    mode: .focus,
    durationSec: 60,
    profile: ComputeProfile(windowSec: 10, emitIntervalSec: 3, rawEmitIntervalSec: 1),
    includeRawSamples: true
)

You can also create a SessionConfig from a dictionary, for example a start_session command received over WatchConnectivity:

let config = try SessionConfig(from: [
    "session_id": "abc-123",
    "mode": "focus",
    "duration_sec": 30,
    "profile": ["window_sec": 10, "emit_interval_sec": 3]
])

It throws SessionError.invalidState if session_id, mode, or duration_sec is missing or the mode is unknown.

SessionMode

Value	Raw	Description
`.focus`	`"focus"`	Focus session
`.breathing`	`"breathing"`	Breathing session
`.typing`	`"typing"`	Typing session: the host brackets a keyboard lifecycle with a watch session

ComputeProfile

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

SessionError

SessionError is the error type thrown by the API. Each case carries a String message; code returns the matching SessionErrorCode.

Case	`SessionErrorCode`	Raw	Description
`.permissionDenied(String)`	`.permissionDenied`	`"permission_denied"`	Health data permissions not granted
`.sensorUnavailable(String)`	`.sensorUnavailable`	`"sensor_unavailable"`	Sensor not available
`.invalidState(String)`	`.invalidState`	`"invalid_state"`	Invalid engine state
`.lowBattery(String)`	`.lowBattery`	`"low_battery"`	Device battery too low
`.osTerminated(String)`	`.osTerminated`	`"os_terminated"`	OS terminated the session

Session Events

SessionEvent is an enum. Every case exposes sessionId, and toDictionary() returns the snake_case wire dictionary shared with the other SDKs.

Case	Associated values
`.sessionStarted`	`sessionId`, `startedAtMs: Int64`
`.sessionFrame`	`sessionId`, `seq: Int`, `emittedAtMs: Int64`, `metrics: [String: Any]`, `behavior: [String: Any]?`
`.biosignalFrame`	`sessionId`, `seq: Int`, `emittedAtMs: Int64`, `samples: [[String: Any]]`
`.sessionSummary`	`sessionId`, `durationActualSec: Int`, `metrics: [String: Any]`, `behavior: [String: Any]?`
`.sessionError`	`sessionId`, `code: SessionErrorCode`, `message: String`

session_frame

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

["type": "session_frame", "session_id": "...", "seq": 1,
 "emitted_at_ms": 1700000003000,
 "metrics": [
    "hr_mean_bpm": 72.3,
    "hr_sdnn_ms": 0.0,      // from ingestHsiMetrics, else 0.0
    "rmssd_ms": 0.0,        // from ingestHsiMetrics, else 0.0
    "pnn50": 0.0,           // from ingestHsiMetrics, else 0.0
    "sample_count": 10,
    "start_ms": 1700000000000,
    "end_ms": 1700000009000
 ]]

hr_mean_bpm is rounded to one decimal. behavior is added when a BehaviorProvider is configured, reports isAvailable, and returns a snapshot.

biosignal_frame

Emitted every rawEmitIntervalSec when includeRawSamples is true and the window is not empty. Its seq is a separate counter from the session frame seq. Each sample has timestamp_ms, bpm, source, and, when the provider supplies them, rr_intervals_ms and device_id:

["type": "biosignal_frame", "session_id": "...", "seq": 1,
 "emitted_at_ms": 1700000003000,
 "samples": [
    ["timestamp_ms": 1700000002000, "bpm": 72.3,
     "source": "mock", "rr_intervals_ms": [829.9]],
    ...
 ]]

session_summary

["type": "session_summary", "session_id": "...",
 "duration_actual_sec": 30, "metrics": ["hr_mean_bpm": 72.3, ...]]

session_error

Emitted instead of a summary when the provider throws from startStreaming (for example WearBiosignalProvider with no connected HRM); the code is .sensorUnavailable and the stream finishes. On the wire the code is under error_code:

["type": "session_error", "session_id": "...",
 "error_code": "sensor_unavailable", "message": "..."]

Providers

BLE Heart Rate Monitor

import SynheartSession
import SynheartSessionWear
import SynheartWear

let bleHrm = BleHrmProvider()
let devices = try await bleHrm.scan(timeoutMs: 10000)
try await bleHrm.connect(deviceId: devices.first!.deviceId)

let session = SynheartSession(provider: WearBiosignalProvider(bleHrmProvider: bleHrm))

HealthKit

import SynheartSession
import SynheartSessionHealthKit
import SynheartWear

let wear = SynheartWear(config: SynheartWearConfig(enabledAdapters: [.platformHealth]))
try await wear.initialize()

let session = SynheartSession(provider: HealthKitBiosignalProvider(wear: wear))

Initialize the SynheartWear instance before passing it in. The provider subscribes to streamHR(interval: 1.0); when a reading has no RR intervals, it derives one from BPM (60000 / bpm).

HRV Metrics

session.ingestHsiMetrics(sessionId: config.sessionId, hsiMetrics: [
    "hrv.sdnn_ms": 48.2,
    "hrv.rmssd_ms": 36.5,
    "hrv.pnn50": 14.0,
])

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

WatchOS Integration

The Swift SDK runs on Apple Watch. A watch app can receive commands from the phone over WatchConnectivity and run SynheartSession locally. The relay below is an example you write in your watch app, not part of the SDK:

Watch-Side Relay

import WatchConnectivity
import SynheartSession

class PhoneSessionRelay: NSObject, WCSessionDelegate {
    // Pass your HR provider, e.g. HealthKitBiosignalProvider(wear:)
    private let engine = SynheartSession()

    override init() {
        super.init()
        guard WCSession.isSupported() else { return }
        WCSession.default.delegate = self
        WCSession.default.activate()
    }

    func session(_ session: WCSession,
                 didReceiveMessage message: [String: Any]) {
        DispatchQueue.main.async { self.handle(message) }
    }

    private func handle(_ message: [String: Any]) {
        guard let command = message["command"] as? String else { return }

        switch command {
        case "start_session":
            do {
                let config = try SessionConfig(from: message)
                let events = try engine.startSession(config: config)
                Task {
                    for await event in events {
                        self.sendToPhone(event.toDictionary())
                    }
                }
            } catch {
                // Report the failure to the phone
            }

        case "stop_session":
            if let sessionId = message["session_id"] as? String {
                try? engine.stopSession(sessionId: sessionId)
            }

        default: break
        }
    }

    private func sendToPhone(_ event: [String: Any]) {
        guard WCSession.default.isReachable else { return }
        WCSession.default.sendMessage(event, replyHandler: nil)
    }

    // Required delegate method
    func session(_ session: WCSession,
                 activationDidCompleteWith state: WCSessionActivationState,
                 error: Error?) {}
}

Phone Side

The Swift SDK does not include a phone-side relay. A native iOS app that drives a watch session sends the start_session / stop_session commands itself and decodes the returned event dictionaries; the message format is described in Watch Protocol. The Flutter SDK’s iOS plugin carries its own relay.

XcodeGen Configuration

If you use XcodeGen for your watchOS project, add the SDK as a local package and link WatchConnectivity:

name: SynheartWatchDemo
options:
  deploymentTarget:
    watchOS: "10.0"

packages:
  SynheartSession:
    path: path/to/synheart-session-swift

targets:
  SynheartWatchApp:
    type: application
    platform: watchOS
    dependencies:
      - package: SynheartSession
      - sdk: WatchConnectivity.framework

Behavioral Signals

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

Mock Behavior (Development)

import SynheartSession

let session = SynheartSession(behaviorProvider: MockBehaviorProvider())

let events = try session.startSession(config: config)
Task {
    for await event in events {
        if case .sessionFrame(_, _, _, _, let behavior?) = event {
            print("Stability: \(behavior["stability_index"] ?? "")")
        }
    }
}

Production (via synheart-behavior)

import SynheartSession
import SynheartSessionBehavior
import SynheartBehavior

let behaviorSdk = SynheartBehavior()
try behaviorSdk.initialize()

let session = SynheartSession(
    provider: myBiosignalProvider,
    behaviorProvider: BehaviorSdkProvider(sdk: behaviorSdk)
)

The behavior value is only present in frames when a BehaviorProvider is configured and returns data. See Flutter SDK — Behavioral Fields for the keys; they are the same in every SDK.

API Reference

SynheartSession

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

Method	Description
`startSession(config:) throws -> AsyncStream<SessionEvent>`	Start a session. Throws `SessionError.invalidState` if a session is already running (whatever its id) or the instance is disposed
`stopSession(sessionId:) throws`	Stop the running session; emits `.sessionSummary` and finishes the stream. Throws if no session is running or the id does not match. No-op after `dispose()`
`getStatus() -> SessionStatus?`	`SessionStatus(sessionId, active, lastSeq)`, or `nil` if no session is running
`ingestHsiMetrics(sessionId:hsiMetrics:)`	Supply HRV values for the running session
`dispose()`	Stop timers and the provider, finish the stream, release state. Later `startSession` calls throw

Resources

Repository: synheart-session-swift
Issues: GitHub Issues