API reference (iOS)

public enum VitalsSDK {
  public static let sdkVersion: String        // "1.0.0"
  public static let engineVersion: String     // "1.3.0" (PpgCoreVersion.string)
  public static let buildDate: String         // "2026-09-30"; release scripts stamp it

  /// Verifies the key offline against the public key compiled into the SDK and records the status.
  /// Throws VitalsError.licenseInvalid, .licenseNotValidForApp(appId:), .licenseUpdatesExpired(updatesUntil:).
  @discardableResult
  public static func activate(licenseKey: String) throws -> LicenseStatus

  /// The status from the last successful activate(licenseKey:), or nil.
  public static var licenseStatus: LicenseStatus? { get }

  /// Rear camera, torch and the highest reachable frame-rate tier. Does not open the camera.
  public static func deviceSupport() -> DeviceSupport

  /// Current camera authorization, without prompting.
  public static var cameraAuthorization: CameraAuthorization { get }

  /// Prompts for camera access when not yet determined. True when access is granted.
  public static func requestCameraAccess() async -> Bool

  /// Debug logging to os.Logger (subsystem "com.neurofit.vitals"). Off by default.
  public static var isLoggingEnabled: Bool { get set }
}

public struct LicenseStatus: Sendable, Equatable {
  public let licensee: String
  public let apps: [String]          // bundle identifiers and application ids the key covers
  public let features: [String]      // ["vitals"] in 1.0.0
  public let updatesUntil: String    // "YYYY-MM-DD": last SDK build date this key accepts
  public let type: LicenseType
  public let warnings: [String]      // non-fatal notes, e.g. the relaxed app-id check in debug builds
  public init(licensee: String, apps: [String], features: [String], updatesUntil: String,
              type: LicenseType, warnings: [String])
}

public enum LicenseType: String, Sendable, Codable {
  case binary
  case source
}

public struct DeviceSupport: Sendable, Equatable {
  public let isSupported: Bool
  public let hasCamera: Bool         // a rear wide camera is present
  public let hasTorch: Bool          // the rear camera has a torch (required)
  public let fpsTier: Int?           // highest reachable tier: 60, 30 or 20; nil when none
  public let reason: String?         // why isSupported is false; nil when supported
  public init(isSupported: Bool, hasCamera: Bool, hasTorch: Bool, fpsTier: Int?, reason: String?)
}

public enum CameraAuthorization: String, Sendable {
  case notDetermined
  case denied
  case restricted
  case authorized
}

public struct VitalsConfiguration: Sendable, Equatable {
  public var readingDuration: TimeInterval = 60     // seconds (Double); the validated duration
  public var autoRestartAfterCancel: Bool = true    // after a cancel: positioning (true) or idle (false)
  public var motionBreathing: Bool = true           // accelerometer as a breathing-rate channel
  public var advanced: AdvancedConfiguration = AdvancedConfiguration()
  public init()
}

public struct AdvancedConfiguration: Sendable, Equatable {
  // Contact and signal
  public var minAmplitude: Double = 0.5
  public var contactEnterFrac: Double = 0.5
  public var contactExitFrac: Double = 0.5
  // Start gate
  public var startWindowSeconds: Double = 3.0
  public var startRequiredFraction: Double = 1.0
  public var startQualityFloor: Double = 0.5
  public var requireExposureConverged: Bool = false
  public var startMaxWaitSeconds: Double = 15.0
  // Cancel gates
  public var cancelWindowSeconds: Double = 12.0
  public var cancelMinSamples: Int = 8
  public var cancelBadFraction: Double = 0.6
  public var liveSqCancelConsecutive: Int = 100      // observe only
  public var contactLossPreviews: Int = 3
  public var liveDiscardGateSeconds: Int = 35
  public var liveDiscardGateThreshold: Double = 0.5
  // Exposure (iOS runs auto-exposure; these are carried for parity and inert while the tuner is off)
  public var exposureTunerEnabled: Bool = false
  public var exposureTargetDc: Double = 150
  public var exposureDcMin: Double = 120
  public var exposureDcMax: Double = 210
  public var exposureTuneFramesPerStep: Int = 15
  public var exposureTuneMaxSteps: Int = 8
  public var exposureTuneGamma: Double = 1.0
  public var exposureTunerMaxCancels: Int = 2
  // Engine finalize
  public var consistencyGate: Bool = true
  public var mergedIntervalFix: Bool = true
  public var androidEstimator: Bool = false          // Android-only estimator; no effect on iOS
  // Frame-rate tiers tried in order; the session drops a tier on sustained frame drop
  public var fpsTiers: [Int] = [60, 30, 20]
  public init()
}

