API Reference

SmartSpectraSdk

Entry point for the SmartSpectra SDK. Most apps use the shared singleton initialized by AndroidX Startup, or call [initialize] with a custom [SmartSpectraConfig] before accessing [shared].

Methods

```
public suspend fun start()
```
Begin processing frames from the device camera.
```
public suspend fun stop()
```
Stop processing. Call [start] again to resume.
```
public fun requestInsight(text: String): Int
```
Dispatch an on-demand insight request alongside the vitals samples buffered since the last send.
```
@SmartSpectraTestingApi public fun setVideoInputEnabled(enabled: Boolean)
```
Enables or disables video-frame input mode for automated testing. While enabled, the SDK does not open the device camera (so no camera hardware or CAMERA permission is needed) and expects the caller to supply frames through [addVideoFrame]. Call before [start]; toggle back to false to return to normal camera capture.
```
@SmartSpectraTestingApi public fun addVideoFrame(frame: Bitmap, timestampUs: Long)
```
Feeds one decoded video frame into the measurement pipeline while video-frame input mode is active (see [setVideoInputEnabled]). Call after [start] has completed. Decode your recorded clip however you like (for example MediaMetadataRetriever or MediaCodec) and deliver frames in playback order.

@JvmStatic @JvmOverloads fun initialize( context: Context, config: SmartSpectraConfig = SmartSpectraConfig(), ): SmartSpectraSdk

Initialize the shared SDK instance and apply the provided configuration.

Properties

```
val config: SmartSpectraConfig
```
```
public val metrics: LiveData<Metrics?> = _metrics
```
Latest metrics snapshot (keep-latest). Suitable for scalar state such as pulse rate or status. For the per-sample traces, prefer [metricsFlow]: LiveData can drop intermediate emits under main-thread congestion, losing trace samples.
```
public val metricsFlow: SharedFlow<Metrics> = _metricsFlow.asSharedFlow()
```
Every metrics emission, in order — lossless streaming. Prefer this over [metrics] for the per-sample traces; deliveries are buffered, so nothing is dropped under consumer main-thread congestion.

public val insight: LiveData<Insight?> = _insight

```
public val imageOutput: LiveData<Bitmap?> = _imageOutput
```
Latest engine display frame as an ARGB_8888 [Bitmap], or null while image output is disabled. The bitmap is reused from a small internal pool and refilled on later frames. ImageView.setImageBitmap keeps the reference (it does not copy) and reads the pixels at draw time, so displaying each frame as it arrives is safe — the pool covers the delivery latency. You MUST copy it (Bitmap.copy(...) or draw into your own bitmap) if you retain or cache it, or refresh the view slower than frames arrive; otherwise its pixels change under you.

val processingStatus: LiveData<ProcessingStatus>

val validationStatus: LiveData<ValidationStatus?> = _validationStatus

val error: LiveData<SmartSpectraError?> = _error

```
val version: String
```
```
val shared: SmartSpectraSdk
```
Shared SmartSpectra SDK instance.

SmartSpectraConfig

Configuration for [SmartSpectraSdk]. Most apps access configuration through [SmartSpectraSdk.config], or pass a prebuilt config to [SmartSpectraSdk.initialize] before using [SmartSpectraSdk.shared].

Properties

```
public var apiKey: String? = null
```
```
public var logLevel: SmartSpectraLogLevel = SmartSpectraLogLevel.DEFAULT
```
Verbosity of SDK logging — both the SDK's own logging and the native engine. Set it before [SmartSpectraSdk.initialize] for full effect; later changes apply to the SDK's own logging immediately and to the engine when the next measurement session starts. Defaults to [SmartSpectraLogLevel.WARNING] (warnings and errors only).

public var cameraPosition: CameraPosition

public var imageOutputEnabled: Boolean = true

