Synheart Session - Flutter SDK - Synheart Documentation

Overview

The Synheart Session Dart SDK provides a stream-based API for running timed biometric sessions. Sessions emit session frames with HR metrics at configurable intervals and deliver a final summary when complete. Frames can include behavioral signal data (typing, scrolling, taps, app switches, idle gaps, stability/fragmentation indices) when a BehaviorProvider is configured. A built-in mock engine lets you develop and test without hardware. Key Features:

Stream-based session lifecycle (SessionStarted -> SessionFrame* -> SessionSummary)
Pluggable BiosignalProvider and optional BehaviorProvider
Companion-watch sessions on Apple Watch and Wear OS through WatchBiosignalProvider
Built-in mock engine with seeded output
Configurable session modes, duration, and compute profile

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

Installation

Add to your pubspec.yaml:

dependencies:
  synheart_session: ^0.3.0

Install dependencies:

flutter pub get

Requirements

Dart SDK >=3.8.0 <4.0.0
Flutter >=3.22.0

Quick Start

Mock Mode (Development)

import 'package:synheart_session/synheart_session.dart';

final session = SynheartSession.mock(seed: 42);

final config = SessionConfig(
  mode: SessionMode.focus,
  durationSec: 30,
  profile: const ComputeProfile(windowSec: 10, emitIntervalSec: 3),
);

session.startSession(config).listen((event) {
  switch (event) {
    case SessionStarted():
      print('Session started');
    case SessionFrame():
      print('HR: ${event.metrics['hr_mean_bpm']} bpm');
    case BiosignalFrame():
      print('Raw samples: ${event.samples.length}');
    case SessionSummary():
      print('Done: ${event.durationActualSec}s');
    case SessionError():
      print('Error [${event.code.value}]: ${event.message}');
  }
});

SessionEvent is sealed, so a switch without a default must cover all five subclasses, including BiosignalFrame().

Live Mode with a Companion Watch

final session = SynheartSession(
  biosignalProvider: WatchBiosignalProvider(),
);

final config = SessionConfig(
  mode: SessionMode.breathing,
  durationSec: 60,
);

final subscription = session.startSession(config).listen(
  (event) {
    // Handle events
  },
  onDone: () {
    print('Stream closed');
  },
);

// Stop early
await session.stopSession(config.sessionId);

// Clean up
session.dispose();

SynheartSession() takes two optional named arguments: biosignalProvider and behaviorProvider. Watch routing happens only when biosignalProvider is a WatchBiosignalProvider: startSession and stopSession then also send start_session / stop_session commands to the companion app (WatchConnectivity on iOS, Wearable Data Layer on Android). The watch’s events feed the phone-side engine as HR samples, and the phone-side engine emits the frames you receive. There is no fallback to another source. If no watch is reachable, frames still arrive on schedule with sample_count 0 and hr_mean_bpm 0.0. With no biosignalProvider at all, the same happens. See Lifecycle.

Watch Connectivity

Query watch connectivity status from your Flutter app:

final session = SynheartSession(biosignalProvider: WatchBiosignalProvider());
final status = await session.getWatchStatus();

if (status != null) {
  print('Supported: ${status.supported}');
  print('Paired: ${status.paired}');
  print('Installed: ${status.installed}');
  print('Reachable: ${status.reachable}');
}

WatchStatus fields:

Field	Type	Description
`supported`	`bool`	iOS: WatchConnectivity is supported. Android: Google Play services is available
`paired`	`bool`	iOS: an Apple Watch is paired. Android: same as `reachable`
`installed`	`bool`	iOS: the companion watch app is installed. Android: same as `reachable`
`reachable`	`bool`	iOS: `WCSession.isReachable`. Android: at least one Wear OS node is connected

getWatchStatus() returns null in mock mode and whenever biosignalProvider is not a WatchBiosignalProvider. On iOS, reachable requires the watch to be paired, the companion app installed, and the watch app reachable. The start command is only sent when the watch is reachable at the moment startSession is called.

Session Configuration

final config = SessionConfig(
  mode: SessionMode.focus,          // focus, breathing, or typing
  durationSec: 60,                  // session duration in seconds
  profile: const ComputeProfile(
    windowSec: 10,                  // sliding window size
    emitIntervalSec: 3,             // session frame interval
  ),
  windowLabel: 'morning-check',     // optional label
);

// Auto-generated UUID accessible via config.sessionId

SessionConfig

Parameter	Type	Required	Default	Description
`mode`	`SessionMode`	Yes	-	`SessionMode.focus`, `SessionMode.breathing`, or `SessionMode.typing`
`durationSec`	`int`	Yes	-	Session duration in seconds
`profile`	`ComputeProfile`	No	60s window, 5s interval	Session frame computation timing
`windowLabel`	`String?`	No	`null`	Optional label for the session window
`includeRawSamples`	`bool`	No	`false`	Enable raw biosignal frames (mock engine only)
`sessionId`	`String?`	No	Auto-generated UUID	Custom session ID