public final class VitalsSession {
  /// Throws .notActivated (activate has not succeeded), .unsupportedDevice(reason:) (deviceSupport().isSupported
  /// is false) or .internalError("Invalid configuration: ...") (see Configuration validation).
  public convenience init(configuration: VitalsConfiguration = VitalsConfiguration()) throws

  /// Optional camera preview for the host to place. Available after init.
  public var previewLayer: AVCaptureVideoPreviewLayer? { get }

  /// Every event, in order, on the main thread. One consumer per session. The stream ends after the
  /// terminal event (completed or failed) and on stop().
  public let events: AsyncStream<VitalsEvent>

  /// Callback alternative to events. Called on the main thread.
  public weak var delegate: VitalsSessionDelegate? { get set }

  /// The current state. Safe from any thread.
  public var state: VitalsSessionState { get }

  /// Turns on the camera and torch and enters positioning.
  public func start() async throws

  /// Cancels the current attempt; the session returns to positioning (autoRestartAfterCancel) or idle.
  /// No-op unless measuring. Any thread.
  public func cancelReading(reason: String = "host")

  /// Tears down the camera and turns the torch off. Idempotent. Any thread.
  public func stop()
}

public protocol VitalsSessionDelegate: AnyObject {
  func vitalsSession(_ session: VitalsSession, didEmit event: VitalsEvent)
}

public enum VitalsSessionState: Sendable, Equatable {
  case idle
  case positioning                     // camera and torch on; waiting for a stable fingertip signal
  case measuring(elapsed: Double)      // reading in progress; seconds since the reading started
  case finalizing
  case completed(VitalsResult)
  case failed(VitalsError)
}

public enum VitalsEvent: Sendable, Equatable {
  case state(VitalsSessionState)                        // every transition (not the measuring ticks)
  case guidance(Guidance, startProgress: Double)        // about 1 Hz while positioning; startProgress 0...1
  case preview(LivePreview)                             // about 1 Hz while measuring
  case heartbeat(ibiMs: Double?)                        // one per detected beat while measuring
  case started                                          // the start gate opened; a reading began
  case cancelled(CancelReason, CancelContext)
  case reconfiguringCamera(lowPowerMode: Bool)          // dropping to a lower fps tier in place
  case recoverableError(VitalsRecoverableError)         // one automatic recovery per session
  case measurementComplete                              // the full duration was captured; result follows
  case completed(VitalsResult)
  case failed(VitalsError)
}

public enum Guidance: String, Sendable, CaseIterable {
  case noContact      // no fingertip detected
  case lowQuality     // contact, signal not yet stable
  case weakSignal     // contact, pulse amplitude below minAmplitude
  case compliant      // eligible; the start gate is filling
  case frameDrop      // camera below 70% of its target frame rate
}

public struct LivePreview: Sendable, Equatable {
  public let elapsed: Double                 // seconds since the reading started
  public let progress: Double                // elapsed / readingDuration, clamped to 0...1
  public let hrBpm: Double?
  public let rmssdMs: Double?                // provisional HRV (RMSSD), from about 20 s; nil before
  public let signalLevel: SignalLevel
  public let breathingRate: Double?          // breaths per minute; nil until the estimate is ready (about 30 s)
  public let abortRisk: AbortRisk
  public init(elapsed: Double, progress: Double, hrBpm: Double?, rmssdMs: Double?,
              signalLevel: SignalLevel, breathingRate: Double?, abortRisk: AbortRisk)
}

public enum SignalLevel: String, Sendable, CaseIterable {
  case strong, good, fair, weak              // quality score >= 0.80 / >= 0.65 / >= 0.50 / else
}

public enum AbortRisk: String, Sendable, CaseIterable {
  case none, warn, imminent                  // distance to the no-low-discard-estimate cancel
}