```
public var enableTelemetry: Boolean = true
```
Controls whether the SDK reports anonymous, aggregate usage telemetry. On by default; set false to opt out. When enabled, the SDK sends a per-session summary — no raw frames, metric values, file paths, or user/device identifiers — to help Presage improve SDK reliability. Reporting is best-effort and never blocks a measurement. Read when a measurement session starts.
```
public var previewSurfaceProvider: Preview.SurfaceProvider?
```
Optional CameraX preview surface supplied by a host app. When set, the SDK binds a CameraX [Preview] use case alongside image analysis so the host can display the camera stream through a native PreviewView without consuming bitmap image-output frames.
```
public var requestedMetrics: List<MetricType>?
```
Metrics the SDK requests for authorization and output. The getter never returns null — when no list has been set (or after explicitly setting null), it falls back to [breathingMetrics]. The setter accepts null to reset back to that default.

public val breathingMetrics: List<MetricType> = listOf( MetricType.CHEST_BREATHING, MetricType.ABDOMEN_BREATHING, MetricType.BREATHING_RATE, MetricType.BREATHING_AMPLITUDE, MetricType.APNEA, MetricType.RESPIRATORY_LINE_LENGTH, MetricType.BASELINE, MetricType.INHALE_EXHALE_RATIO, )

Breathing metric bundle. Equivalent to leaving [requestedMetrics] unset.

public val cardioMetrics: List<MetricType> = listOf( MetricType.PULSE_RATE, MetricType.ARTERIAL_PRESSURE_TRACE, MetricType.HRV, )

Cardio metric bundle (pulse rate, arterial pressure trace, HRV). Combine with [breathingMetrics] for the typical "vitals" bundle.

public val faceMetrics: List<MetricType> = listOf( MetricType.FACE_LANDMARKS, MetricType.BLINKING, MetricType.TALKING, MetricType.EXPRESSIONS, )

Face metric bundle (landmarks, blinking, talking, expressions). Requires the face-metrics-enabled bundle.

public val edaMetrics: List<MetricType> = listOf( MetricType.EDA_TRACE, )

Electrodermal activity (EDA) trace metric bundle.

CameraPosition

public fun fromLensFacing(@CameraSelector.LensFacing lensFacing: Int): CameraPosition = when (lensFacing)
FRONT
BACK

ProcessingStatus

IDLE
STARTING
RUNNING
STOPPING
ERROR

ValidationStatus

Properties

```
val code: ValidationCode
```
```
val hint: String
```

ValidationCode

val wireValue: Int
OK(0)
NO_FACE_FOUND(1)
MULTIPLE_FACES_FOUND(2)
FACE_NOT_CENTERED(3)
FACE_SIZE_OUT_OF_RANGE(4)
TOO_DARK(5)
TOO_BRIGHT(6)
CHEST_NOT_VISIBLE(7)
CAMERA_TUNING(10)
FRAME_RATE_TOO_LOW(11)
EXCESSIVE_MOTION(12)
FACE_TOO_CLOSE(13)
FACE_TOO_FAR(14)
FACE_TOO_HIGH(15)
FACE_TOO_LOW(16)
FACE_NOT_FORWARD(17)

SmartSpectraError

A typed error from the SmartSpectra SDK. Lifecycle methods throw [SmartSpectraException] wrapping this type, and async pipeline failures are published on [SmartSpectraSdk.error].

Properties

```
val code: Code
```
```
val message: String
```
```
val retryable: Boolean = false
```

SmartSpectraError.Code

SDK error codes. Raw values are stable across SDK versions and match the C++/Swift wire values.

INVALID_STATE(1)
AUTHENTICATION_FAILED(2)
CONFIGURATION_FAILED(3)
CREDIT_EXHAUSTED(4)
NETWORK_ERROR(5)
SERVER_ERROR(6)
INPUT_UNAVAILABLE(7)
PROCESSING_FAILED(8)
FRAME_CONVERSION_FAILED(9)
NON_MONOTONIC_TIMESTAMP(10)
TIMESTAMP_GAP(11)

Verbosity of SDK logging, set via [SmartSpectraConfig.logLevel]. Levels are cumulative: a level shows its own messages plus everything more severe. The setting covers both the SDK logging and the native engine. [DEBUG] cannot restore debug-only statements that were compiled out of the release engine binary. Wire values are stable across SDK versions and match the C++ SmartSpectraLogLevel values.

DEBUG(0, Log.DEBUG)
INFO(1, Log.INFO)
WARNING(2, Log.WARN)
ERROR(3, Log.ERROR)
NONE(4, Log.ASSERT + 1)

On this page