ComputeProfile

Parameter	Type	Default	Description
`windowSec`	`int`	60	Sliding window size in seconds
`emitIntervalSec`	`int`	5	How often to emit session frames in seconds
`rawEmitIntervalSec`	`int?`	`null`	How often to emit raw biosignal frames (defaults to `emitIntervalSec`)

Session Events

All events extend the sealed SessionEvent class and include a sessionId.

SessionStarted

Emitted immediately when startSession is called.

case SessionStarted():
  print('Started at ${event.startedAtMs}');

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

SessionFrame

Emitted at each emitIntervalSec with computed session metrics.

case SessionFrame():
  final hr = event.metrics['hr_mean_bpm'] as double?;
  final rmssd = event.metrics['rmssd_ms'] as double?;
  print('HR: $hr bpm, RMSSD: $rmssd ms');

  // Optional behavioral signals
  if (event.behavior != null) {
    print('Stability: ${event.behavior!['stability_index']}');
  }

Field	Type	Description
`sessionId`	`String`	Session identifier
`seq`	`int`	Frame sequence number (1-based)
`emittedAtMs`	`int`	Unix timestamp in milliseconds
`metrics`	`Map<String, dynamic>`	Flat metrics map (see below)
`behavior`	`Map<String, dynamic>?`	Optional behavioral signals (when a `BehaviorProvider` is configured)

Live engine metrics keys:

Key	Type	Description
`hr_mean_bpm`	`double`	Mean HR over the window, one decimal; `0.0` when the window is empty
`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`	Samples in the window
`start_ms` / `end_ms`	`int`	First and last sample timestamps (the current time when the window is empty)
`session_id`	`String`	Session identifier
`mode`	`String`	Session mode value
`seq`	`int`	Frame sequence number

The mock engine emits the same keys except pnn50, computes synthetic hr_sdnn_ms and rmssd_ms from its generated data, and adds "mock": true.

BiosignalFrame

Emitted at each rawEmitIntervalSec when includeRawSamples is true. In 0.3.0 only the mock engine emits BiosignalFrame; the live engine does not.

case BiosignalFrame():
  for (final sample in event.samples) {
    print('BPM: ${sample.bpm}, RR: ${sample.rrIntervalMs} ms');
    if (sample.accelerometer case final accel?) {
      print('Accel: (${accel.x}, ${accel.y}, ${accel.z})');
    }
  }

Field	Type	Description
`sessionId`	`String`	Session identifier
`seq`	`int`	Raw frame sequence number (1-based, separate from `SessionFrame.seq`)
`emittedAtMs`	`int`	Unix timestamp in milliseconds
`samples`	`List<BiosignalSample>`	Raw biosignal samples

BiosignalSample fields:

Field	Type	Description
`timestampMs`	`int`	Unix timestamp in milliseconds
`bpm`	`double`	Heart rate
`rrIntervalMs`	`double?`	Inter-beat interval in milliseconds
`accelerometer`	`({double x, double y, double z})?`	3-axis accelerometer (synthetic in the mock engine)
`spo2`	`double?`	SpO2 percentage (0-100)

SessionSummary

Emitted when the session completes (duration elapsed or stopped manually). The stream closes after it.

case SessionSummary():
  print('Duration: ${event.durationActualSec}s');
  print('Avg HR: ${event.metrics['hr_mean_bpm']} bpm');

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

SessionError

Part of the sealed hierarchy and of the wire format. Neither Dart engine emits it in 0.3.0; misuse is reported by throwing SessionInvalidStateError instead. See Errors.

case SessionError():
  print('[${event.code.value}]: ${event.message}');

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

Error codes:

Code	Description
`permission_denied`	Health data permissions not granted
`sensor_unavailable`	Heart rate sensor not available
`low_battery`	Device battery too low
`os_terminated`	Operating system terminated the session
`invalid_state`	Invalid session state

HRV Metrics

The live engine does not compute HRV. Pass values from your HRV source (typically the Synheart runtime) with ingestHsiMetrics; the latest map is used for every following frame and the summary:

session.ingestHsiMetrics(config.sessionId, {
  'hrv.sdnn_ms': 48.2,
  'hrv.rmssd_ms': 36.5,
  'hrv.pnn50': 14.0,
});

It is a no-op in mock mode, after dispose(), or when no session with that id is running.

Behavioral Signals

Pass a BehaviorProvider to SynheartSession() or SynheartSession.mock(). The engine pulls a snapshot at each frame and once more for the summary. The Dart SDK bundles MockBehaviorProvider; to use real behavioral data, implement BehaviorProvider over your behavior source (see Providers).