public enum CancelReason: Sendable, Equatable {
  case contactLost                 // no contact for contactLossPreviews consecutive previews
  case lowQuality                  // cancel gate: too many failed quality checks in the window
  case lowLiveSignalQuality        // liveSqCancelConsecutive withheld live estimates (observe only)
  case noLowDiscardEstimate        // no live estimate below the threshold by liveDiscardGateSeconds
  case host(String)                // cancelReading(reason:)

  /// The snake_case token the NEUROFIT app logs ("contact_lost", "low_quality", "low_live_signal_quality",
  /// "no_low_discard_estimate"), or the host's own string for .host.
  public var token: String { get }
}

public struct CancelContext: Sendable, Equatable {
  public let elapsedSeconds: Double?
  public let qualityScore: Double?
  public let effectiveFps: Int
  public let deviceModel: String             // hardware identifier, e.g. "iPhone15,2"
  public let redDc: Double?                  // red mean of the last measuring frame
  public let exposureIso: Double?            // the camera's current ISO
  public let exposureTuneSteps: Int?         // always nil on iOS (no exposure tuner)
  public let exposureInBand: Bool?           // redDc within exposureDcMin...exposureDcMax
  public func toDictionary() -> [String: Any]
}

public enum VitalsRecoverableError: Sendable, Equatable {
  case frameRateUnsustainable(fps: Double)
  case cameraStalled
}

public enum VitalsError: Error, Sendable, Equatable {
  case notActivated                                  // activate(licenseKey:) has not succeeded
  case licenseInvalid                                // malformed key or bad signature
  case licenseNotValidForApp(appId: String)          // the key does not list this bundle identifier
  case licenseUpdatesExpired(updatesUntil: String)   // this build is dated after the key's window
  case cameraDenied
  case cameraRestricted
  case cameraUnavailable
  case unsupportedDevice(reason: String)
  case interrupted(reason: String)                   // backgrounding, another client, media services reset
  case noHeartRate                                   // the reading finished without a heart rate
  case alreadyRunning
  case internalError(String)

  /// The case name as a stable string ("notActivated", "licenseInvalid", ...), for hosts and wrappers.
  public var code: String { get }
}

extension VitalsError: LocalizedError {
  public var errorDescription: String? { get }       // one English sentence per case, with the associated value
}

public struct VitalsResult: Sendable, Codable, Equatable {
  public let id: UUID
  public let capturedAt: Date
  public let durationSeconds: Double
  public let heartRateBpm: Double?
  public let rmssdMs: Double?                   // HRV (RMSSD), ms
  public let sdnnMs: Double?
  public let baevskyStressIndex: Double?
  public let sd2sd1: Double?                    // Poincaré SD2:SD1
  public let breathingRateBrpm: Double?         // returned at any confidence
  public let breathingRateConfidence: Double?   // nil exactly when breathingRateBrpm is nil; 0...1
  public let confidence: Double                 // HRV confidence, else heart-rate confidence, else 0
  public let quality: SignalQuality
  public let flags: [String]
  public let diagnostics: VitalsDiagnostics
  public let engineVersion: String              // "1.3.0"
  public let sdkVersion: String                 // "1.0.0"
}

public enum SignalQuality: Int, Sendable, Codable, CaseIterable {
  case clean = 3
  case usable = 2
  case withheld = 1
}

