--- title: Swift API Reference description: API reference for the SmartSpectra Swift SDK — observable state, 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/swift/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 instance: ```swift let sdk = SmartSpectraSDK.shared sdk.config.apiKey = "your-key" try await sdk.start() ``` Tests and advanced integrations can create an isolated instance via ``init(config:)``. The underlying authentication handler and C++ preprocessing runtime are process-global, so only one SDK instance can drive an active measurement at a time. ### Initializers - ```swift 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 - ```swift public func start () async throws ``` Begin processing the selected input (device camera by default). In custom mode, await this call before submitting frames. - ```swift public func stop () async throws ``` Stop processing. Call ``start()`` again to resume. - ```swift public func useCustomInput (frameTransform: FrameTransform = .none) throws -> CustomInput ``` Select caller-owned video input while stopped. No SDK camera discovery, capture, or camera permission is required. Selecting a source invalidates older custom-input handles. Throws `.invalidState` during startup or processing. - ```swift public func useCamera (_ selection: CameraSelection) throws ``` Select camera capture while stopped. Default prefers front, then the first discovered camera. Explicit selections never fall back. Selection is resolved at capture startup; an unavailable camera fails start with `.inputUnavailable`. Throws `.configurationFailed` for an empty ID and `.invalidState` while busy. Rejected requests preserve the previous source. Stop/start/reset retain the selection until another source is selected. This call does not open a camera. - ```swift @available(*, deprecated, message: "Pass an explicit CameraSelection, such as .default or .byId(id).") public func useCamera () throws ``` Select camera capture using the legacy config.cameraPosition behavior. - ```swift public nonisolated static func availableCameras () throws -> [CameraInfo] ``` Discover cameras without constructing or authenticating an SDK instance, requesting permission, or starting capture. Visibility depends on platform permissions; a snapshot does not guarantee capture will succeed later. Throws `.inputUnavailable` if discovery fails. - ```swift public func reset () async throws ``` Stop processing and clear measurement output, retaining configuration, the selected source, transform, and custom-input handle. Safe while idle; await before restarting. - ```swift @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 delivered `Insight` always has `type == .vitals` today (`.speech` and `.combined` are reserved and not emitted). Vitals snapshots auto-fire — one as each of pulse rate, breathing rate, and HRV first stabilises, then one every 60 seconds — carrying a fixed SDK-supplied prompt rather than caller text, and are published through ``SmartSpectraSDK/insight`` alongside on-demand replies, so match a reply to its prompt with `requestID`, not `type`. - ```swift @_spi(Testing) public func setVideoInput (path: String) ``` Configures a video file as input source instead of the live camera. Supported formats: .mov, .mp4, .qt - ```swift @_spi(Testing) public func setVideoTimestampInput (path: String) ``` Configures optional timestamp file (one ms value per line) for frame timing. - ```swift @_spi(Testing) public func setVideoInterframeDelay (milliseconds: Int) ``` Configures optional video-file playback throttling in milliseconds. - ```swift @_spi(Testing) public func setVideoInputEnabled (_ enabled: Bool) ``` Selects testing file input or camera input while stopped. An active-session selection is rejected and reported through `error`. ### Properties - ```swift public static let shared = SmartSpectraSDK() ``` The shared SDK instance. - ```swift public internal(set) var metrics : Metrics? ``` Real-time metrics emitted while processing is active. - ```swift public internal(set) var imageOutput : UIImage? ``` Live camera preview image. - ```swift public internal(set) var processingStatus : ProcessingStatus = .idle ``` Current processing pipeline status. - ```swift public internal(set) var error : SmartSpectraError? ``` Latest error from the SDK. - ```swift public internal(set) var validationStatus : ValidationStatus? ``` Measurement readiness: face position, lighting, etc. Only meaningful while ``processingStatus`` is `.running`. - ```swift public internal(set) var insight : Insight? ``` Latest insight from the AI insights service. - ```swift public nonisolated static var version : String ``` SDK version string. - ```swift public let config : SmartSpectraConfig ``` Configuration for this SDK instance. Mutate properties on this object rather than replacing it. ## SmartSpectraConfig Configuration for ``SmartSpectraSDK``. Access configuration through ``SmartSpectraSDK/config`` rather than constructing one directly: ```swift let sdk = SmartSpectraSDK.shared sdk.config.apiKey = "your-key" ``` Standalone construction is available for tests and advanced integrations that pass a custom config into ``SmartSpectraSDK/init(config:)``. ### Initializers - ```swift 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 - ```swift @available(*, deprecated, message: "Use sdk.useCamera(.front), .back, or .byId instead.") public var cameraPosition : AVCaptureDevice.Position = .front ``` Legacy camera position, used until an explicit camera selector is chosen. - ```swift public var logLevel : SmartSpectraLogLevel = .default ``` Verbosity of SDK logging — both the SDK's Swift-side logging and the native engine. Takes effect immediately when set (like ``imageOutputEnabled``). Defaults to ``SmartSpectraLogLevel/warning`` (warnings and errors only). - ```swift public var imageOutputEnabled : Bool = true ``` Controls whether the SDK publishes preview frames to ``SmartSpectraSDK/imageOutput``. When disabled, camera frames are still processed for vitals analysis, but the SDK skips `CVPixelBuffer` to `UIImage` conversion and preview updates. This is useful for custom integrations that do not display a live camera feed. Example: ```swift let sdk = SmartSpectraSDK.shared sdk.config.imageOutputEnabled = false ``` - Note: Changes take effect immediately and do not require restarting processing. - ```swift public var enableTelemetry : Bool = true ``` Controls whether the SDK reports anonymous, aggregate usage telemetry. Telemetry is on by default; set this to `false` to opt out. When enabled, the SDK sends a per-session summary. It does not include raw frames, metric values, file paths, user identifiers, or device identifiers. Reporting is best-effort and never blocks or affects a measurement session. Example: ```swift let sdk = SmartSpectraSDK.shared sdk.config.enableTelemetry = false ``` - Note: Read when a measurement session starts. - ```swift public var apiKey : String? ``` API key from the Presage developer portal. Setting this automatically configures authentication. - ```swift public var requestedMetrics : [MetricType]? ``` Which metrics to compute during processing. This property provides granular control over which metric families the SDK requests. Derived feature flags such as cardio and face processing are inferred from the selected metric types. Duplicate metrics are removed automatically while preserving the original order. If you do not set this property, the SDK defaults to breathing-only metrics: chest breathing, abdomen breathing, breathing rate, breathing amplitude, apnea, respiratory line length, baseline, and inhale/exhale ratio. Example: ```swift let sdk = SmartSpectraSDK.shared sdk.config.requestedMetrics = [ .breathingRate, .pulseRate, .faceLandmarks ] ``` Example using the predefined bundles: ```swift config.requestedMetrics = SmartSpectraConfig.breathingMetrics + SmartSpectraConfig.cardioMetrics ``` - ```swift public nonisolated static let breathingMetrics : [MetricType] ``` Breathing metric bundle. Equivalent to leaving ``SmartSpectraConfig/requestedMetrics`` unset. - ```swift public nonisolated static let cardioMetrics : [MetricType] ``` Cardio metric bundle (pulse rate, arterial pressure trace, HRV). Combine with ``breathingMetrics`` for the typical "vitals" bundle. - ```swift public nonisolated static let faceMetrics : [MetricType] ``` Face metric bundle (landmarks, blinking, talking, expressions). - ```swift public nonisolated static let edaMetrics : [MetricType] ``` EDA Proxy (electrodermal activity) trace metric bundle. ## CustomInput Caller-owned video input obtained from ``SmartSpectraSDK/useCustomInput(frameTransform:)``. The handle survives stop/start and reset. Selecting another source invalidates it. Await `sdk.start()` before submitting frames from a serial worker queue. Keep each buffer alive and unchanged until submission returns; the SDK retains no borrowed pixels. Calls are serialized with native teardown. This type is safe to share across threads; callers remain responsible for ordering timestamps and synchronizing buffer mutations. ### Methods - ```swift public func sendFrame (_ pixelBuffer: CVPixelBuffer, timestampUs: Int64) -> FrameSubmissionResult ``` Submits BGRA or 8-bit bi-planar NV12 (video or full range) pixels. Timestamps are nonnegative, strictly increasing microseconds on one monotonic timeline per run, below `Int64.max - 2`. Gaps greater than two seconds are rejected; stop and start again after an interruption. Row padding and separate NV12 planes are supported. NV12 is converted to BGRA before submission. Unsupported formats return `.rejected` with `.frameConversionFailed`. Pixels must already have the desired orientation, or select a session transform. Camera position and preview mirroring do not transform caller-owned frames. - ```swift public func sendFrame (_ sampleBuffer: CMSampleBuffer) -> FrameSubmissionResult ``` Submits the image and presentation timestamp of an uncompressed video sample. The timestamp is converted to microseconds; invalid, indefinite, infinite, negative, or out-of-range timestamps are rejected. Orientation is not inferred from metadata. ## FrameTransform Spatial transform applied to every frame in a custom-input session. - `case none = 0` - `case rotate90CW = 1` - `case rotate90CCW = 2` - `case rotate180 = 3` - `case mirrorHorizontal = 4` - `case mirrorVertical = 5` ## 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). ### Properties - ```swift public let code : ValidationCode ``` The stable, machine-readable readiness code. - ```swift public let hint : String ``` A human-readable hint describing what needs to change for a valid measurement. ## 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` - `case excessiveMotion = 12` - `case faceTooClose = 13` - `case faceTooFar = 14` - `case faceTooHigh = 15` - `case faceTooLow = 16` - `case faceNotForward = 17` ## SmartSpectraError A typed error from the SmartSpectra SDK. Thrown by ``SmartSpectraSDK/start()`` and ``SmartSpectraSDK/stop()``, and published on ``SmartSpectraSDK/error`` for async pipeline failures. ### Properties - ```swift public let code : Code ``` The error category. - ```swift public let message : String ``` A human-readable description of what went wrong. - ```swift public let retryable : Bool ``` Whether the operation that produced this error can be retried. - ```swift public var errorDescription : String? ``` A human-readable description of the error; returns ``message``. ## 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. - `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` - `case timestampGap = 11` ## CameraSelection A camera request resolved when capture starts. Explicit selections never fall back. - `` case `default` `` - `case front` - `case back` - `case byId(String)` ## CameraFacing Direction reported by the camera. External cameras may report `.unknown`. - `case front` - `case back` - `case unknown` ## CameraLensType Best-effort lens classification, independent of digital zoom. Missing metadata and cameras combining multiple lenses report `.unknown`. - `case unknown` - `case wideAngle` - `case ultraWide` - `case telephoto` ## CameraInfo A discoverable camera. IDs are opaque and device-local; availability can change. ### Initializers - ```swift public init (id: String, name: String? = nil, facing: CameraFacing = .unknown, lensType: CameraLensType = .unknown) ``` ### Properties - ```swift public let id : String ``` - ```swift public let name : String? ``` - ```swift public let facing : CameraFacing ``` - ```swift public let lensType : CameraLensType ``` ## FrameSubmissionResult Acceptance means the pixels were consumed, not that measurement processing has finished. - `case accepted` - `case rejected(SmartSpectraError)` ## 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's Swift-side logging and the native engine. ``debug`` cannot restore debug-only statements that were compiled out of the release engine binary. Raw values are stable across SDK versions and match the C++/Android wire values. - `case debug = 0` - `case info = 1` - `case warning = 2` - `case error = 3` - `case none = 4`