Methods

Reference for all public methods on the CircadifySDK instance.

`measureVitals(options?)`

Runs the full measurement pipeline: camera access, face detection, frame capture, upload, and server-side inference. Returns a promise that resolves with the vital signs result.

The SDK is headless — you render the <video> element and any overlays. The SDK drives the camera, extraction, and upload, and emits per-frame events via the callbacks set on the constructor.

const result = await sdk.measureVitals({
  videoElement: document.getElementById('preview') as HTMLVideoElement,
  demographics: { age: 35, sex: 'M', fitzpatrick: 3 },
  signal: abortController.signal,
});

Parameters (MeasurementOptions):

Name	Type	Required	Description
`videoElement`	`HTMLVideoElement`	No	Caller-owned `<video>`. The SDK binds the camera stream to it. If omitted, the SDK creates an off-DOM video and emits `onCameraReady` with the stream.
`demographics`	`Demographics`	No	User demographics to improve accuracy.
`signal`	`AbortSignal`	No	Cancel the measurement mid-scan via `AbortController`.

Demographics:

interface Demographics {
  age?: number;
  sex?: 'M' | 'F';
  fitzpatrick?: 1 | 2 | 3 | 4 | 5 | 6;
}

Returns: Promise<VitalSignsResult>

interface VitalSignsResult {
  heartRate: number;         // BPM (always present)
  hrv?: number;              // Heart rate variability (ms)
  respiratoryRate?: number;  // Breaths per minute
  spo2?: number;             // Blood oxygen saturation (%)
  systolicBp?: number;       // Systolic blood pressure (mmHg)
  diastolicBp?: number;      // Diastolic blood pressure (mmHg)
  confidence: number;        // 0-1 measurement reliability
  sessionId: string;         // Unique session identifier
  timestamp: number;         // Unix timestamp (ms)
}

Errors thrown:

Error Code	When
`MISSING_API_KEY`	No API key was provided
`CAMERA_PERMISSION_DENIED`	User denied camera access
`CAMERA_NOT_AVAILABLE`	No camera found on the device
`CAMERA_IN_USE`	Camera is already in use by another application
`FACE_NOT_DETECTED`	No face found in the camera feed
`FACE_DETECTION_TIMEOUT`	No face detected within 30 seconds
`QUALITY_TOO_LOW`	Capture quality was too poor to produce results
`WASM_LOAD_FAILED`	Vision engine modules failed to load
`BROWSER_NOT_SUPPORTED`	Browser lacks required APIs (WebAssembly, MediaDevices)
`RATE_LIMITED`	Hourly request limit exceeded
`CANCELLED`	The `AbortController` signal was triggered
`NETWORK_ERROR`	Network request failed (retryable)
`UPLOAD_FAILED`	Upload to cloud storage failed (retryable)
`TIMEOUT`	Polling for results timed out (retryable)

Building UI from per-frame callbacks

Render quality meters, face overlays, and progress UI from the callbacks set on the SDK constructor. See Configuration for the full list — the most common are onProgress, onQualityState, and onLandmarks.

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  onProgress:     (e)  => updateProgressBar(e.phase, e.percent),
  onQualityState: (q)  => updateQualityMeters(q),
  onLandmarks:    (lm) => renderFaceMesh(lm),
});

const result = await sdk.measureVitals({ videoElement: myVideoEl });

`checkCameraAccess()`

Checks whether the device has a camera and camera permissions are available. Does not prompt the user for permission.

const hasCamera = await sdk.checkCameraAccess();

if (!hasCamera) {
  showMessage('Camera not available on this device.');
}

Returns: Promise<boolean>

`getDeviceCapabilities()`

Returns information about the device’s camera support.

const capabilities = sdk.getDeviceCapabilities();

console.log(capabilities.hasCamera);         // true
console.log(capabilities.hasFrontCamera);    // true
console.log(capabilities.isSecureContext);   // true (HTTPS)

Returns: DeviceCapabilities

interface DeviceCapabilities {
  hasCamera: boolean;
  hasFrontCamera: boolean;
  isSecureContext: boolean;
  mediaDevicesSupported: boolean;
  maxResolution?: { width: number; height: number };
}

`cancel()`

Cancels a measurement that is currently in progress. Equivalent to aborting the AbortController signal.

sdk.cancel();

The measureVitals() promise will reject with a CircadifyError with code CANCELLED.

`destroy()`

Releases all resources: stops active camera streams and unloads WASM modules.

sdk.destroy();

Call destroy() when the SDK is no longer needed — for example, on component unmount.

React cleanup example

useEffect(() => {
  const sdk = new CircadifySDK({ apiKey: 'ck_live_your_key_here' });
  // ...use sdk
  return () => sdk.destroy();
}, []);

@circadify/react’s <CircadifyProvider> does this automatically when it unmounts.

Next Steps

Configuration — All SDK options and per-frame callbacks
Events — Progress and quality events
Error Codes — Full error reference