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.

import { SmartSpectraSDK, PixelFormat, decodeMetrics } from '@smartspectra/node-sdk';
const sdk = new SmartSpectraSDK({ apiKey: 'YOUR_KEY' });
sdk.on('metrics', (buf, ts) => console.log(decodeMetrics(buf)));
sdk.useCustomInput();
sdk.start();
sdk.sendFrame(rgbBuf, width, height, stride, PixelFormat.kRGB, timestampUs);
await sdk.destroy();

Methods

constructor(options?: SmartSpectraOptions)

```
start(): void
```
Initialize and begin a custom-input session.
```
stop(): void
```
Request the session to stop. Idempotent.
```
stopAsync(): Promise<void>
```
Async variant of stop() — the native stop blocks until the pipeline drains; prefer this in event-loop-sensitive contexts.
```
reset(): void
```
Rebuild the processing pipeline after kError; source must be reconfigured before next start().
```
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
```
SDK package version.

readonly processingStatus: ProcessingStatusValue

Current ProcessingStatus integer value.

SmartSpectraOptions

Options passed to the SmartSpectra constructor.

apiKey?: string

API key for server-validated auth.

requestedMetrics?: number[]

MetricType integer codes. Defaults to breathingMetrics when omitted.

enableAccumulatedOutput?: boolean

Also emit an accumulated metrics packet at the end of each session.

logLevel?: SmartSpectraLogLevelValue

Verbosity of SDK logging, applied when the session initializes. Defaults to SmartSpectraLogLevel.kWarning (warnings and errors only).

enableTelemetry?: boolean

Aggregate SDK telemetry. Defaults to true; set false to opt out.

VideoFileOptions

Playback options for useFile().

timestampsPath?: string | null

Path to a per-frame timestamps file (one timestamp per line).

interframeDelayMs?: number

Throttle between frames in ms; omit/0 = as fast as possible.

startOffsetMs?: number

Seek this far into the file before playback (ms); omit/0 = start.

maxDurationMs?: number

Stop after this much content (ms); omit/0 = no limit.

frameTransform?: FrameTransformValue

Spatial transform applied to every frame.

CameraOptions

Camera capture options for useCamera().

deviceIndex?: number

Camera device index; omit/0 = default device.

width?: number

Capture width in px; omit/0 = SDK default.

height?: number

Capture height in px; omit/0 = SDK default.

fps?: number

Capture frame rate; omit/0 = SDK default.

frameTransform?: FrameTransformValue

Spatial transform applied to every frame.

FrameTransform

Frame transform applied by the SDK to every pushed frame.

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

PixelFormat

Pixel format of a raw frame buffer passed to sendFrame().

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

ProcessingStatus

Processing lifecycle status. Integer values are stable across SDK versions.

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

ValidationCode

Measurement-readiness codes delivered via the 'validationStatus' event.

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
readonly kExcessiveMotion: 12
readonly kFaceTooClose: 13
readonly kFaceTooFar: 14
readonly kFaceTooHigh: 15
readonly kFaceTooLow: 16
readonly kFaceNotForward: 17

SmartSpectraErrorCode

Error codes on errors thrown by lifecycle methods and delivered via the 'error' event.

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

SmartSpectraLogLevel

Verbosity of SDK logging, set via the SmartSpectraSDK logLevel option. Levels are cumulative: a level shows its own messages plus everything more severe.

readonly kDebug: 0
readonly kInfo: 1
readonly kWarning: 2
readonly kError: 3
readonly kNone: 4

On this page