API Reference

SmartSpectraSDK

Vitals measurement entry point. Owns one processing pipeline and surfaces lifecycle events via on(). Lifecycle methods throw a JS Error on failure with numeric code (a SmartSpectraErrorCode value), message, and boolean retryable properties.

Methods

• constructor(options?: SmartSpectraOptions)

• start(): void

• stop(): void

• stopAsync(): Promise<void>

• reset(): void

• waitUntilComplete(timeoutMs?: number): boolean

  Block until the session reaches a terminal state (idle or error), or the timeout elapses. Returns true if the session settled, false on timeout. timeoutMs <= 0 (the default) waits indefinitely. Use after useFile() + start() to block until end-of-file.

• destroy(): Promise<void>

  Tear down the session. Idempotent. Await before constructing a replacement session when teardown ordering matters, since native SDK state is process-global.

• requestInsight(text: string): number

  Dispatch an on-demand insight prompt; returns the request id. The matching Insight response arrives asynchronously through the 'insight' event with the same id.

• useCustomInput(frameTransform?: FrameTransformValue): this

  Select the custom frame-push input source (push frames via sendFrame() after start()). Returns this for chaining; call before start().

• useCamera(options?: CameraOptions): this

  Select a live camera as the input source. The SDK opens the camera and pumps frames internally on start() — no sendFrame() needed. Returns this for chaining. Captures in THIS process — for Electron, prefer the renderer SDK's useMediaStream().

• useFile(videoPath: string, options?: VideoFileOptions): this

  Select a pre-recorded video file as the input source. start() begins playback (non-blocking, on SDK worker threads); use waitUntilComplete() or watch 'processingStatus' for the idle transition to detect end-of-file. Returns this for chaining.

• sendFrame( buffer: Uint8Array | Buffer, width: number, height: number, stride: number, pixelFormat: PixelFormatValue, timestampUs: number, ): boolean

  Submits a raw video frame. Requires useCustomInput() + start() first.

• on(event: 'processingStatus',   callback: (status: ProcessingStatusValue) => void): this

  Register a callback for a named event. Replaces any previously registered callback for the same event. Returns this for chaining.

• on(event: 'validationStatus',   callback: (code: ValidationCodeValue, timestampUs: number, hint: string) => void): this

• on(event: 'metrics',            callback: (buf: Buffer, timestampUs: number) => void): this

• on(event: 'accumulatedMetrics', callback: (buf: Buffer, timestampUs: number) => void): this

• on(event: 'insight',            callback: (buf: Buffer, requestId: number) => void): this

• on(event: 'error',              callback: (code: SmartSpectraErrorCodeValue, message: string, retryable: boolean) => void): this

• on(event: 'frameSentThrough',   callback: (sent: boolean, timestampUs: number) => void): this

• on(event: 'videoOutput',        callback: (buf: Buffer, width: number, height: number, stride: number, pixelFormat: PixelFormatValue, timestampUs: number) => void): this

Properties

• static readonly version: string

• readonly processingStatus: ProcessingStatusValue

SmartSpectraOptions

apiKey?: string

requestedMetrics?: number[]

MetricType integer codes. Defaults to breathingMetrics when omitted.

enableAccumulatedOutput?: boolean

VideoFileOptions

timestampsPath?: string | null

interframeDelayMs?: number

startOffsetMs?: number

maxDurationMs?: number

frameTransform?: FrameTransformValue

CameraOptions

deviceIndex?: number

width?: number

height?: number

fps?: number

frameTransform?: FrameTransformValue

FrameTransform

• readonly kNone: 0
• readonly kRotate90CW: 1
• readonly kRotate90CCW: 2
• readonly kRotate180: 3
• readonly kMirrorHorizontal: 4
• readonly kMirrorVertical: 5

PixelFormat

• readonly kRGB: 0
• readonly kBGR: 1
• readonly kRGBA: 2
• readonly kBGRA: 3
• readonly kNV12: 4
• readonly kNV21: 5
• readonly kYUYV: 6

ProcessingStatus

• readonly kUninitialized: 0
• readonly kIdle: 1
• readonly kStarting: 2
• readonly kRunning: 3
• readonly kStopping: 4
• readonly kError: 5

ValidationCode

• readonly kOk: 0
• readonly kNoFaceFound: 1
• readonly kMultipleFacesFound: 2
• readonly kFaceNotCentered: 3
• readonly kFaceSizeOutOfRange: 4
• readonly kTooDark: 5
• readonly kTooBright: 6
• readonly kChestNotVisible: 7
• readonly kCameraTuning: 10
• readonly kFrameRateTooLow: 11

SmartSpectraErrorCode

• readonly kOk: 0
• readonly kInvalidState: 1
• readonly kAuthenticationFailed: 2
• readonly kConfigurationFailed: 3
• readonly kCreditExhausted: 4
• readonly kNetworkError: 5
• readonly kServerError: 6
• readonly kInputUnavailable: 7
• readonly kProcessingFailed: 8
• readonly kFrameConversionFailed: 9
• readonly kNonMonotonicTimestamp: 10
• readonly kTimestampGap: 11

decodeMetrics()

Deserialize a protobuf Metrics buffer from the 'metrics' or 'accumulatedMetrics' events. Returns the decoded message if a class has been registered via setMetricsClass, otherwise the raw Buffer.

export declare function decodeMetrics(buf: Buffer): unknown

setMetricsClass()

Register a protobuf Metrics class exposing deserializeBinary(buf) (google-protobuf) or decode(buf) (protobufjs). decodeMetrics() will use it; otherwise the raw Buffer is returned.

export declare function setMetricsClass(cls: unknown): void