---
title: Node.js API Reference
description: API reference for the SmartSpectra Node.js SDK — the SmartSpectraSDK class, events, metrics decoding, 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/nodejs/api-reference
> Index of all pages: https://presagetech.com/docs/smartspectra-sdk/llms.txt

<!-- Auto-generated by scripts/generate-api.ts — do not edit manually. -->

## 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.

```ts
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

- ```typescript
  static availableCameras(): CameraInfo[]
  ```

  No SDK instance, authentication, or capture required. Throws when discovery is unsupported.

- ```typescript
  constructor(options?: SmartSpectraOptions)
  ```

- ```typescript
  start(): void
  ```

  Initialize and begin the input configured with useCamera, useCustomInput, or useFile.

- ```typescript
  stop(): void
  ```

  Request the session to stop. Idempotent.

- ```typescript
  stopAsync(): Promise<void>
  ```

  Async variant of stop() — the native stop blocks until the pipeline drains; prefer this in event-loop-sensitive contexts.

- ```typescript
  reset(): void
  ```

  Rebuild after kError. Clears the source unless useCamera(selection, options) opted into retention. After typed selection, throws kInvalidState while stopAsync() is pending; await it before resetting.

- ```typescript
  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.

- ```typescript
  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.

- ```typescript
  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.

- ```typescript
  useCustomInput(frameTransform?: FrameTransformValue): this
  ```

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

- ```typescript
  useCamera(selection: CameraSelection, options?: Omit<CameraOptions, 'deviceIndex'>): 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()`. Select while stopped; explicit requests never fall back. Selection is resolved at startup and retained across stop/start/reset. Invalid or busy requests preserve the previous source. Pass CameraSelection.default for SDK selection.

- ```typescript
  useCamera(options?: CameraOptions): this
  ```

  Select a camera by legacy index (default 0). Reset clears the source. @deprecated Pass an explicit CameraSelection and separate capture options instead.

- ```typescript
  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.

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

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

- ```typescript
  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.

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

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

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

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

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

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

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

### Properties

- ```typescript
  static readonly version: string
  ```

  SDK package version.

- ```typescript
  readonly processingStatus: ProcessingStatusValue
  ```

  Current ProcessingStatus integer value.

## SmartSpectraOptions

Options passed to the SmartSpectra constructor.

```typescript
apiKey?: string
```

API key for server-validated auth.

```typescript
requestedMetrics?: number[]
```

MetricType integer codes. Defaults to `breathingMetrics` when omitted.

```typescript
enableAccumulatedOutput?: boolean
```

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

```typescript
logLevel?: SmartSpectraLogLevelValue
```

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

```typescript
enableTelemetry?: boolean
```

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

## VideoFileOptions

Playback options for useFile().

```typescript
timestampsPath?: string | null
```

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

```typescript
interframeDelayMs?: number
```

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

```typescript
startOffsetMs?: number
```

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

```typescript
maxDurationMs?: number
```

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

```typescript
frameTransform?: FrameTransformValue
```

Spatial transform applied to every frame.

## CameraOptions

Capture settings, separate from camera selection.

```typescript
deviceIndex?: number
```

@deprecated Use useCamera(CameraSelection.byId(id), options) instead.

```typescript
width?: number
```

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

```typescript
height?: number
```

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

```typescript
fps?: number
```

Capture frame rate; omit/0 = SDK default.

```typescript
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`

## CameraInfo

Discovery snapshot. IDs are opaque and platform-local; rediscover before reuse.

```typescript
readonly id: string
```

```typescript
readonly name: string | null
```

```typescript
readonly facing: CameraFacing
```

```typescript
readonly lensType: CameraLensType
```

## 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`

## MetricType

MetricType integer codes accepted by `requestedMetrics`. Runtime values are generated from protobuf.

- `readonly CHEST_BREATHING: 0`
- `readonly ABDOMEN_BREATHING: 1`
- `readonly BREATHING_RATE: 2`
- `readonly BREATHING_AMPLITUDE: 3`
- `readonly APNEA: 4`
- `readonly RESPIRATORY_LINE_LENGTH: 5`
- `readonly BASELINE: 6`
- `readonly INHALE_EXHALE_RATIO: 7`
- `readonly EDA_TRACE: 10`
- `readonly FACE_LANDMARKS: 11`
- `readonly BLINKING: 12`
- `readonly TALKING: 13`
- `readonly EXPRESSIONS: 14`
- `readonly PULSE_RATE: 15`
- `readonly ARTERIAL_PRESSURE_TRACE: 16`
- `readonly HRV: 17`

## CameraSelection

- `readonly default: Readonly<{ kind: 'default' }>`
- `readonly front: Readonly<{ kind: 'front' }>`
- `readonly back: Readonly<{ kind: 'back' }>`
- `readonly byId: (id: string) => Readonly<{ kind: 'byId'; id: string }>`

## ProcessingStatusValue

```typescript
export type ProcessingStatusValue = typeof ProcessingStatus[keyof typeof ProcessingStatus];
```

## SmartSpectraLogLevelValue

```typescript
export type SmartSpectraLogLevelValue = typeof SmartSpectraLogLevel[keyof typeof SmartSpectraLogLevel];
```

## PixelFormatValue

```typescript
export type PixelFormatValue = typeof PixelFormat[keyof typeof PixelFormat];
```

## ValidationCodeValue

```typescript
export type ValidationCodeValue = typeof ValidationCode[keyof typeof ValidationCode];
```

## SmartSpectraErrorCodeValue

```typescript
export type SmartSpectraErrorCodeValue = typeof SmartSpectraErrorCode[keyof typeof SmartSpectraErrorCode];
```

## FrameTransformValue

```typescript
export type FrameTransformValue = typeof FrameTransform[keyof typeof FrameTransform];
```

## MetricTypeValue

```typescript
export type MetricTypeValue = typeof MetricType[keyof typeof MetricType];
```

## CameraFacing

```typescript
export type CameraFacing = 'front' | 'back' | 'unknown';
```

## CameraLensType

Best-effort classification. Missing metadata and multi-lens cameras are unknown; independent of digital zoom.

```typescript
export type CameraLensType = 'unknown' | 'wideAngle' | 'ultraWide' | 'telephoto';
```