@daboss2003/liveness-web 1.0.4 → 1.0.6

package/dist/engine.d.ts

@@ -50,13 +50,14 @@ export type Metrics = {
     faceCy: number;
     faceSize: number;
 };
-export declare const LIVENESS_STEP_COUNT: number;
+export declare const LIVENESS_STEP_COUNT: 5;
 export declare class LivenessEngine {
     private opts;
     private landmarker;
     private running;
     private rafId;
     private stream;
+    private steps;
     private stepIndex;
     private stepStart;
     private baselineYaw;
@@ -71,14 +72,15 @@ export declare class LivenessEngine {
     private lastDetectTs;
     private lastOvalState;
     private stepSoundPlayedForCurrentStep;
-    private currentStepAudio;
-    private currentStepAudioCleanup;
+    private currentAudio;
+    private currentAudioCleanup;
+    private currentAudioToken;
     private sessionTimeoutId;
     constructor(opts: LivenessOptions);
     private playSound;
     private getSoundUrl;
     private playStepSound;
-    private stopStepSound;
+    private stopAllSounds;
     private clearSessionTimeout;
     private playGoodSound;
     private playCaptureSound;

package/dist/engine.js

@@ -84,8 +84,7 @@ function shuffleArray(array) {
     }
     return out;
 }
-const steps = shuffleArray(STEP_LABELS).map((label, index) => ({ index, label }));
-export const LIVENESS_STEP_COUNT = steps.length;
+export const LIVENESS_STEP_COUNT = STEP_LABELS.length;
 // ─────────────────────────────────────────────────────────────────────────────
 //  KEY DESIGN: RELATIVE MEASUREMENT
 //
@@ -114,18 +113,18 @@ const config = {
     yawWrongDirDelta: 16, // block if turned clearly the WRONG way
     headTurnHoldMs: 80, // sustain the turned pose for this long
     // ── Nod (relative to baseline) ────────────────────────────────────────────
-    nodDownDelta: 4, // chin must DROP by this many degrees from baseline
-    nodReturnFraction: 0.75, // return to 75% of peak nod depth to complete
-    nodReturnMaxDelta: 9, // cap: never require returning past 9° from baseline
-    maxYawDuringNod: 32,
+    nodDownDelta: 3, // chin must DROP by this many degrees from baseline
+    nodReturnFraction: 0.85, // return to 85% of peak nod depth to complete
+    nodReturnMaxDelta: 12, // cap: never require returning past 12° from baseline
+    maxYawDuringNod: 40,
     // ── Blink ──────────────────────────────────────────────────────────────────
-    blinkClosedThreshold: 0.35, // blendshape score = eyes closed
-    blinkOpenThreshold: 0.20, // blendshape score = eyes open
+    blinkClosedThreshold: 0.30, // blendshape score = eyes closed
+    blinkOpenThreshold: 0.25, // blendshape score = eyes open
     earClosedThreshold: 0.20,
     earOpenThreshold: 0.25,
     blinkMaxDurationMs: 4000,
-    maxYawDuringBlink: 25,
-    maxPitchDuringBlink: 25,
+    maxYawDuringBlink: 30,
+    maxPitchDuringBlink: 30,
     // ── Mouth ──────────────────────────────────────────────────────────────────
     mouthOpenThreshold: 0.20, // jawOpen blendshape
     mouthOpenMarThreshold: 0.20,
@@ -158,6 +157,7 @@ export class LivenessEngine {
         this.running = false;
         this.rafId = null;
         this.stream = null;
+        this.steps = [];
         this.stepIndex = 0;
         this.stepStart = 0;
         // ── Baseline (sampled during readyMs window) ───────────────────────────────
@@ -174,22 +174,36 @@ export class LivenessEngine {
         this.lastDetectTs = -1;
         this.lastOvalState = null;
         this.stepSoundPlayedForCurrentStep = false;
-        this.currentStepAudio = null;
-        this.currentStepAudioCleanup = null;
+        this.currentAudio = null;
+        this.currentAudioCleanup = null;
+        this.currentAudioToken = 0;
         this.sessionTimeoutId = null;
     }
     playSound(url, onEnded) {
+        this.stopAllSounds();
+        const token = ++this.currentAudioToken;
         const a = new Audio(url);
-        if (onEnded) {
-            const done = () => {
-                a.removeEventListener("ended", done);
-                a.removeEventListener("error", done);
-                onEnded();
-            };
-            a.addEventListener("ended", done);
-            a.addEventListener("error", done);
-        }
-        a.play().catch(() => onEnded?.());
+        a.preload = "auto";
+        const done = () => {
+            if (token !== this.currentAudioToken)
+                return;
+            a.removeEventListener("ended", done);
+            a.removeEventListener("error", done);
+            if (this.currentAudio === a)
+                this.currentAudio = null;
+            if (this.currentAudioCleanup === cleanup)
+                this.currentAudioCleanup = null;
+            onEnded?.();
+        };
+        const cleanup = () => {
+            a.removeEventListener("ended", done);
+            a.removeEventListener("error", done);
+        };
+        this.currentAudio = a;
+        this.currentAudioCleanup = cleanup;
+        a.addEventListener("ended", done);
+        a.addEventListener("error", done);
+        a.play().catch(() => done());
     }
     getSoundUrl(key) {
         const s = this.opts.sounds;
@@ -211,34 +225,17 @@ export class LivenessEngine {
         const url = this.getSoundUrl(key);
         if (!url)
             return;
-        this.stopStepSound();
-        const a = new Audio(url);
-        const done = () => {
-            a.removeEventListener("ended", done);
-            a.removeEventListener("error", done);
-            if (this.currentStepAudio === a)
-                this.currentStepAudio = null;
-            if (this.currentStepAudioCleanup === cleanup)
-                this.currentStepAudioCleanup = null;
-        };
-        const cleanup = () => {
-            a.removeEventListener("ended", done);
-            a.removeEventListener("error", done);
-        };
-        this.currentStepAudio = a;
-        this.currentStepAudioCleanup = cleanup;
-        a.addEventListener("ended", done);
-        a.addEventListener("error", done);
-        a.play().catch(() => done());
+        this.playSound(url);
     }
-    stopStepSound() {
-        if (this.currentStepAudio) {
-            this.currentStepAudio.pause();
-            this.currentStepAudio.currentTime = 0;
+    stopAllSounds() {
+        this.currentAudioToken += 1;
+        if (this.currentAudio) {
+            this.currentAudio.pause();
+            this.currentAudio.currentTime = 0;
         }
-        this.currentStepAudioCleanup?.();
-        this.currentStepAudioCleanup = null;
-        this.currentStepAudio = null;
+        this.currentAudioCleanup?.();
+        this.currentAudioCleanup = null;
+        this.currentAudio = null;
     }
     clearSessionTimeout() {
         if (this.sessionTimeoutId != null) {
@@ -264,6 +261,7 @@ export class LivenessEngine {
     async start() {
         this.stopDetectionOnly();
         this.running = true;
+        this.steps = shuffleArray(STEP_LABELS).map((label, index) => ({ index, label }));
         this.stepIndex = 0;
         this.lastDetectTs = -1;
         this.lastOvalState = null;
@@ -276,7 +274,9 @@ export class LivenessEngine {
             if (this.running)
                 this.fail("Timed out. Please try again.");
         }, config.sessionTimeoutMs);
-        this.opts.callbacks?.onChallengeChanged?.(steps[0].index, steps[0].label);
+        if (this.steps.length > 0) {
+            this.opts.callbacks?.onChallengeChanged?.(this.steps[0].index, this.steps[0].label);
+        }
         await this.ensureVideo();
         this.landmarker = await createLandmarkerWithRetry(this.opts, MAX_CDN_RETRIES);
         this.loop();
@@ -289,7 +289,7 @@ export class LivenessEngine {
     stopDetectionOnly() {
         this.running = false;
         this.clearSessionTimeout();
-        this.stopStepSound();
+        this.stopAllSounds();
         if (this.rafId != null) {
             cancelAnimationFrame(this.rafId);
             this.rafId = null;
@@ -360,12 +360,12 @@ export class LivenessEngine {
             }
             this.opts.callbacks?.onDebugFrame?.({
                 hasFace: true, metrics,
-                step: steps[this.stepIndex]?.label ?? "done",
+                step: this.steps[this.stepIndex]?.label ?? "done",
             });
             if (inside) {
-                if (!this.stepSoundPlayedForCurrentStep && this.stepIndex < steps.length) {
+                if (!this.stepSoundPlayedForCurrentStep && this.stepIndex < this.steps.length) {
                     this.stepSoundPlayedForCurrentStep = true;
-                    this.playStepSound(steps[this.stepIndex].label);
+                    this.playStepSound(this.steps[this.stepIndex].label);
                 }
                 if (this.updateState(metrics, now) === "passed") {
                     this.scheduleCapture();
@@ -380,14 +380,14 @@ export class LivenessEngine {
             }
             this.opts.callbacks?.onDebugFrame?.({
                 hasFace: false, metrics: null,
-                step: steps[this.stepIndex]?.label ?? "done",
+                step: this.steps[this.stepIndex]?.label ?? "done",
             });
         }
         this.rafId = requestAnimationFrame(() => this.loop());
     }
     // ── Oval check ─────────────────────────────────────────────────────────────
     checkFaceInOval(m) {
-        const isHeadTurn = config.headTurnSteps.has(steps[this.stepIndex]?.label ?? "");
+        const isHeadTurn = config.headTurnSteps.has(this.steps[this.stepIndex]?.label ?? "");
         const mx = 1 - m.faceCx; // mirror x to match CSS scaleX(-1)
         const dy = (m.faceCy - config.ovalCy) / config.ovalRy;
         const dx = (mx - config.ovalCx) / config.ovalRx;
@@ -426,7 +426,7 @@ export class LivenessEngine {
         const bPitch = this.baselinePitch ?? metrics.pitch;
         const dYaw = metrics.yaw - bYaw;
         const dPitch = metrics.pitch - bPitch;
-        switch (steps[this.stepIndex].label) {
+        switch (this.steps[this.stepIndex]?.label) {
             // ── LEFT turn (negative yaw delta = turning left from rest) ─────────────
             case "Turn your head LEFT": {
                 if (dYaw > config.yawWrongDirDelta) {
@@ -529,18 +529,20 @@ export class LivenessEngine {
         return "none";
     }
     advanceStep(now) {
-        this.stopStepSound();
+        this.stopAllSounds();
         this.stepIndex += 1;
-        if (this.stepIndex >= steps.length) {
+        if (this.stepIndex >= this.steps.length) {
             this.playGoodSound();
             return "passed";
         }
         this.stepStart = now + config.readyMs;
         this.resetStepState();
         this.stepSoundPlayedForCurrentStep = true;
-        const step = steps[this.stepIndex];
-        this.opts.callbacks?.onChallengeChanged?.(step.index, step.label);
-        this.playGoodSound(() => this.playStepSound(step.label));
+        const step = this.steps[this.stepIndex];
+        if (step) {
+            this.opts.callbacks?.onChallengeChanged?.(step.index, step.label);
+            this.playGoodSound(() => this.playStepSound(step.label));
+        }
         return "none";
     }
     fail(reason) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daboss2003/liveness-web",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Web liveness detection using MediaPipe Face Landmarker (CDN)",
   "keywords": [
     "liveness",

package/src/engine.ts

@@ -158,9 +158,7 @@ function shuffleArray<T>(array: readonly T[]): T[] {
   return out;
 }
 
-const steps: LivenessStep[] = shuffleArray(STEP_LABELS).map((label, index) => ({ index, label }));
-
-export const LIVENESS_STEP_COUNT = steps.length;
+export const LIVENESS_STEP_COUNT = STEP_LABELS.length;
 
 // ─────────────────────────────────────────────────────────────────────────────
 //  KEY DESIGN: RELATIVE MEASUREMENT
@@ -193,19 +191,19 @@ const config = {
   headTurnHoldMs:         80,   // sustain the turned pose for this long
 
   // ── Nod (relative to baseline) ────────────────────────────────────────────
-  nodDownDelta:            4,   // chin must DROP by this many degrees from baseline
-  nodReturnFraction:      0.75, // return to 75% of peak nod depth to complete
-  nodReturnMaxDelta:       9,   // cap: never require returning past 9° from baseline
-  maxYawDuringNod:        32,
+  nodDownDelta:            3,   // chin must DROP by this many degrees from baseline
+  nodReturnFraction:      0.85, // return to 85% of peak nod depth to complete
+  nodReturnMaxDelta:      12,   // cap: never require returning past 12° from baseline
+  maxYawDuringNod:        40,
 
   // ── Blink ──────────────────────────────────────────────────────────────────
-  blinkClosedThreshold:  0.35,  // blendshape score = eyes closed
-  blinkOpenThreshold:    0.20,  // blendshape score = eyes open
+  blinkClosedThreshold:  0.30,  // blendshape score = eyes closed
+  blinkOpenThreshold:    0.25,  // blendshape score = eyes open
   earClosedThreshold:    0.20,
   earOpenThreshold:      0.25,
   blinkMaxDurationMs:   4000,
-  maxYawDuringBlink:     25,
-  maxPitchDuringBlink:   25,
+  maxYawDuringBlink:     30,
+  maxPitchDuringBlink:   30,
 
   // ── Mouth ──────────────────────────────────────────────────────────────────
   mouthOpenThreshold:    0.20,  // jawOpen blendshape
@@ -242,6 +240,7 @@ export class LivenessEngine {
   private rafId:       number | null = null;
   private stream:      MediaStream | null = null;
 
+  private steps: LivenessStep[] = [];
   private stepIndex   = 0;
   private stepStart   = 0;
 
@@ -261,24 +260,35 @@ export class LivenessEngine {
   private lastDetectTs   = -1;
   private lastOvalState: boolean | null = null;
   private stepSoundPlayedForCurrentStep = false;
-  private currentStepAudio: HTMLAudioElement | null = null;
-  private currentStepAudioCleanup: (() => void) | null = null;
+  private currentAudio: HTMLAudioElement | null = null;
+  private currentAudioCleanup: (() => void) | null = null;
+  private currentAudioToken = 0;
   private sessionTimeoutId: number | null = null;
 
   constructor(private opts: LivenessOptions) {}
 
   private playSound(url: string, onEnded?: () => void): void {
+    this.stopAllSounds();
+    const token = ++this.currentAudioToken;
     const a = new Audio(url);
-    if (onEnded) {
-      const done = () => {
-        a.removeEventListener("ended", done);
-        a.removeEventListener("error", done);
-        onEnded();
-      };
-      a.addEventListener("ended", done);
-      a.addEventListener("error", done);
-    }
-    a.play().catch(() => onEnded?.());
+    a.preload = "auto";
+    const done = () => {
+      if (token !== this.currentAudioToken) return;
+      a.removeEventListener("ended", done);
+      a.removeEventListener("error", done);
+      if (this.currentAudio === a) this.currentAudio = null;
+      if (this.currentAudioCleanup === cleanup) this.currentAudioCleanup = null;
+      onEnded?.();
+    };
+    const cleanup = () => {
+      a.removeEventListener("ended", done);
+      a.removeEventListener("error", done);
+    };
+    this.currentAudio = a;
+    this.currentAudioCleanup = cleanup;
+    a.addEventListener("ended", done);
+    a.addEventListener("error", done);
+    a.play().catch(() => done());
   }
 
   private getSoundUrl(key: string): string | undefined {
@@ -297,33 +307,18 @@ export class LivenessEngine {
     if (!key) return;
     const url = this.getSoundUrl(key);
     if (!url) return;
-    this.stopStepSound();
-    const a = new Audio(url);
-    const done = () => {
-      a.removeEventListener("ended", done);
-      a.removeEventListener("error", done);
-      if (this.currentStepAudio === a) this.currentStepAudio = null;
-      if (this.currentStepAudioCleanup === cleanup) this.currentStepAudioCleanup = null;
-    };
-    const cleanup = () => {
-      a.removeEventListener("ended", done);
-      a.removeEventListener("error", done);
-    };
-    this.currentStepAudio = a;
-    this.currentStepAudioCleanup = cleanup;
-    a.addEventListener("ended", done);
-    a.addEventListener("error", done);
-    a.play().catch(() => done());
+    this.playSound(url);
   }
 
-  private stopStepSound(): void {
-    if (this.currentStepAudio) {
-      this.currentStepAudio.pause();
-      this.currentStepAudio.currentTime = 0;
+  private stopAllSounds(): void {
+    this.currentAudioToken += 1;
+    if (this.currentAudio) {
+      this.currentAudio.pause();
+      this.currentAudio.currentTime = 0;
     }
-    this.currentStepAudioCleanup?.();
-    this.currentStepAudioCleanup = null;
-    this.currentStepAudio = null;
+    this.currentAudioCleanup?.();
+    this.currentAudioCleanup = null;
+    this.currentAudio = null;
   }
 
   private clearSessionTimeout(): void {
@@ -350,6 +345,7 @@ export class LivenessEngine {
   async start(): Promise<void> {
     this.stopDetectionOnly();
     this.running      = true;
+    this.steps        = shuffleArray(STEP_LABELS).map((label, index) => ({ index, label }));
     this.stepIndex    = 0;
     this.lastDetectTs = -1;
     this.lastOvalState = null;
@@ -361,7 +357,9 @@ export class LivenessEngine {
     this.sessionTimeoutId = setTimeout(() => {
       if (this.running) this.fail("Timed out. Please try again.");
     }, config.sessionTimeoutMs);
-    this.opts.callbacks?.onChallengeChanged?.(steps[0].index, steps[0].label);
+    if (this.steps.length > 0) {
+      this.opts.callbacks?.onChallengeChanged?.(this.steps[0].index, this.steps[0].label);
+    }
     await this.ensureVideo();
     this.landmarker = await createLandmarkerWithRetry(this.opts, MAX_CDN_RETRIES);
     this.loop();
@@ -376,7 +374,7 @@ export class LivenessEngine {
   private stopDetectionOnly(): void {
     this.running = false;
     this.clearSessionTimeout();
-    this.stopStepSound();
+    this.stopAllSounds();
     if (this.rafId != null) { cancelAnimationFrame(this.rafId); this.rafId = null; }
     if (this.landmarker)    { this.landmarker.close(); this.landmarker = null; }
   }
@@ -455,13 +453,13 @@ export class LivenessEngine {
 
       this.opts.callbacks?.onDebugFrame?.({
         hasFace: true, metrics,
-        step: steps[this.stepIndex]?.label ?? "done",
+        step: this.steps[this.stepIndex]?.label ?? "done",
       });
 
       if (inside) {
-        if (!this.stepSoundPlayedForCurrentStep && this.stepIndex < steps.length) {
+        if (!this.stepSoundPlayedForCurrentStep && this.stepIndex < this.steps.length) {
           this.stepSoundPlayedForCurrentStep = true;
-          this.playStepSound(steps[this.stepIndex].label);
+          this.playStepSound(this.steps[this.stepIndex].label);
         }
         if (this.updateState(metrics, now) === "passed") {
           this.scheduleCapture();
@@ -475,7 +473,7 @@ export class LivenessEngine {
       }
       this.opts.callbacks?.onDebugFrame?.({
         hasFace: false, metrics: null,
-        step: steps[this.stepIndex]?.label ?? "done",
+        step: this.steps[this.stepIndex]?.label ?? "done",
       });
     }
 
@@ -485,7 +483,7 @@ export class LivenessEngine {
   // ── Oval check ─────────────────────────────────────────────────────────────
 
   private checkFaceInOval(m: Metrics): { inside: boolean; reason?: string } {
-    const isHeadTurn = config.headTurnSteps.has(steps[this.stepIndex]?.label ?? "");
+    const isHeadTurn = config.headTurnSteps.has(this.steps[this.stepIndex]?.label ?? "");
     const mx = 1 - m.faceCx; // mirror x to match CSS scaleX(-1)
     const dy = (m.faceCy - config.ovalCy) / config.ovalRy;
     const dx = (mx - config.ovalCx) / config.ovalRx;
@@ -529,7 +527,7 @@ export class LivenessEngine {
     const dYaw   = metrics.yaw   - bYaw;
     const dPitch = metrics.pitch - bPitch;
 
-    switch (steps[this.stepIndex].label) {
+    switch (this.steps[this.stepIndex]?.label) {
 
       // ── LEFT turn (negative yaw delta = turning left from rest) ─────────────
       case "Turn your head LEFT": {
@@ -627,18 +625,20 @@ export class LivenessEngine {
   }
 
   private advanceStep(now: number): "passed" | "none" {
-    this.stopStepSound();
+    this.stopAllSounds();
     this.stepIndex += 1;
-    if (this.stepIndex >= steps.length) {
+    if (this.stepIndex >= this.steps.length) {
       this.playGoodSound();
       return "passed";
     }
     this.stepStart = now + config.readyMs;
     this.resetStepState();
     this.stepSoundPlayedForCurrentStep = true;
-    const step = steps[this.stepIndex];
-    this.opts.callbacks?.onChallengeChanged?.(step.index, step.label);
-    this.playGoodSound(() => this.playStepSound(step.label));
+    const step = this.steps[this.stepIndex];
+    if (step) {
+      this.opts.callbacks?.onChallengeChanged?.(step.index, step.label);
+      this.playGoodSound(() => this.playStepSound(step.label));
+    }
     return "none";
   }