@daboss2003/liveness-web 1.0.6 → 1.0.8

package/README.md

@@ -66,6 +66,98 @@ startLiveness({
 });
 ```
 
+## Embedding in your own UI
+
+By default, `startLiveness` takes over the viewport and renders its own oval frame, step dots, and instructions. If you want to drop just the camera + face frame into a slot in your own designed page (custom button, branding, copy), pass:
+
+```ts
+startLiveness({
+  container:        mySlotEl,   // your sized div (give it explicit width & height)
+  embed:            true,       // render inside container instead of full-screen
+  shape:            "circle",   // or "oval" (default)
+  showInstructions: false,      // hide built-in text/dots — your UI shows them
+  minSize:          240,        // floor on shape diameter (px) so small screens stay usable
+  theme: {
+    progressColor:      "#1a0f4d",
+    progressErrorColor: "#ff3b3b",
+    progressWidth:      4,
+    progressLineCap:    "round",
+    overlayColor:       "#5b34d6",          // fill outside the cutout — match your bg
+    overlayErrorColor:  "rgba(180,0,0,0.6)",
+  },
+  callbacks: {
+    onChallengeChanged: (i, label) => myStatus.textContent = label,
+    onFaceInOval:       (inside, reason) => { if (!inside) myStatus.textContent = reason ?? ""; },
+    onSuccess, onFailure,
+  },
+});
+```
+
+Sounds still play in `embed` mode and with `showInstructions: false` — only the visuals are hidden.
+
+A complete working example (yellow page, purple circle slot, host-owned Start button) lives at [`demo-apps/web/embed.html`](../demo-apps/web/embed.html) + [`demo-apps/web/src/embed.ts`](../demo-apps/web/src/embed.ts). Run it with:
+
+```bash
+cd demo-apps/web && npm install && npm run dev
+# open http://localhost:5173/embed.html
+```
+
+All new options are optional — omitting them gives you the original full-screen oval behaviour.
+
+## Picking which challenges run
+
+By default, all 5 challenges run in a random order. Pass `steps` to restrict to a subset (e.g. for shorter flows or A/B testing). The dot progress indicator and the progress ring both adjust to the active subset count.
+
+```ts
+import { startLiveness, type LivenessStepKey } from "@daboss2003/liveness-web";
+
+startLiveness({
+  steps: ["nod", "blink", "mouth"],   // run only these, in this set
+  shuffleSteps: true,                 // default true — randomise within the subset
+  callbacks: { /* … */ },
+});
+```
+
+Valid keys are `"left"`, `"blink"`, `"right"`, `"nod"`, `"mouth"`. Unknown keys and duplicates are dropped; an empty array falls back to all 5.
+
+`shuffleSteps: false` runs the steps in the order you pass.
+
+## Tuning individual steps
+
+Each challenge has its own thresholds — bump them up to be stricter (harder to pass, fewer false positives), or down to be more lenient.
+
+**Blink**
+
+| Field | Default | Effect |
+|---|---|---|
+| `blinkClosedThreshold` | `0.50` | Min blendshape score that counts as "eyes closed". Raise to reject squinting / glare / hooded eyelids; lower if real blinks don't register. Below ~0.35 you start catching passive eye states. |
+| `blinkOpenThreshold`   | `0.25` | Max score that counts as "eyes open". Keep a clear gap from `blinkClosedThreshold`. |
+| `blinkMinClosedMs`     | `60`   | Eyes must stay closed at least this long. Raise to require deliberate (slower) blinks. |
+| `blinkMaxDurationMs`   | `4000` | Abandon and reset if eyes stay closed longer than this. |
+
+**Head turn** — `yawTurnDelta` (degrees needed), `yawWrongDirDelta` (wrong-direction abort), `headTurnHoldMs` (sustain time).
+
+**Nod** — `nodDownDelta` (degrees chin must drop), `nodReturnFraction`, `nodReturnMaxDelta`.
+
+**Mouth** — `mouthOpenThreshold`, `mouthOpenMarThreshold`, `mouthHoldMs`.
+
+**Capture (post-success)** — `captureMaxYaw`, `captureMaxPitch`, `captureMaxMouthScore`, `captureMaxBlinkScore` (all bound how "neutral" the final frame must be).
+
+Pass any subset as part of `config`:
+
+```ts
+startLiveness({
+  config: {
+    blinkClosedThreshold: 0.55,   // tighter blink
+    blinkMinClosedMs:     100,    // require ~6 frames of closure
+    yawTurnDelta:         12,     // looser head turn
+  },
+  callbacks: { /* … */ },
+});
+```
+
+See [`engine.ts`](src/engine.ts) for the full config object and every default value.
+
 ## Notes
 
 - Uses MediaPipe Tasks Vision Web from CDN.

package/dist/engine.d.ts

@@ -26,7 +26,13 @@ export type LivenessOptions = {
     wasmUrl?: string;
     callbacks?: LivenessCallbacks;
     sounds?: LivenessSoundOptions;
+    /** Subset of challenges to run. Default: all 5. Empty array, duplicates and unknown keys fall back to all 5. */
+    steps?: LivenessStepKey[];
+    /** Shuffle the selected step order. Default true. */
+    shuffleSteps?: boolean;
 };
+/** Identifier for a liveness challenge step. Lowercase, matches the sound-key form. */
+export type LivenessStepKey = "left" | "blink" | "right" | "nod" | "mouth";
 export declare const DEFAULT_MODEL_URL = "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task";
 export declare const DEFAULT_WASM_URL = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm";
 /** Error code when CDN/assets are unavailable after retries (internet confirmed). */
@@ -50,7 +56,11 @@ export type Metrics = {
     faceCy: number;
     faceSize: number;
 };
-export declare const LIVENESS_STEP_COUNT: 5;
+/** Resolve a caller-supplied step-key array into the corresponding display labels.
+ *  Empty / undefined / all-invalid → default to all 5 steps. Duplicates are dropped. */
+export declare function resolveStepLabels(keys?: readonly LivenessStepKey[] | null): string[];
+/** Default step count (5). The active session may have fewer if `options.steps` is set. */
+export declare const LIVENESS_STEP_COUNT: number;
 export declare class LivenessEngine {
     private opts;
     private landmarker;
@@ -65,6 +75,7 @@ export declare class LivenessEngine {
     private baselineSamples;
     private blinkState;
     private blinkCloseTs;
+    private blinkSeenOpen;
     private nodState;
     private holdStart;
     private latestMetrics;
@@ -84,6 +95,8 @@ export declare class LivenessEngine {
     private clearSessionTimeout;
     private playGoodSound;
     private playCaptureSound;
+    /** Number of challenge steps in the active session (after applying `options.steps`). */
+    get stepCount(): number;
     start(): Promise<void>;
     stop(): void;
     private stopDetectionOnly;

package/dist/engine.js

@@ -61,21 +61,35 @@ function isRetriableCdnError(error) {
         return true;
     return false;
 }
-const STEP_LABELS = [
-    "Turn your head LEFT",
-    "Blink",
-    "Turn your head RIGHT",
-    "Nod your head",
-    "Open your mouth",
+/** Canonical step ordering. Each entry pairs the sound/identifier key with its display label. */
+const STEP_DEFS = [
+    { key: "left", label: "Turn your head LEFT" },
+    { key: "blink", label: "Blink" },
+    { key: "right", label: "Turn your head RIGHT" },
+    { key: "nod", label: "Nod your head" },
+    { key: "mouth", label: "Open your mouth" },
 ];
+const STEP_LABELS = STEP_DEFS.map(s => s.label);
+const STEP_KEY_TO_LABEL = STEP_DEFS.reduce((acc, s) => { acc[s.key] = s.label; return acc; }, {});
 /** Step label → sound key (filename without .mp3). Used so the correct sound plays regardless of randomized step order. */
-const STEP_LABEL_TO_SOUND = {
-    "Turn your head LEFT": "left",
-    "Blink": "blink",
-    "Turn your head RIGHT": "right",
-    "Nod your head": "nod",
-    "Open your mouth": "mouth",
-};
+const STEP_LABEL_TO_SOUND = STEP_DEFS.reduce((acc, s) => { acc[s.label] = s.key; return acc; }, {});
+/** Resolve a caller-supplied step-key array into the corresponding display labels.
+ *  Empty / undefined / all-invalid → default to all 5 steps. Duplicates are dropped. */
+export function resolveStepLabels(keys) {
+    if (!keys || keys.length === 0)
+        return [...STEP_LABELS];
+    const seen = new Set();
+    const out = [];
+    for (const k of keys) {
+        const normalised = (typeof k === "string" ? k.toLowerCase() : "");
+        const label = STEP_KEY_TO_LABEL[normalised];
+        if (label && !seen.has(label)) {
+            seen.add(label);
+            out.push(label);
+        }
+    }
+    return out.length > 0 ? out : [...STEP_LABELS];
+}
 function shuffleArray(array) {
     const out = [...array];
     for (let i = out.length - 1; i > 0; i--) {
@@ -84,6 +98,7 @@ function shuffleArray(array) {
     }
     return out;
 }
+/** Default step count (5). The active session may have fewer if `options.steps` is set. */
 export const LIVENESS_STEP_COUNT = STEP_LABELS.length;
 // ─────────────────────────────────────────────────────────────────────────────
 //  KEY DESIGN: RELATIVE MEASUREMENT
@@ -118,10 +133,13 @@ const config = {
     nodReturnMaxDelta: 12, // cap: never require returning past 12° from baseline
     maxYawDuringNod: 40,
     // ── Blink ──────────────────────────────────────────────────────────────────
-    blinkClosedThreshold: 0.30, // blendshape score = eyes closed
-    blinkOpenThreshold: 0.25, // blendshape score = eyes open
+    // Real blinks easily hit 0.7+. Sustained squinting / glare / hooded eyelids hover at 0.25–0.40 —
+    // keep the "closed" threshold well above that band so passive eye states don't latch CLOSED.
+    blinkClosedThreshold: 0.50,
+    blinkOpenThreshold: 0.25,
     earClosedThreshold: 0.20,
     earOpenThreshold: 0.25,
+    blinkMinClosedMs: 60, // eyes must be CLOSED for at least this long — filters out single-frame noise
     blinkMaxDurationMs: 4000,
     maxYawDuringBlink: 30,
     maxPitchDuringBlink: 30,
@@ -167,6 +185,7 @@ export class LivenessEngine {
         // ── Per-step sub-state ─────────────────────────────────────────────────────
         this.blinkState = "waitingClose";
         this.blinkCloseTs = 0;
+        this.blinkSeenOpen = false; // gate: must observe at least one isEyeOpen frame before allowing a `closed` transition
         this.nodState = "neutral";
         this.holdStart = null;
         this.latestMetrics = null;
@@ -258,10 +277,16 @@ export class LivenessEngine {
             onEnded?.();
     }
     // ── Public ─────────────────────────────────────────────────────────────────
+    /** Number of challenge steps in the active session (after applying `options.steps`). */
+    get stepCount() {
+        return this.steps.length > 0 ? this.steps.length : resolveStepLabels(this.opts.steps).length;
+    }
     async start() {
         this.stopDetectionOnly();
         this.running = true;
-        this.steps = shuffleArray(STEP_LABELS).map((label, index) => ({ index, label }));
+        const selected = resolveStepLabels(this.opts.steps);
+        const ordered = this.opts.shuffleSteps === false ? selected : shuffleArray(selected);
+        this.steps = ordered.map((label, index) => ({ index, label }));
         this.stepIndex = 0;
         this.lastDetectTs = -1;
         this.lastOvalState = null;
@@ -411,6 +436,7 @@ export class LivenessEngine {
     resetStepState() {
         this.blinkState = "waitingClose";
         this.blinkCloseTs = 0;
+        this.blinkSeenOpen = false;
         this.nodState = "neutral";
         this.holdStart = null;
         this.baselineYaw = null;
@@ -472,13 +498,20 @@ export class LivenessEngine {
                 const isEyeOpen = metrics.blinkScore > 0
                     ? metrics.blinkScore < config.blinkOpenThreshold
                     : metrics.ear > config.earOpenThreshold;
-                if (this.blinkState === "waitingClose" && isEyeClosed) {
+                // Confirm eyes were OPEN before we count any closed → open transition.
+                // Kills the "step starts mid-blink / mid-squint" false positive.
+                if (isEyeOpen)
+                    this.blinkSeenOpen = true;
+                if (this.blinkState === "waitingClose" && isEyeClosed && this.blinkSeenOpen) {
                     this.blinkState = "closed";
                     this.blinkCloseTs = now;
                 }
                 else if (this.blinkState === "closed" && isEyeOpen) {
-                    if (now - this.blinkCloseTs <= config.blinkMaxDurationMs)
+                    const dt = now - this.blinkCloseTs;
+                    if (dt >= config.blinkMinClosedMs && dt <= config.blinkMaxDurationMs)
                         return this.advanceStep(now);
+                    // Closed phase too short (noise) or too long (eyes never reopened in time) — discard, wait for next attempt.
+                    // blinkSeenOpen stays true — we've already confirmed the user can open their eyes.
                     this.blinkState = "waitingClose";
                 }
                 break;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { LivenessEngine } from "./engine";
-export type { StartLivenessOptions } from "./ui";
-export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, LivenessError, } from "./engine";
-export type { LivenessCallbacks, LivenessOptions, LivenessSoundOptions } from "./engine";
+export type { StartLivenessOptions, LivenessTheme } from "./ui";
+export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, resolveStepLabels, LivenessError, } from "./engine";
+export type { LivenessCallbacks, LivenessOptions, LivenessSoundOptions, LivenessStepKey } from "./engine";
 export type { LivenessEngine } from "./engine";
 /**
  * Starts liveness verification with built-in UI (oval frame, progress ring, camera).

package/dist/index.js

@@ -1,5 +1,5 @@
 import { startLivenessWithUI } from "./ui";
-export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, LivenessError, } from "./engine";
+export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, resolveStepLabels, LivenessError, } from "./engine";
 let currentEngine = null;
 /**
  * Starts liveness verification with built-in UI (oval frame, progress ring, camera).

package/dist/ui.d.ts

@@ -1,9 +1,30 @@
-import { LivenessEngine, LivenessCallbacks, LivenessSoundOptions } from "./engine";
+import { LivenessEngine, LivenessCallbacks, LivenessSoundOptions, LivenessStepKey } from "./engine";
+export type LivenessTheme = {
+    progressColor?: string;
+    progressErrorColor?: string;
+    progressWidth?: number;
+    progressLineCap?: "round" | "square" | "butt";
+    overlayColor?: string;
+    overlayErrorColor?: string;
+};
 export type StartLivenessOptions = {
     container?: HTMLElement;
+    /** If true, render inside `container` instead of taking over the viewport. Container should have explicit width and height. */
+    embed?: boolean;
+    /** Visible face frame shape. Defaults to "oval". */
+    shape?: "oval" | "circle";
+    /** If false, hides SDK-provided instruction text, step dots, position hint, gesture icon and loading text. Sounds still play. Default true. */
+    showInstructions?: boolean;
+    theme?: LivenessTheme;
+    /** Minimum diameter of the visible shape in CSS pixels (so it stays usable on small screens). Default 220. */
+    minSize?: number;
     modelUrl?: string;
     wasmUrl?: string;
     callbacks: LivenessCallbacks;
     sounds?: LivenessSoundOptions;
+    /** Subset of challenges to run, e.g. `["nod", "blink", "mouth"]`. Default: all 5. */
+    steps?: LivenessStepKey[];
+    /** Shuffle the selected step order. Default true. */
+    shuffleSteps?: boolean;
 };
 export declare function startLivenessWithUI(options: StartLivenessOptions): LivenessEngine;