Vanilla JavaScript

npm install @facesmash/sdk

// Factory function (recommended)
import { createFaceSmash } from '@facesmash/sdk';
const client = createFaceSmash(config);

// Class constructor (equivalent)
import { FaceSmashClient } from '@facesmash/sdk';
const client = new FaceSmashClient(config);

init(onProgress?: (progress: number) => void): Promise<boolean>

import { createFaceSmash } from '@facesmash/sdk';

const client = createFaceSmash({
  apiUrl: 'https://api.facesmash.app',
  debug: true,
});

const success = await client.init((progress) => {
  document.getElementById('loader').textContent = `Loading: ${progress}%`;
});

if (!success) {
  console.error('Failed to load models — check WebGL support');
}

readonly isReady: boolean

if (!client.isReady) {
  alert('Face recognition is still loading');
  return;
}

login(images: string[]): Promise<LoginResult>

interface LoginResult {
  success: boolean;
  user?: UserProfile;    // Present on success
  similarity?: number;   // 0–1 match score (present on success or partial match)
  error?: string;        // Present on failure
}

interface UserProfile {
  id: string;            // PocketBase record ID (e.g., "a1b2c3d4e5f6")
  name: string;          // Display name
  email: string;         // Email address
  face_embedding: number[]; // 128-dimensional descriptor as plain array
  created: string;       // ISO date (e.g., "2026-03-07 20:15:00.000Z")
  updated: string;       // ISO date
}

const result = await client.login(images);

if (result.success) {
  console.log('Welcome back,', result.user.name);
  console.log('Email:', result.user.email);
  console.log('User ID:', result.user.id);
  console.log('Similarity:', result.similarity); // e.g., 0.78
} else {
  console.error('Login failed:', result.error);
  // Possible errors:
  // - "No face detected in any image"
  // - "Face quality too low. Improve lighting and face the camera directly."
  // - "No registered users found"
  // - "Face not recognized."
  // - "Face partially matched but did not meet security threshold."
}

register(name: string, images: string[], email?: string): Promise<RegisterResult>

interface RegisterResult {
  success: boolean;
  user?: UserProfile;  // Present on success
  error?: string;      // Present on failure
}

const result = await client.register('Jane Doe', images, 'jane@example.com');

if (result.success) {
  console.log('Registered:', result.user.name);
  console.log('User ID:', result.user.id);
  console.log('Email:', result.user.email);
} else {
  console.error('Registration failed:', result.error);
  // Possible errors:
  // - "No face detected in any image"
  // - "Face quality too low for registration."
  // - "This face is already registered to John Doe"
}

analyzeFace(imageData: string): Promise<FaceAnalysis | null>

interface FaceAnalysis {
  descriptor: Float32Array;           // Raw 128-D face embedding
  normalizedDescriptor: Float32Array; // L2-normalized version
  confidence: number;                 // SSD detection confidence (0–1)
  qualityScore: number;               // Composite quality (0–1)
  lightingScore: number;              // Lighting quality (0–1)
  headPose: HeadPose;                 // Yaw, pitch, roll, isFrontal
  faceSizeCheck: FaceSizeCheck;       // Size validation
  eyeAspectRatio: number;            // Eye openness (~0.2–0.35 for open eyes)
  rejectionReason?: string;           // Present if face should not be used
}

interface HeadPose {
  yaw: number;       // Left/right (-1 to 1, 0 = center)
  pitch: number;     // Up/down (-1 to 1, 0 = center)
  roll: number;      // Tilt (radians)
  isFrontal: boolean; // true if |yaw| < 0.35, |pitch| < 0.4, |roll| < 0.25
}

interface FaceSizeCheck {
  isValid: boolean;  // true if face is 2–65% of frame and >= 80×80px
  ratio: number;     // face area / frame area
  reason?: string;   // "Face too far from camera", "Face too close", etc.
}

const analysis = await client.analyzeFace(base64Image);

if (!analysis) {
  console.log('No face detected in image');
} else if (analysis.rejectionReason) {
  console.log('Face rejected:', analysis.rejectionReason);
} else {
  console.log('Quality:', (analysis.qualityScore * 100).toFixed(0) + '%');
  console.log('Confidence:', (analysis.confidence * 100).toFixed(0) + '%');
  console.log('Lighting:', (analysis.lightingScore * 100).toFixed(0) + '%');
  console.log('Frontal:', analysis.headPose.isFrontal);
  console.log('Eyes open:', analysis.eyeAspectRatio > 0.2);
  console.log('Face size valid:', analysis.faceSizeCheck.isValid);
}

on(listener: FaceSmashEventListener): () => void

const unsub = client.on((event) => {
  console.log('[FaceSmash]', event.type, event);
});

// Later: stop listening
unsub();

readonly config: ResolvedConfig

console.log(client.config.apiUrl);               // "https://api.facesmash.app"
console.log(client.config.modelUrl);              // "https://cdn.jsdelivr.net/npm/@vladmandic/face-api/model"
console.log(client.config.matchThreshold);        // 0.45
console.log(client.config.minQualityScore);       // 0.2
console.log(client.config.minDetectionConfidence); // 0.3
console.log(client.config.maxTemplatesPerUser);   // 10
console.log(client.config.debug);                 // false

