@circadify/sdk

Official Circadify SDK for Web applications. Measure vital signs contactlessly using your device's camera.

Face detection and ROI extraction happen on-device — only 72×72 pixel patches are uploaded, never raw video.

Installation

npm install @circadify/sdk

You'll need an API key to use the SDK. Sign up at developer.circadify.com after reaching out to us at circadify.com/contact-us.

Quick Start

With Built-in Scanning UI

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

const circadify = new CircadifySDK({
  apiKey: 'YOUR_API_KEY',
});

// SDK mounts video + face guide + progress bar in your container
const result = await circadify.measureVitals({
  container: document.getElementById('scan-container'),
});

console.log(result.heartRate, 'BPM');

Headless Mode (No UI)

const circadify = new CircadifySDK({
  apiKey: 'YOUR_API_KEY',
  onProgress: (event) => console.log(`${event.phase}: ${event.percent}%`),
});

// No container = no UI rendered, just callbacks
const result = await circadify.measureVitals();

Configuration Options

const circadify = new CircadifySDK({
  apiKey: 'YOUR_API_KEY',

  // Optional
  baseUrl: 'https://api.circadify.com',
  measurementDuration: 30,
  debug: true,

  // Callbacks
  onProgress: (event) => {
    console.log(`${event.phase}: ${event.percent}%`);
  },
  onQualityWarning: (warning) => {
    console.log(`Quality issue: ${warning.message}`);
  },

  // Self-host WASM files (optional)
  wasmConfig: {
    mediapipeWasmUrl: 'https://your-cdn.com/mediapipe/wasm',
    mediapipeModelUrl: 'https://your-cdn.com/mediapipe/face_landmarker.task',
    opencvUrl: 'https://your-cdn.com/opencv.js',
  },
});

Measurement Options

const result = await circadify.measureVitals({
  // Mount built-in scanning UI in this element
  container: document.getElementById('scan'),

  // Customize scanning UI
  ui: {
    showFaceGuide: true,          // Face oval overlay
    showThermalGlow: true,        // Thermal glow animation during scan
    showQualityIndicators: true,  // Status banner
    accentColor: '#00D4FF',       // UI accent color
    borderRadius: '16px',         // Video container radius
  },

  // Improve accuracy with demographics
  demographics: { age: 35, sex: 'M', fitzpatrick: 3 },

  // Cancellation
  signal: abortController.signal,
});

API

measureVitals(options?): Promise<VitalSignsResult>

Starts measurement. Pass container for built-in UI, omit for headless mode.

checkCameraAccess(): Promise<boolean>

Checks camera availability.

getDeviceCapabilities(): DeviceCapabilities

Returns device camera info.

destroy(): void

Cleans up all resources (WASM, camera, UI).

Types

interface VitalSignsResult {
  heartRate: number;
  hrv?: number;
  respiratoryRate?: number;
  spo2?: number;
  systolicBp?: number;
  diastolicBp?: number;
  confidence: number;       // 0-1
  timestamp: number;
  sessionId: string;
}

How It Works

1. WASM loads — MediaPipe Face Mesh + OpenCV.js from CDN (~6MB, cached)
2. Quality gate — Face detected, lighting/motion/pose checks pass
3. Frame capture — 30fps loop extracts 3 face ROIs per frame (forehead, cheeks)
4. Binary encoding — 720 frames × 12 channels × 72×72 → ~44.8MB tensor
5. Upload + inference — Binary tensor uploaded, server returns vital signs

Browser Support

Browser	Minimum
Chrome	80+
Firefox	75+
Safari	14+
Edge	80+

Requires HTTPS (or localhost) for camera access.

Bundle Size

Format	Size
ESM	~38 KB
CJS	~38 KB

WASM dependencies (~6MB) are loaded at runtime from CDN and cached by the browser.

License

MIT © A.Y. Health Technologies Inc.