public struct VitalsDiagnostics: Sendable, Codable, Equatable {
  // Provenance
  public let engine: String                 // engine: "neurofit_vitals"
  public let engineVersion: String          // engine_version
  public let hrSource: String               // hr_source
  public let refineMode: String             // refine_mode: a per-platform engine constant. Opaque.
  public let effectiveFps: Int              // effective_fps
  // Quality
  public let signalQuality: Int             // signal_quality
  public let qualityPassedFraction: Double  // quality_passed_fraction
  public let discardRatio: Double           // discard_ratio
  public let saturationFrac: Double         // saturation_frac
  public let measuredFps: Double            // measured_fps
  public let frameIntervalCv: Double        // frame_interval_cv
  public let frameDropComplianceErrorCount: Int // frame_drop_compliance_error_count
  public let amplitude: Double              // amplitude
  public let spectralConcentration: Double  // spectral_concentration
  public let snrDb: Double                  // snr_db
  public let skewness: Double               // skewness
  // Capture hardware
  public let torchActive: Bool              // torch_active
  public let torchLevel: Double             // torch_level
  public let exposureIso: Double            // exposure_iso
  public let exposureDurationMs: Double     // exposure_duration_ms
  public let exposureLocked: Bool           // exposure_locked
  public let exposureTunerEnabled: Bool     // exposure_tuner_enabled
  public let exposureTuneSteps: Int         // exposure_tune_steps
  public let redDcMean: Double              // red_dc_mean
  public let activeFormatWidth: Int         // active_format_width
  public let activeFormatHeight: Int        // active_format_height
  public let isVideoBinned: Bool            // is_video_binned
  public let videoFieldOfView: Double       // video_field_of_view
  public let lensPosition: Double           // lens_position
  public let minimumFocusDistance: Int      // minimum_focus_distance
  // Quality trajectory
  public let liveSqAt15s: Double            // live_sq_at_15s
  public let liveSqAt30s: Double            // live_sq_at_30s
  public let earlyMeanQualityScore: Double  // early_mean_quality_score
  public let earlyMinQualityScore: Double   // early_min_quality_score
  public let earlyMeanAmplitude: Double     // early_mean_amplitude
  public let liveSqMaxWithheldRun: Int      // live_sq_max_withheld_run
  public let liveSqWithheldEstimates: Int   // live_sq_withheld_estimates
  public let liveSqTotalEstimates: Int      // live_sq_total_estimates
  public let liveSqWithheldSeq: String      // live_sq_withheld_seq
  public let earlyMeanDiscardRatio: Double  // early_mean_discard_ratio
  public let earlyMaxDiscardRatio: Double   // early_max_discard_ratio
  // Breathing
  public let motionSamples: Int             // motion_samples
  public let rrMotionBrpm: Double?          // rr_motion_brpm
  public let rrMotionConc: Double?          // rr_motion_conc
  // Engine (consistency gate and estimator); optionals absent when the gate did not run
  public let gateEnabled: Bool              // gate_enabled
  public let gateMergedFixEnabled: Bool     // gate_merged_fix_enabled
  public let gateRejected: Bool?            // gate_rejected
  public let gateVeto: Bool?                // gate_veto
  public let gateNPairs: Int?               // gate_n_pairs
  public let gateNMerged: Int?              // gate_n_merged
  public let gateDiscardRaw: Double?        // gate_discard_raw
  public let gateMaxJump: Double?           // gate_max_jump
  public let gateHfShare: Double?           // gate_hf_share
  public let gateCompress: Double?          // gate_compress
  public let gateRPs: Double?               // gate_r_ps
  public let estColOverProd: Double?        // est_col_over_prod
  public let estRmssdParabolic: Double?     // est_rmssd_parabolic
  public let estRmssdFixed: Double?         // est_rmssd_fixed
  public let estGmApplied: Bool?            // est_gm_applied
  public let estArm2Fired: Bool?            // est_arm2_fired

  /// The snake_case dictionary, key for key what Codable encodes (optionals absent when nil).
  public func toDictionary() -> [String: Any]
}

public enum VitalsChange {
  /// Thresholds: heart rate 5 bpm, HRV (RMSSD) 10 ms, breathing rate 2 brpm (not exposed as public constants).
  public static func compare(baseline: VitalsResult, followUp: VitalsResult) -> ChangeAssessment
}

public struct ChangeAssessment: Sendable, Equatable {
  public let heartRateBpm: MetricChange?        // threshold 5 bpm
  public let rmssdMs: MetricChange?             // threshold 10 ms
  public let breathingRateBrpm: MetricChange?   // threshold 2 brpm
  public let sdnnMs: MetricChange?              // no threshold; beyondTypicalVariation is nil
  public let baevskyStressIndex: MetricChange?  // no threshold
  public let sd2sd1: MetricChange?              // no threshold
}

public struct MetricChange: Sendable, Equatable {
  public let baseline: Double
  public let followUp: Double
  public let delta: Double                       // followUp - baseline
  public let beyondTypicalVariation: Bool?       // |delta| > threshold; nil when the metric has no threshold
}