readonly pb: PocketBase

// Query all registered users
const users = await client.pb.collection('user_profiles').getFullList();
console.log('Registered users:', users.length);

// Get a specific user's templates
const templates = await client.pb.collection('face_templates').getList(1, 50, {
  filter: 'user_email="jane@example.com"',
  sort: '-quality_score',
});
console.log('Templates:', templates.items.length);

// Get recent sign-in logs
const logs = await client.pb.collection('sign_in_logs').getList(1, 20, {
  sort: '-created',
});

type FaceSmashEvent =
  | { type: 'models-loading'; progress: number }
  | { type: 'models-loaded' }
  | { type: 'models-error'; error: string }
  | { type: 'face-detected'; analysis: FaceAnalysis }
  | { type: 'face-lost' }
  | { type: 'login-start' }
  | { type: 'login-success'; user: UserProfile; similarity: number }
  | { type: 'login-failed'; error: string; bestSimilarity?: number }
  | { type: 'register-start' }
  | { type: 'register-success'; user: UserProfile }
  | { type: 'register-failed'; error: string };

type FaceSmashEventListener = (event: FaceSmashEvent) => void;

const statusEl = document.getElementById('status');
const progressEl = document.getElementById('progress');

client.on((event) => {
  switch (event.type) {
    case 'models-loading':
      progressEl.style.width = `${event.progress}%`;
      statusEl.textContent = 'Loading face recognition...';
      break;
    case 'models-loaded':
      statusEl.textContent = 'Ready — look at the camera';
      break;
    case 'models-error':
      statusEl.textContent = `Error: ${event.error}`;
      break;
    case 'login-start':
      statusEl.textContent = 'Analyzing your face...';
      break;
    case 'login-success':
      statusEl.textContent = `Welcome back, ${event.user.name}! (${(event.similarity * 100).toFixed(0)}% match)`;
      break;
    case 'login-failed':
      statusEl.textContent = event.bestSimilarity
        ? `Not recognized (best match: ${(event.bestSimilarity * 100).toFixed(0)}%)`
        : `Not recognized: ${event.error}`;
      break;
    case 'register-success':
      statusEl.textContent = `Registered as ${event.user.name}!`;
      break;
    case 'register-failed':
      statusEl.textContent = `Registration failed: ${event.error}`;
      break;
  }
});

import {
  loadModels,
  areModelsLoaded,
  extractDescriptor,
  analyzeFace,
  processImages,
  normalizeDescriptor,
} from '@facesmash/sdk';

loadModels(config: ResolvedConfig, onProgress?: (p: number) => void): Promise<boolean>

import { loadModels } from '@facesmash/sdk';

const config = {
  apiUrl: 'https://api.facesmash.app',
  modelUrl: 'https://cdn.jsdelivr.net/npm/@vladmandic/face-api/model',
  minDetectionConfidence: 0.3,
  matchThreshold: 0.45,
  minQualityScore: 0.2,
  maxTemplatesPerUser: 10,
  debug: false,
};

await loadModels(config, (p) => console.log(`${p}%`));

areModelsLoaded(): boolean

extractDescriptor(
  input: string | HTMLVideoElement | HTMLCanvasElement | HTMLImageElement,
  config: ResolvedConfig
): Promise<Float32Array | null>

import { extractDescriptor } from '@facesmash/sdk';

// From a base64 string
const desc1 = await extractDescriptor('data:image/jpeg;base64,...', config);

// From a video element (live webcam)
const desc2 = await extractDescriptor(videoElement, config);

// From a canvas
const desc3 = await extractDescriptor(canvasElement, config);

// Returns Float32Array(128) or null if no face found

analyzeFace(imageData: string, config: ResolvedConfig): Promise<FaceAnalysis | null>

processImages(images: string[], config: ResolvedConfig): Promise<Float32Array | null>

normalizeDescriptor(descriptor: Float32Array): Float32Array

import {
  calculateSimilarity,
  facesMatch,
  enhancedMatch,
  multiTemplateMatch,
  calculateLearningWeight,
} from '@facesmash/sdk';

calculateSimilarity(d1: Float32Array, d2: Float32Array): number

const similarity = calculateSimilarity(descriptor1, descriptor2);
console.log(`${(similarity * 100).toFixed(1)}% similar`);

facesMatch(d1: Float32Array, d2: Float32Array, threshold?: number): boolean

enhancedMatch(
  d1: Float32Array,
  d2: Float32Array,
  baseThreshold?: number,     // default: 0.45
  confidenceBoost?: number,   // default: 0
  lightingScore?: number      // default: 0.5
): MatchResult

interface MatchResult {
  isMatch: boolean;
  similarity: number;
  adaptedThreshold: number;
}

const result = enhancedMatch(newDescriptor, storedDescriptor, 0.45, 0, 0.7);
console.log(result);
// { isMatch: true, similarity: 0.72, adaptedThreshold: 0.47 }

