Configuration

The SDK accepts a configuration object when you create a new CircadifySDK instance. Only apiKey is required.

Basic Configuration

import { CircadifySDK } from '@circadify/web-sdk';

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
});

Full Configuration

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  baseUrl: 'https://api.circadify.com',
  measurementDuration: 30,
  debug: false,
  onDeviceOnly: true,

  // Per-frame callbacks for rendering custom UI:
  onProgress:        (e) => { /* phase + percent */ },
  onQualityState:    (q) => { /* full per-frame quality */ },
  onQualityWarning:  (w) => { /* transient warnings */ },
  onLandmarks:       (lm) => { /* 468 MediaPipe points */ },
  onCameraReady:     ({ stream, video }) => { /* mirror stream */ },
});

Configuration Reference

Option	Type	Default	Description
`apiKey`	`string`	—	Required. Your API key (`ck_live_*`).
`baseUrl`	`string`	`'https://api.circadify.com'`	Custom API base URL.
`measurementDuration`	`number`	`30`	Target measurement duration in seconds.
`debug`	`boolean`	`false`	Enable debug logging to the browser console.
`onDeviceOnly`	`boolean`	`true`	When true, sends `X-Circadify-On-Device: true` so the backend skips server-side fallback inference.
`onProgress`	`(e: ProgressEvent) => void`	—	Phase + percent updates throughout measurement.
`onQualityState`	`(q: QualityState) => void`	—	Full per-frame quality state (lighting, motion, pose, readiness). Use for live quality meters.
`onQualityWarning`	`(w: QualityWarning) => void`	—	Fires on transient warnings (lighting, motion, face_position, occlusion).
`onLandmarks`	`(lm: Landmark[]) => void`	—	Per-frame 468-point face mesh. Use to render your own face overlay.
`onCameraReady`	`({ stream, video }) => void`	—	Fires once after the camera is acquired. Useful for mirroring the SDK-owned video into custom UI.
`wasmConfig`	`WasmConfig`	—	Override CDN URLs for self-hosted vision engine files.

CircadifyConfig Interface

interface CircadifyConfig {
  apiKey: string;
  baseUrl?: string;
  measurementDuration?: number;
  debug?: boolean;
  onDeviceOnly?: boolean;
  onProgress?: (event: ProgressEvent) => void;
  onQualityState?: (state: QualityState) => void;
  onQualityWarning?: (warning: QualityWarning) => void;
  onLandmarks?: (landmarks: Landmark[]) => void;
  onCameraReady?: (info: { stream: MediaStream; video: HTMLVideoElement }) => void;
  wasmConfig?: WasmConfig;
}

Progress Callback

The onProgress callback fires throughout measurement with a ProgressEvent object:

interface ProgressEvent {
  percent: number;    // 0-100
  phase: 'initializing' | 'readiness' | 'capturing' | 'uploading' | 'processing';
  elapsed: number;    // Seconds since measurement started
  remaining?: number; // Estimated seconds remaining (when available)
}

Phase	Progress	What’s happening
`initializing`	0–5%	Creating session, loading vision engine
`readiness`	5–10%	Opening camera, waiting for quality checks to pass
`capturing`	10–60%	Capturing and preprocessing frames
`uploading`	60–80%	Uploading preprocessed data
`processing`	80–100%	Backend inference running

Quality State Callback

The onQualityState callback fires every frame during readiness and capture with the full quality picture. Use it to drive live quality meters or pills.

interface QualityState {
  lighting: { brightness: number; stability: number; isTooDark: boolean; isTooBright: boolean; isUnstable: boolean; isOk: boolean };
  motion:   { motionMagnitude: number; isStill: boolean };
  pose:     { yaw: number; pitch: number; isFacingForward: boolean };
  isReady:  boolean;
  messages: string[];
}

Quality Warning Callback

The onQualityWarning callback fires on transient quality drops:

interface QualityWarning {
  type: 'lighting' | 'motion' | 'face_position' | 'occlusion';
  message: string;
  severity: 'low' | 'medium' | 'high';
}

Use this for short-lived toasts (“Hold still”, “Move to better lighting”). For sustained UI state, prefer onQualityState.

Landmarks Callback

The onLandmarks callback emits the full 468-point face mesh from MediaPipe every frame. Use it to render your own face overlay or thermal glow effect.

interface Landmark {
  x: number; // 0-1 normalized
  y: number; // 0-1 normalized
  z: number; // depth (relative)
}

Camera Ready Callback

When you don’t pass a videoElement to measureVitals(), the SDK creates an off-DOM <video> and reads from it directly. onCameraReady fires once with the live stream so you can mirror it into your own UI:

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  onCameraReady: ({ stream, video }) => {
    myPreviewVideo.srcObject = stream;
  },
});

Self-Hosting WASM

For air-gapped or regulated environments, host the vision engine files on your own infrastructure:

interface WasmConfig {
  visionWasmUrl?: string;
  visionModelUrl?: string;
  geometryEngineUrl?: string;
}

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  wasmConfig: {
    visionWasmUrl: 'https://your-cdn.example.com/wasm/',
    visionModelUrl: 'https://your-cdn.example.com/models/',
    geometryEngineUrl: 'https://your-cdn.example.com/geometry.js',
  },
});

Contact support@circadify.com for the WASM distribution package.

Next Steps

Methods — SDK method reference
Events — Event handling and callbacks
Error Codes — Error handling reference