API reference (Android)

public object VitalsSDK {
  public const val sdkVersion: String = "1.0.0"
  public const val engineVersion: String   // "1.3.0" (PpgCoreVersion.STRING)
  public const val buildDate: String = "2026-09-30"   // release scripts stamp it

  /** The status from the last successful activate, or null. */
  @JvmStatic public val licenseStatus: LicenseStatus?

  /** Debug logging (tag "NeurofitVitals"). Off by default. */
  @JvmStatic public var loggingEnabled: Boolean

  /** Verifies the key offline against the public key compiled into the SDK and remembers the result.
   *  Throws VitalsException.LicenseInvalid, LicenseUpdatesExpired, LicenseNotValidForApp. */
  @JvmStatic @Throws(VitalsException::class)
  public fun activate(context: Context, licenseKey: String): LicenseStatus

  /** Rear camera, torch and 30 fps support from the camera characteristics. Does not open the camera. */
  @JvmStatic public fun deviceSupport(context: Context): DeviceSupport

  @JvmStatic public fun hasCameraPermission(context: Context): Boolean

  /** Requests android.permission.CAMERA through the activity's ActivityResultRegistry. Main thread. */
  @JvmStatic public fun requestCameraPermission(activity: ComponentActivity, onResult: (Boolean) -> Unit)

  /** Throws VitalsException.NotActivated, UnsupportedDevice or InternalError("invalid configuration: ..."). */
  @JvmStatic @JvmOverloads @Throws(VitalsException::class)
  public fun createSession(context: Context, config: VitalsConfig = VitalsConfig()): VitalsSession
}

public data class LicenseStatus(
  public val licensee: String,
  public val apps: List<String>,        // application ids and bundle identifiers the key covers
  public val features: List<String>,    // ["vitals"] in 1.0.0
  public val updatesUntil: String,      // "YYYY-MM-DD": last SDK build date this key accepts
  public val type: LicenseType,
  public val warnings: List<String>,    // non-fatal notes, e.g. the relaxed app-id check in debuggable builds
)

public enum class LicenseType { BINARY, SOURCE }

public data class DeviceSupport(
  public val isSupported: Boolean,
  public val hasCamera: Boolean,        // PackageManager.FEATURE_CAMERA (a rear camera)
  public val hasTorch: Boolean,         // PackageManager.FEATURE_CAMERA_FLASH; required
  public val fpsTier: Int?,             // 30 on a supported device, null otherwise
  public val reason: String?,           // why isSupported is false; null when supported
)

public data class VitalsConfig @JvmOverloads public constructor(
  public val readingDuration: Double = 60.0,          // seconds; the validated duration
  public val autoRestartAfterCancel: Boolean = true,  // after a cancel: Positioning (true) or Idle (false)
  public val motionBreathing: Boolean = true,         // accelerometer as a breathing-rate channel
  public val advanced: AdvancedConfig = AdvancedConfig(),
) {
  /** Java-friendly builder; every setter is optional. */
  public class Builder {
    public fun readingDuration(seconds: Double): Builder
    public fun autoRestartAfterCancel(enabled: Boolean): Builder
    public fun motionBreathing(enabled: Boolean): Builder
    public fun advanced(advanced: AdvancedConfig): Builder
    public fun build(): VitalsConfig
  }
}

public data class AdvancedConfig(
  public val minAmplitude: Double = 0.0,              // 0 = not enforced on Android
  public val contactEnterFrac: Double = 0.5,
  public val contactExitFrac: Double = 0.4,
  public val startWindowSeconds: Double = 4.0,
  public val startRequiredFraction: Double = 0.75,
  public val startQualityFloor: Double = 0.5,
  public val requireExposureConverged: Boolean = true,
  public val startMaxWaitSeconds: Double = 15.0,
  public val cancelWindowSeconds: Double = 12.0,
  public val cancelMinSamples: Int = 8,
  public val cancelBadFraction: Double = 0.6,
  public val liveSqCancelConsecutive: Int = 100,      // observe only
  public val contactLossPreviews: Int = 3,
  public val liveDiscardGateSeconds: Int = 35,
  public val liveDiscardGateThreshold: Double = 0.5,
  public val exposureTunerEnabled: Boolean = true,
  public val exposureTargetDc: Double = 150.0,
  public val exposureDcMin: Double = 120.0,
  public val exposureDcMax: Double = 210.0,
  public val exposureTuneFramesPerStep: Int = 15,
  public val exposureTuneMaxSteps: Int = 8,
  public val exposureTuneGamma: Double = 1.0,
  public val exposureTunerMaxCancels: Int = 2,
  public val consistencyGate: Boolean = true,
  public val mergedIntervalFix: Boolean = true,
  public val androidEstimator: Boolean = true,
  public val fps: Int = 30,                           // capture frame rate; Android runs one fixed tier
)