multiTemplateMatch(
  newDescriptor: Float32Array,
  templates: { descriptor: Float32Array; quality: number; weight: number }[],
  baseThreshold: number,
  lightingScore?: number
): MultiTemplateMatchResult

interface MultiTemplateMatchResult {
  isMatch: boolean;
  bestSimilarity: number;
  avgSimilarity: number;   // Quality-weighted average
  matchCount: number;       // How many templates matched
}

const templates = [
  { descriptor: template1, quality: 0.9, weight: 1.5 },
  { descriptor: template2, quality: 0.7, weight: 1.0 },
  { descriptor: template3, quality: 0.85, weight: 1.2 },
];

const result = multiTemplateMatch(newDescriptor, templates, 0.45, 0.8);
console.log(result);
// { isMatch: true, bestSimilarity: 0.78, avgSimilarity: 0.71, matchCount: 3 }

calculateLearningWeight(
  qualityScore: number,
  lightingScore: number,
  confidence: number
): number   // 0.1 to 3.0

async function captureFromWebcam(count = 3, delay = 500) {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: { width: 640, height: 480, facingMode: 'user' },
  });

  const video = document.createElement('video');
  video.srcObject = stream;
  video.autoplay = true;
  video.playsInline = true;
  await new Promise((r) => video.addEventListener('playing', r, { once: true }));

  const canvas = document.createElement('canvas');
  canvas.width = video.videoWidth;
  canvas.height = video.videoHeight;
  const ctx = canvas.getContext('2d');

  const images = [];
  for (let i = 0; i < count; i++) {
    ctx.drawImage(video, 0, 0);
    images.push(canvas.toDataURL('image/jpeg', 0.9));
    if (i < count - 1) await new Promise((r) => setTimeout(r, delay));
  }

  stream.getTracks().forEach((t) => t.stop());
  return images;
}

<div id="camera-container">
  <video id="camera" autoplay playsinline muted></video>
  <div id="status">Initializing...</div>
  <div id="progress-bar" style="width: 0%; height: 4px; background: #10b981;"></div>
  <button id="login-btn" disabled>Sign In</button>
</div>

<script type="module">
import { createFaceSmash } from '@facesmash/sdk';

const client = createFaceSmash({
  apiUrl: 'https://api.facesmash.app',
  debug: true,
});

const video = document.getElementById('camera');
const status = document.getElementById('status');
const progress = document.getElementById('progress-bar');
const loginBtn = document.getElementById('login-btn');

// Track events
client.on((event) => {
  switch (event.type) {
    case 'models-loading':
      progress.style.width = `${event.progress}%`;
      break;
    case 'models-loaded':
      status.textContent = 'Ready — click Sign In';
      break;
    case 'login-start':
      status.textContent = 'Scanning...';
      loginBtn.disabled = true;
      break;
    case 'login-success':
      status.textContent = `Welcome, ${event.user.name}!`;
      break;
    case 'login-failed':
      status.textContent = `Failed: ${event.error}`;
      loginBtn.disabled = false;
      break;
  }
});

// Init models
await client.init();

// Start camera
const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: 640, height: 480, facingMode: 'user' },
});
video.srcObject = stream;
loginBtn.disabled = false;

// Capture + login on click
loginBtn.addEventListener('click', async () => {
  const canvas = document.createElement('canvas');
  canvas.width = video.videoWidth;
  canvas.height = video.videoHeight;
  const ctx = canvas.getContext('2d');

  const images = [];
  for (let i = 0; i < 3; i++) {
    ctx.drawImage(video, 0, 0);
    images.push(canvas.toDataURL('image/jpeg', 0.9));
    await new Promise((r) => setTimeout(r, 500));
  }

  const result = await client.login(images);

  if (result.success) {
    // Redirect or update UI
    stream.getTracks().forEach((t) => t.stop());
  }
});
</script>

try {
  // This throws if models aren't loaded
  const result = await client.login(images);
} catch (err) {
  // "FaceSmash models not loaded. Call client.init() first."
  console.error(err.message);
}

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { createFaceSmash } from '@facesmash/sdk';

const client = createFaceSmash({ apiUrl: 'https://api.facesmash.app' });
const isReady = ref(false);
const progress = ref(0);

onMounted(async () => {
  await client.init((p) => { progress.value = p; });
  isReady.value = true;
});

onUnmounted(() => {
  // Cleanup if needed
});
</script>

<script lang="ts">
  import { onMount } from 'svelte';
  import { createFaceSmash } from '@facesmash/sdk';

  const client = createFaceSmash({ apiUrl: 'https://api.facesmash.app' });
  let isReady = false;
  let progress = 0;

  onMount(async () => {
    await client.init((p) => { progress = p; });
    isReady = true;
  });
</script>

import { Component, OnInit } from '@angular/core';
import { createFaceSmash } from '@facesmash/sdk';

@Component({ selector: 'app-face-auth', template: '...' })
export class FaceAuthComponent implements OnInit {
  client = createFaceSmash({ apiUrl: 'https://api.facesmash.app' });
  isReady = false;
  progress = 0;

  async ngOnInit() {
    await this.client.init((p) => { this.progress = p; });
    this.isReady = true;
  }
}