API Reference

SmartSpectraSDK

Entry point for the SmartSpectra SDK. Most apps use the shared instance:

Initializers

• public init (config: SmartSpectraConfig)

  Create an isolated SDK instance backed by the given configuration. The authentication handler and preprocessing runtime are process-global, so only one instance can drive an active measurement at a time. Use this initializer for tests or advanced integrations where you intentionally need a separate observable state from shared. Most apps should just use SmartSpectraSDK/shared.

Methods

• public func start () async throws

  Begin processing frames from the device camera.

• public func stop () async throws

  Stop processing. Call start() again to resume.

• @discardableResult public func requestInsight (_ text: String) throws -> Int32

  Dispatch an on-demand insight request alongside the vitals samples buffered since the last send. The provided text is sent as the current turn's prompt; prior calls' text is not retained or re-sent by the SDK. The dispatched request type mirrors the Presage Analytics Gateway contract: combined when vitals samples are buffered at dispatch time, speech when only the prompt is present. Vitals snapshots auto-fire approximately every 15 seconds with no prompt and are published through SmartSpectraSDK/insight alongside on-demand replies; callers route on the delivered Insight's type field.

• @_spi(Testing)
  public func setVideoInput (path: String)

  Configures a video file as input source instead of the live camera. Supported formats: .mov, .mp4, .qt

• @_spi(Testing)
  public func setVideoTimestampInput (path: String)

  Configures optional timestamp file (one ms value per line) for frame timing.

• @_spi(Testing)
  public func setVideoInputEnabled (_ enabled: Bool)

  Enables or disables video file input mode. Toggleable at runtime. When enabled, camera input is disabled.

Properties

• public static let shared = SmartSpectraSDK()

• public internal(set) var metrics : Metrics?

• public internal(set) var imageOutput : UIImage?

• public internal(set) var processingStatus : ProcessingStatus = .idle

• public internal(set) var error : SmartSpectraError?

• public internal(set) var validationStatus : ValidationStatus?

• public internal(set) var insight : Insight?

• public nonisolated static var version : String

• public let config : SmartSpectraConfig

SmartSpectraConfig

Configuration for SmartSpectraSDK. Access configuration through SmartSpectraSDK/config rather than constructing one directly:

Initializers

• public init ()

  Creates a configuration with default values. Prefer SmartSpectraSDK/config over constructing a standalone config unless you are driving an isolated SmartSpectraSDK instance.

Properties

• public var cameraPosition : AVCaptureDevice.Position = .front

• public var imageOutputEnabled : Bool = true

• public var apiKey : String?

• public var requestedMetrics : [MetricType]?

• public nonisolated static let breathingMetrics : [MetricType]

• public nonisolated static let cardioMetrics : [MetricType]

• public nonisolated static let faceMetrics : [MetricType]

• public nonisolated static let edaMetrics : [MetricType]

ProcessingStatus

Indicates the current state of the preprocessing pipeline.

• case idle
• case starting
• case running
• case stopping
• case error

ValidationStatus

Measurement readiness: a stable code plus a human-readable hint. Orthogonal to ProcessingStatus (engine lifecycle).

Initializers

• public init (code: ValidationCode, hint: String)

Properties

• public let code : ValidationCode

• public let hint : String

ValidationCode

Measurement-readiness codes.

• case ok = 0
• case noFaceFound = 1
• case multipleFacesFound = 2
• case faceNotCentered = 3
• case faceSizeOutOfRange = 4
• case tooDark = 5
• case tooBright = 6
• case chestNotVisible = 7
• case cameraTuning = 10
• case frameRateTooLow = 11

SmartSpectraError

A typed error from the SmartSpectra SDK. Thrown by SmartSpectraSDK/start() and SmartSpectraSDK/stop(), and published on SmartSpectraSDK/error for async pipeline failures.

Initializers

• public init (code: Code, message: String, retryable: Bool = false)

Properties

• public let code : Code

• public let message : String

• public let retryable : Bool

• public var errorDescription : String?

SmartSpectraError.Code

SDK error codes. No .ok case — in Swift, success means no error thrown. Raw values are stable across SDK versions and match the C++/Android wire values. Never change an existing value; only append new codes at the end.

• case invalidState = 1
• case authenticationFailed = 2
• case configurationFailed = 3
• case creditExhausted = 4
• case networkError = 5
• case serverError = 6
• case inputUnavailable = 7
• case processingFailed = 8
• case frameConversionFailed = 9
• case nonMonotonicTimestamp = 10