public class VitalsSession : AutoCloseable {
  /** The configuration the session was created with. */
  public val config: VitalsConfig

  /** The current state; emits on change. Updated on the SDK's engine thread. */
  public val state: StateFlow<VitalsSessionState>

  /** Every event, in order, emitted on the SDK's engine thread. Subscribe before start(); no replay.
   *  Buffer of 64 events per collector, DROP_OLDEST on overflow. */
  public val events: SharedFlow<VitalsEvent>

  /** Java-friendly callback alternative to events; callbacks run on executor. Pass null to remove. */
  public fun setListener(listener: VitalsListener?, executor: Executor)

  /** Binds the camera to owner, turns the torch on and enters Positioning. Main thread. */
  @JvmOverloads @Throws(VitalsException::class)
  public fun start(owner: LifecycleOwner, previewView: PreviewView? = null)

  /** Cancels the current attempt; the session returns to Positioning (autoRestartAfterCancel) or Idle.
   *  No-op unless measuring. Any thread. */
  @JvmOverloads
  public fun cancelReading(reason: String = "host")

  /** Tears the capture down: the SDK's own CameraX use cases only, torch off, accelerometer unregistered.
   *  Idempotent. Any thread. */
  public fun stop()
  override fun close(): Unit   // = stop()

  /** Suspends until Completed and returns the result; throws the VitalsException on Failed or a stop. */
  public suspend fun awaitResult(): VitalsResult

  /** Callback form of awaitResult for Kotlin code outside a coroutine. Kotlin-only. */
  public fun getResult(callback: (Result<VitalsResult>) -> Unit)
}

public fun interface VitalsListener {
  public fun onEvent(event: VitalsEvent)
}

public sealed interface VitalsSessionState {
  public data object Idle : VitalsSessionState            // created, stopped, or idle after a cancel
  public data object Positioning : VitalsSessionState     // camera and torch on; waiting for a steady fingertip
  public data class Measuring(public val elapsed: Double) : VitalsSessionState   // seconds since the attempt started
  public data object Finalizing : VitalsSessionState
  public data class Completed(public val result: VitalsResult) : VitalsSessionState
  public data class Failed(public val error: VitalsException) : VitalsSessionState
}

public sealed interface VitalsEvent {
  public data class State(public val state: VitalsSessionState) : VitalsEvent          // every transition
  public data class Guidance(public val guidance: com.neurofit.vitals.Guidance,
                             public val startProgress: Double) : VitalsEvent            // ~1 Hz while positioning
  public data class Preview(public val preview: LivePreview) : VitalsEvent              // ~1 Hz while measuring
  public data class Heartbeat(public val ibiMs: Double?) : VitalsEvent                  // one per detected beat
  public data object Started : VitalsEvent                                              // the start gate opened
  public data class Cancelled(public val reason: CancelReason, public val context: CancelContext) : VitalsEvent
  public data class ReconfiguringCamera(public val lowPowerMode: Boolean) : VitalsEvent // not emitted on Android in 1.0.0
  public data class RecoverableError(public val error: VitalsRecoverableError) : VitalsEvent
  public data object MeasurementComplete : VitalsEvent                                  // duration reached; result follows
  public data class Completed(public val result: VitalsResult) : VitalsEvent
  public data class Failed(public val error: VitalsException) : VitalsEvent
}

public enum class Guidance {
  NO_CONTACT,     // no fingertip detected over the camera
  LOW_QUALITY,    // contact, signal not yet stable
  WEAK_SIGNAL,    // contact, pulse amplitude below minAmplitude (never with the default 0.0)
  COMPLIANT,      // eligible; the start gate is filling
  FRAME_DROP,     // camera below its frame-rate floor (24 fps)
}

public data class LivePreview(
  public val elapsed: Double,               // seconds since the attempt started
  public val progress: Double,              // elapsed / readingDuration, clamped to 0..1
  public val hrBpm: Double?,
  public val rmssdMs: Double?,              // provisional HRV (RMSSD), from about 20 s; null before
  public val signalLevel: SignalLevel,
  public val breathingRate: Double?,        // breaths per minute; null until the estimate is ready (about 30 s)
  public val abortRisk: AbortRisk,
)

public enum class SignalLevel { STRONG, GOOD, FAIR, WEAK }   // quality >= 0.80 / >= 0.65 / >= 0.50 / else
public enum class AbortRisk { NONE, WARN, IMMINENT }         // distance to the no-low-discard-estimate cancel