Mock Mode

import 'package:synheart_session/synheart_session.dart';

final session = SynheartSession.mock(
  seed: 42,
  behaviorProvider: MockBehaviorProvider(),
);

final config = SessionConfig(
  mode: SessionMode.focus,
  durationSec: 30,
  profile: const ComputeProfile(windowSec: 10, emitIntervalSec: 3),
);

session.startSession(config).listen((event) {
  switch (event) {
    case SessionFrame():
      print('HR: ${event.metrics['hr_mean_bpm']}');
      if (event.behavior != null) {
        print('Stability: ${event.behavior!['stability_index']}');
        print('Fragmentation: ${event.behavior!['fragmentation_index']}');
      }
    case SessionSummary():
      print('Done: ${event.durationActualSec}s');
      if (event.behavior != null) {
        print('Final stability: ${event.behavior!['stability_index']}');
      }
    default:
      break;
  }
});

Behavioral Fields

When present, the behavior map on SessionFrame and SessionSummary includes:

Field	Type	Description
`typing_cadence`	`double?`	Keys per second
`inter_key_latency`	`double?`	Milliseconds between keystrokes
`burst_length`	`int?`	Keys in current burst
`scroll_velocity`	`double?`	Pixels per second
`scroll_acceleration`	`double?`	Pixels per second squared
`scroll_jitter`	`double?`	Variance in scroll speed
`tap_rate`	`double?`	Taps per second
`app_switches_per_minute`	`int`	App switches per minute
`foreground_duration`	`double?`	Seconds in foreground
`idle_gap_seconds`	`double?`	Idle gap duration in seconds
`stability_index`	`double?`	0.0 to 1.0
`fragmentation_index`	`double?`	0.0 to 1.0
`timestamp`	`int`	Capture timestamp (ms since epoch)

The behavior key is only present when a BehaviorProvider is configured, reports isAvailable, and returns a snapshot. Null optional fields are omitted from the map.

Complete Example

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:synheart_session/synheart_session.dart';

class SessionDemo extends StatefulWidget {
  const SessionDemo({super.key});

  @override
  State<SessionDemo> createState() => _SessionDemoState();
}

class _SessionDemoState extends State<SessionDemo> {
  final _session = SynheartSession.mock(seed: 42);
  StreamSubscription<SessionEvent>? _subscription;
  SessionConfig? _activeConfig;
  double _hr = 0;
  bool _running = false;

  void _start() {
    final config = SessionConfig(
      mode: SessionMode.focus,
      durationSec: 30,
      profile: const ComputeProfile(windowSec: 10, emitIntervalSec: 3),
    );

    setState(() {
      _activeConfig = config;
      _running = true;
    });

    _subscription = _session.startSession(config).listen(
      (event) {
        switch (event) {
          case SessionFrame():
            setState(() {
              _hr = (event.metrics['hr_mean_bpm'] as num?)?.toDouble() ?? 0;
            });
          case SessionSummary():
            setState(() => _running = false);
          default:
            break;
        }
      },
      onDone: () => setState(() => _running = false),
    );
  }

  Future<void> _stop() async {
    if (_activeConfig != null) {
      await _session.stopSession(_activeConfig!.sessionId);
    }
  }

  @override
  void dispose() {
    _subscription?.cancel();
    _session.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('HR: ${_hr.toStringAsFixed(1)} bpm',
                style: const TextStyle(fontSize: 32)),
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: _running ? _stop : _start,
              child: Text(_running ? 'Stop' : 'Start'),
            ),
          ],
        ),
      ),
    );
  }
}

API Reference

SynheartSession

Constructor	Description
`SynheartSession({BiosignalProvider? biosignalProvider, BehaviorProvider? behaviorProvider})`	Live mode. Watch commands are sent only when `biosignalProvider` is a `WatchBiosignalProvider`
`SynheartSession.mock({int? seed, BehaviorProvider? behaviorProvider})`	Mock mode with seeded synthetic data and optional behavioral signals

Method	Returns	Description
`startSession(SessionConfig)`	`Stream<SessionEvent>`	Start a session. Throws `SessionInvalidStateError` synchronously if a session with the same `sessionId` is running or the instance is disposed
`stopSession(String sessionId)`	`Future<void>`	Stop a running session (emits `SessionSummary`); also sends `stop_session` to the watch when routing is active
`getStatus()`	`Future<SessionStatus?>`	Status of an active session, or `null`
`getWatchStatus()`	`Future<WatchStatus?>`	Watch connectivity; `null` unless `biosignalProvider` is a `WatchBiosignalProvider`
`ingestHsiMetrics(String sessionId, Map<String, dynamic>)`	`void`	Supply HRV values to the live engine
`dispose()`	`void`	Release all resources

Resources

Repository: synheart-session-flutter
Issues: GitHub Issues