--- title: Android API Reference description: API reference for the SmartSpectra Android SDK — Kotlin types, lifecycle methods, metrics, and error codes. sidebarTitle: API Reference --- > SmartSpectra SDK developer docs for v3.4.0, the latest stable release. Web page: https://presagetech.com/docs/smartspectra-sdk/android/api-reference > Index of all pages: https://presagetech.com/docs/smartspectra-sdk/llms.txt ## 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]. ```kotlin class SmartSpectraSdk ``` ### Methods - ```kotlin public suspend fun start() ``` Begin processing the selected input. In custom mode, await this call before submitting frames. Camera capture is the default until [useCustomInput] is called. - ```kotlin public suspend fun stop() ``` Stop processing. Call [start] again to resume. - ```kotlin public fun useCustomInput(frameTransform: FrameTransform = FrameTransform.NONE): CustomInput ``` Select caller-supplied frames while stopped. No camera discovery, capture, or camera permission is required. Replacing the source invalidates older handles. Throws [SmartSpectraException] with INVALID_STATE during processing or startup. - ```kotlin public fun useCamera(selection: CameraSelection) ``` Select SDK camera capture while stopped. Default prefers front, then the first discovered camera. Explicit selections never fall back. Resolution happens when capture starts; unavailable cameras report INPUT_UNAVAILABLE. Throws CONFIGURATION_FAILED for an empty ID and INVALID_STATE while busy. Rejected requests preserve the previous source. Stop/start/reset retain the chosen selection until another source is selected. - ```kotlin @Deprecated("Pass an explicit CameraSelection, such as Default or ById(id).") public fun useCamera() ``` - ```kotlin public suspend fun reset() ``` Stop processing and clear measurement output, retaining the selected input, transform, configuration, and custom-input handle. Call [start] to begin again. Safe to call while stopped; teardown runs off the caller's thread. - ```kotlin public fun requestInsight(text: String): Int ``` Dispatch an on-demand insight request alongside the vitals samples buffered since the last send. Requires an active measurement: the engine owns the insight session for the duration of a session, so call this after [start]. - ```kotlin @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]. Select only while stopped; after stopping, toggle back to `false` to return to normal camera capture. Throws [SmartSpectraException] with INVALID_STATE if processing or startup is active. New integrations should use [useCustomInput], which requires no testing opt-in. - ```kotlin @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. Throws [SmartSpectraException] when video input has not been selected or the frame is rejected. Use [CustomInput.sendFrame] for typed per-frame return values. - ```kotlin public suspend fun availableCameras(context: Context): List ``` Discover camera IDs, optional names, and facing without initializing SmartSpectra, authenticating, or starting capture. No permission prompt is shown. Visibility depends on platform permissions; a snapshot does not guarantee a later capture will succeed. Throws INPUT_UNAVAILABLE when discovery fails. Android currently provides no display names. - ```kotlin @JvmStatic @JvmOverloads fun initialize( context: Context, config: SmartSpectraConfig = SmartSpectraConfig(), ): SmartSpectraSdk ``` Initialize the shared SDK instance and apply the provided configuration. ### Properties - ```kotlin val config: SmartSpectraConfig ``` - ```kotlin public val metrics: LiveData = _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. - ```kotlin public val metricsFlow: SharedFlow = _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. - ```kotlin public val insight: LiveData = _insight ``` - ```kotlin public val imageOutput: LiveData = _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. - ```kotlin val processingStatus: LiveData ``` - ```kotlin val validationStatus: LiveData = _validationStatus ``` - ```kotlin val error: LiveData = _error ``` - ```kotlin val version: String ``` - ```kotlin 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]. ```kotlin public class SmartSpectraConfig() ``` ### Properties - ```kotlin @Deprecated("Use sdk.useCamera(CameraSelection.Front), Back, or ById instead.") public var cameraPosition: CameraPosition ``` Legacy facing preference; defaults to front and updates active capture. Deprecated: use [SmartSpectraSdk.useCamera] with an explicit [CameraSelection]. After typed selection, this preference applies again only after legacy `useCamera()`. - ```kotlin public var apiKey: String? = null ``` - ```kotlin 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). - ```kotlin public var imageOutputEnabled: Boolean = true ``` - ```kotlin 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. - ```kotlin 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. - ```kotlin public var requestedMetrics: List? ``` 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. - ```kotlin public val breathingMetrics: List = 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. - ```kotlin public val cardioMetrics: List = 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. - ```kotlin public val faceMetrics: List = listOf( MetricType.FACE_LANDMARKS, MetricType.BLINKING, MetricType.TALKING, MetricType.EXPRESSIONS, ) ``` Face metric bundle (landmarks, blinking, talking, expressions). Requires the face-metrics-enabled bundle. - ```kotlin public val edaMetrics: List = listOf( MetricType.EDA_TRACE, ) ``` EDA Proxy (electrodermal activity) trace metric bundle. ## CameraPosition - `public fun fromLensFacing(@CameraSelector.LensFacing lensFacing: Int): CameraPosition = when (lensFacing)` - `FRONT` - `BACK` ## CustomInput Caller-supplied frame input, obtained from [SmartSpectraSdk.useCustomInput]. The handle survives stop/start and reset; selecting another source invalidates it. Submit after start completes, from a worker thread, in timestamp order. ```kotlin public fun sendFrame(frame: VideoFrame, timestampUs: Long): FrameSubmissionResult ``` Consumes the borrowed pixels before returning. Timestamps are strictly increasing microseconds on one monotonic timeline per run. Gaps greater than two seconds are rejected; stop and start the SDK to begin a fresh timeline after an interruption. Inspect the returned result: timestamp rejections do not end the session or publish a global SDK error. A later frame on the accepted timeline can still be sent. Calls are serialized; no queue of caller-owned buffers is retained. ```kotlin public fun sendFrame(frame: Bitmap, timestampUs: Long): FrameSubmissionResult ``` Copies a bitmap for submission. The caller retains ownership of the bitmap. ```kotlin public fun sendFrame(frame: ImageProxy): FrameSubmissionResult ``` Submits a full YUV_420_888 image, applying its clockwise rotationDegrees metadata before the selected session transform. Uses its capture timestamp converted from nanoseconds to microseconds. The caller must close the image after this returns. Unrotated images borrow the planes directly; rotated images require a pixel copy. Cropped images are rejected. Plane buffer positions and limits are preserved. ## FrameTransform Spatial transform applied to every frame in a custom-input session. - `NONE` - `ROTATE_90_CW` - `ROTATE_90_CCW` - `ROTATE_180` - `MIRROR_HORIZONTAL` - `MIRROR_VERTICAL` ## PixelFormat Pixel layout of a [VideoFrame.Packed] buffer. - `RGB` - `BGR` - `RGBA` - `BGRA` - `NV12` - `NV21` - `YUYV` ## ProcessingStatus - `IDLE` - `STARTING` - `RUNNING` - `STOPPING` - `ERROR` ## ValidationStatus ```kotlin public data class ValidationStatus( val code: ValidationCode, val hint: String, ) ``` ### Properties - ```kotlin val code: ValidationCode ``` - ```kotlin val hint: String ``` ## ValidationCode - `val wireValue: Int` - `OK` - `NO_FACE_FOUND` - `MULTIPLE_FACES_FOUND` - `FACE_NOT_CENTERED` - `FACE_SIZE_OUT_OF_RANGE` - `TOO_DARK` - `TOO_BRIGHT` - `CHEST_NOT_VISIBLE` - `CAMERA_TUNING` - `FRAME_RATE_TOO_LOW` - `EXCESSIVE_MOTION` - `FACE_TOO_CLOSE` - `FACE_TOO_FAR` - `FACE_TOO_HIGH` - `FACE_TOO_LOW` - `FACE_NOT_FORWARD` ## SmartSpectraError A typed error from the SmartSpectra SDK. Lifecycle methods throw [SmartSpectraException] wrapping this type, and async pipeline failures are published on [SmartSpectraSdk.error]. ```kotlin public data class SmartSpectraError( val code: Code, val message: String, val retryable: Boolean = false, ) ``` ### Properties - ```kotlin val code: Code ``` - ```kotlin val message: String ``` - ```kotlin 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` - `AUTHENTICATION_FAILED` - `CONFIGURATION_FAILED` - `CREDIT_EXHAUSTED` - `NETWORK_ERROR` - `SERVER_ERROR` - `INPUT_UNAVAILABLE` - `PROCESSING_FAILED` - `FRAME_CONVERSION_FAILED` - `NON_MONOTONIC_TIMESTAMP` - `TIMESTAMP_GAP` ## SmartSpectraException ```kotlin public class SmartSpectraException( public val error: SmartSpectraError, ) : RuntimeException(error.message) ``` ### Properties - ```kotlin val error: SmartSpectraError ``` ## CameraSelection Requested camera: `CameraSelection.Default`, `Front`, `Back`, or `CameraSelection.ById(id)` for an exact ID from [SmartSpectraSdk.availableCameras]. ## CameraSelection.Default Prefer front, otherwise use the first camera in discovery order. ```kotlin public data object CameraSelection.Default : CameraSelection ``` ## CameraSelection.Front ```kotlin public data object CameraSelection.Front : CameraSelection ``` ## CameraSelection.Back ```kotlin public data object CameraSelection.Back : CameraSelection ``` ## CameraSelection.ById An opaque, device-local camera ID. An unavailable ID fails without fallback. ```kotlin public data class CameraSelection.ById(val id: String) : CameraSelection ``` ### Properties - ```kotlin val id: String ``` ## CameraFacing Camera facing, including cameras that have no front/back position. - `FRONT` - `BACK` - `UNKNOWN` ## CameraLensType Best-effort lens classification, independent of digital zoom. Android compares the nominal view with the default camera of the same facing. Missing metadata and logical cameras combining multiple lenses report [UNKNOWN]. - `UNKNOWN` - `WIDE_ANGLE` - `ULTRA_WIDE` - `TELEPHOTO` ## CameraInfo A discoverable camera; availability may change before capture starts. ```kotlin public data class CameraInfo( val id: String, val name: String? = null, val facing: CameraFacing = CameraFacing.UNKNOWN, val lensType: CameraLensType = CameraLensType.UNKNOWN, ) ``` ### Properties - ```kotlin val id: String ``` - ```kotlin val name: String? = null ``` - ```kotlin val facing: CameraFacing = CameraFacing.UNKNOWN ``` - ```kotlin val lensType: CameraLensType = CameraLensType.UNKNOWN ``` ## SmartSpectraLogLevel 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` - `INFO` - `WARNING` - `ERROR` - `NONE` ## FramePlane A borrowed direct buffer with row and pixel strides in bytes. ```kotlin public data class FramePlane( val buffer: ByteBuffer, val rowStride: Int, val pixelStride: Int, ) ``` ### Properties - ```kotlin val buffer: ByteBuffer ``` - ```kotlin val rowStride: Int ``` - ```kotlin val pixelStride: Int ``` ## VideoFrame Caller-owned pixels. Buffers must be direct; only bytes between position and limit are used. Submission leaves those positions and limits unchanged. Keep the buffers alive and unchanged until [CustomInput.sendFrame] returns, then reuse them freely. ## VideoFrame.Packed A single buffer. NV12/NV21 require even dimensions and row stride, with the UV/VU plane immediately after rowStride * height bytes, using the same stride. YUYV requires an even width. Include padding after the final row. ```kotlin public data class VideoFrame.Packed( val buffer: ByteBuffer, val width: Int, val height: Int, val rowStride: Int, val pixelFormat: PixelFormat, ) : VideoFrame ``` ### Properties - ```kotlin val buffer: ByteBuffer ``` - ```kotlin val width: Int ``` - ```kotlin val height: Int ``` - ```kotlin val rowStride: Int ``` - ```kotlin val pixelFormat: PixelFormat ``` ## VideoFrame.Yuv420 Flexible YUV 4:2:0 planes. Y pixel stride must be 1; U and V must share pixel stride 1 or 2. Chroma dimensions round up for odd image dimensions. Padding after a plane's final sample is optional. ```kotlin public data class VideoFrame.Yuv420( val width: Int, val height: Int, val y: FramePlane, val u: FramePlane, val v: FramePlane, ) : VideoFrame ``` ### Properties - ```kotlin val width: Int ``` - ```kotlin val height: Int ``` - ```kotlin val y: FramePlane ``` - ```kotlin val u: FramePlane ``` - ```kotlin val v: FramePlane ``` ## FrameSubmissionResult Result of a frame submission; acceptance does not mean processing has finished. ## FrameSubmissionResult.Accepted ```kotlin public data object FrameSubmissionResult.Accepted : FrameSubmissionResult ``` ## FrameSubmissionResult.Rejected ```kotlin public data class FrameSubmissionResult.Rejected(val error: SmartSpectraError) : FrameSubmissionResult ``` ### Properties - ```kotlin val error: SmartSpectraError ```