public sealed interface CancelReason {
  public data object ContactLost : CancelReason            // no contact for contactLossPreviews previews
  public data object LowQuality : CancelReason             // cancel gate: too many failed quality checks
  public data object LowLiveSignalQuality : CancelReason   // liveSqCancelConsecutive withheld estimates (observe only)
  public data object NoLowDiscardEstimate : CancelReason   // no estimate below the threshold by the deadline
  public data class Host(public val reason: String) : CancelReason   // cancelReading(reason)
}

public class CancelContext(
  public val elapsedSeconds: Double?,
  public val qualityScore: Double?,
  public val effectiveFps: Int,
  public val deviceModel: String,          // "Samsung SM-A155F", "Google Pixel 8" (manufacturer + model)
  public val redDc: Double?,               // red mean of the last frame
  public val exposureIso: Double?,         // the tuner's manual ISO; null on the auto-exposure path
  public val exposureTuneSteps: Int?,      // exposure steps taken while positioning; null when the tuner is off
  public val exposureInBand: Boolean?,     // the tuner has the red mean inside its band
) {
  public fun toMap(): Map<String, Any>
  // equals, hashCode and toString cover every field and the wire reason
}

public sealed interface VitalsRecoverableError {
  public data class FrameRateUnsustainable(public val fps: Double) : VitalsRecoverableError  // measured fps, 1 decimal
  public data object CameraStalled : VitalsRecoverableError
}

public sealed class VitalsException(message: String) : Exception(message) {
  public class NotActivated : VitalsException                 // "VitalsSDK.activate(context, licenseKey) has not succeeded"
  public class LicenseInvalid : VitalsException               // malformed key or bad signature
  public class LicenseNotValidForApp(public val appId: String) : VitalsException
  public class LicenseUpdatesExpired(public val updatesUntil: String) : VitalsException
  public class CameraDenied : VitalsException                 // android.permission.CAMERA not granted
  public class CameraRestricted : VitalsException             // not raised on Android in 1.0.0
  public class CameraUnavailable : VitalsException            // the camera could not be opened or bound
  public class UnsupportedDevice(public val reason: String) : VitalsException
  public class Interrupted(public val reason: String) : VitalsException   // backgrounded, camera lost, stopped
  public class NoHeartRate : VitalsException                  // the reading finished without a heart rate
  public class AlreadyRunning : VitalsException
  public class InternalError(public val detail: String) : VitalsException
}

public data class VitalsResult(
  public val id: String,                         // UUID string
  public val capturedAt: Long,                   // epoch milliseconds when the reading finished
  public val durationSeconds: Double,
  public val heartRateBpm: Double?,
  public val rmssdMs: Double?,                   // HRV (RMSSD), ms
  public val sdnnMs: Double?,
  public val baevskyStressIndex: Double?,
  public val sd2sd1: Double?,                    // Poincaré SD2:SD1
  public val breathingRateBrpm: Double?,         // returned at any confidence
  public val breathingRateConfidence: Double?,   // null exactly when breathingRateBrpm is null; 0..1
  public val confidence: Double,                 // HRV confidence, else heart-rate confidence, else 0
  public val quality: SignalQuality,
  public val flags: List<String>,
  public val diagnostics: VitalsDiagnostics,
  public val engineVersion: String,              // "1.3.0"
  public val sdkVersion: String,                 // "1.0.0"
) {
  /** camelCase keys; capturedAt as ISO 8601; quality as its wireName; diagnostics as its snake_case map. */
  public fun toMap(): Map<String, Any?>
}

public enum class SignalQuality(public val value: Int) {
  CLEAN(3), USABLE(2), WITHHELD(1);
  public val wireName: String   // "clean" / "usable" / "withheld"
}

public data class VitalsDiagnostics(
  // Provenance
  public val engine: String = ENGINE,            // engine: "neurofit_vitals"
  public val engineVersion: String,              // engine_version
  public val hrSource: String,                   // hr_source
  public val refineMode: String,                 // refine_mode: a per-platform engine constant. Opaque.
  public val effectiveFps: Int,                  // effective_fps
  // Quality
  public val signalQuality: Int,                 // signal_quality
  public val qualityPassedFraction: Double,      // quality_passed_fraction
  public val discardRatio: Double,               // discard_ratio
  public val saturationFrac: Double,             // saturation_frac
  public val measuredFps: Double,                // measured_fps
  public val frameIntervalCv: Double,            // frame_interval_cv
  public val frameDropComplianceErrorCount: Int, // frame_drop_compliance_error_count
  public val amplitude: Double,                  // amplitude
  public val spectralConcentration: Double,      // spectral_concentration
  public val snrDb: Double,                      // snr_db
  public val skewness: Double,                   // skewness
  // Capture hardware
  public val torchActive: Boolean,               // torch_active
  public val torchLevel: Double,                 // torch_level (1.0 on, 0.0 off, -1.0 unknown)
  public val exposureIso: Double,                // exposure_iso (-1.0 when auto exposure owns it)
  public val exposureDurationMs: Double,         // exposure_duration_ms
  public val exposureLocked: Boolean,            // exposure_locked (the manual capture config was applied)
  // Quality trajectory
  public val liveSqAt15s: Double,                // live_sq_at_15s
  public val liveSqAt30s: Double,                // live_sq_at_30s
  public val earlyMeanQualityScore: Double,      // early_mean_quality_score
  public val earlyMinQualityScore: Double,       // early_min_quality_score
  public val earlyMeanAmplitude: Double,         // early_mean_amplitude
  public val liveSqMaxWithheldRun: Int,          // live_sq_max_withheld_run
  public val liveSqWithheldEstimates: Int,       // live_sq_withheld_estimates
  public val liveSqTotalEstimates: Int,          // live_sq_total_estimates
  public val liveSqWithheldSeq: String,          // live_sq_withheld_seq
  public val earlyMeanDiscardRatio: Double,      // early_mean_discard_ratio
  public val earlyMaxDiscardRatio: Double,       // early_max_discard_ratio
  // Configuration mirrors
  public val gateEnabled: Boolean,               // gate_enabled
  public val gateMergedFixEnabled: Boolean,      // gate_merged_fix_enabled
  public val estAndroidEstimatorEnabled: Boolean,// est_android_estimator_enabled
  // Breathing
  public val motionSamples: Int,                 // motion_samples
  public val rrMotionBrpm: Double? = null,       // rr_motion_brpm
  public val rrMotionConc: Double? = null,       // rr_motion_conc
  // Engine (present only when the consistency gate ran)
  public val gateRejected: Boolean? = null,      // gate_rejected
  public val gateVeto: Boolean? = null,          // gate_veto
  public val gateNPairs: Int? = null,            // gate_n_pairs
  public val gateNMerged: Int? = null,           // gate_n_merged
  public val gateDiscardRaw: Double? = null,     // gate_discard_raw
  public val gateMaxJump: Double? = null,        // gate_max_jump
  public val gateHfShare: Double? = null,        // gate_hf_share
  public val gateCompress: Double? = null,       // gate_compress
  public val gateRPs: Double? = null,            // gate_r_ps
  public val estColOverProd: Double? = null,     // est_col_over_prod
  public val estRmssdParabolic: Double? = null,  // est_rmssd_parabolic
  public val estRmssdFixed: Double? = null,      // est_rmssd_fixed
  public val estGmRatio: Double? = null,         // est_gm_ratio
  public val estGmApplied: Boolean? = null,      // est_gm_applied
  public val estArm2Fired: Boolean? = null,      // est_arm2_fired
) {
  /** The full snake_case map, identical to the keys on the Diagnostics page. */
  public fun toMap(): Map<String, Any>

  public companion object {
    /** The engine value every NEUROFIT Vitals reading carries. */
    public const val ENGINE: String = "neurofit_vitals"
  }
}

public object VitalsChange {
  public const val HEART_RATE_THRESHOLD_BPM: Double = 5.0
  public const val RMSSD_THRESHOLD_MS: Double = 10.0
  public const val BREATHING_RATE_THRESHOLD_BRPM: Double = 2.0

  @JvmStatic
  public fun compare(baseline: VitalsResult, followUp: VitalsResult): ChangeAssessment
}

public data class ChangeAssessment(
  public val heartRateBpm: MetricChange?,        // threshold 5 bpm
  public val rmssdMs: MetricChange?,             // threshold 10 ms
  public val breathingRateBrpm: MetricChange?,   // threshold 2 brpm
  public val sdnnMs: MetricChange?,              // no threshold; beyondTypicalVariation is null
  public val baevskyStressIndex: MetricChange?,  // no threshold
  public val sd2sd1: MetricChange?,              // no threshold
)

public data class MetricChange(
  public val baseline: Double,
  public val followUp: Double,
  public val delta: Double,                      // followUp - baseline
  public val beyondTypicalVariation: Boolean?,   // |delta| > threshold; null when the metric has no threshold
)

-keep public class com.neurofit.vitals.* { public *; protected *; }
-keep public interface com.neurofit.vitals.* { *; }
-keepclassmembers enum com.neurofit.vitals.* {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}
-keep class kotlin.Metadata { *; }
-keepattributes Signature, InnerClasses, EnclosingMethod, Exceptions, *Annotation*, SourceFile, LineNumberTable