@daboss2003/liveness-web 1.0.2 → 1.0.4

package/dist/engine.js

@@ -110,14 +110,14 @@ const config = {
     // Number of frames averaged to produce the resting baseline per step
     baselineFrames: 8,
     // ── Head turns (relative to baseline) ─────────────────────────────────────
-    yawTurnDelta: 12, // degrees of YAW change needed from rest
+    yawTurnDelta: 9, // degrees of YAW change needed from rest
     yawWrongDirDelta: 16, // block if turned clearly the WRONG way
-    headTurnHoldMs: 120, // sustain the turned pose for this long
+    headTurnHoldMs: 80, // sustain the turned pose for this long
     // ── Nod (relative to baseline) ────────────────────────────────────────────
-    nodDownDelta: 8, // chin must DROP by this many degrees from baseline
-    nodReturnFraction: 0.40, // return to 40% of peak nod depth to complete
-    nodReturnMaxDelta: 5, // cap: never require returning past 5° from baseline
-    maxYawDuringNod: 22,
+    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,
     // ── Blink ──────────────────────────────────────────────────────────────────
     blinkClosedThreshold: 0.35, // blendshape score = eyes closed
     blinkOpenThreshold: 0.20, // blendshape score = eyes open
@@ -127,11 +127,11 @@ const config = {
     maxYawDuringBlink: 25,
     maxPitchDuringBlink: 25,
     // ── Mouth ──────────────────────────────────────────────────────────────────
-    mouthOpenThreshold: 0.28, // jawOpen blendshape
-    mouthOpenMarThreshold: 0.28,
-    mouthHoldMs: 120,
-    maxYawDuringMouth: 25,
-    maxPitchDuringMouth: 25,
+    mouthOpenThreshold: 0.20, // jawOpen blendshape
+    mouthOpenMarThreshold: 0.20,
+    mouthHoldMs: 50,
+    maxYawDuringMouth: 35,
+    maxPitchDuringMouth: 35,
     // ── Face-in-oval ───────────────────────────────────────────────────────────
     ovalCx: 0.50,
     ovalCy: 0.42,

package/dist/ui.js

@@ -64,8 +64,58 @@ function createStyles() {
       object-fit: cover;
       /* Mirror so it feels like a selfie camera */
       transform: scaleX(-1);
+      opacity: 0;
+      transition: opacity 0.2s ease;
       /* Clip the video to the oval using clip-path on the parent */
     }
+    .lv-video.is-playing { opacity: 1; }
+    .lv-video::-webkit-media-controls,
+    .lv-video::-webkit-media-controls-panel,
+    .lv-video::-webkit-media-controls-play-button,
+    .lv-video::-webkit-media-controls-start-playback-button,
+    .lv-video::-webkit-media-controls-overlay-play-button,
+    .lv-video::-webkit-media-controls-enclosure {
+      display: none !important;
+      -webkit-appearance: none;
+    }
+
+    .lv-root.lv-is-loading .lv-ring-wrap,
+    .lv-root.lv-is-loading .lv-dots,
+    .lv-root.lv-is-loading .lv-instruction,
+    .lv-root.lv-is-loading .lv-pos-hint,
+    .lv-root.lv-is-loading .lv-hint-icon {
+      opacity: 0;
+      pointer-events: none;
+    }
+    .lv-root:not(.lv-is-loading) .lv-loading { display: none; }
+    .lv-loading {
+      position: absolute;
+      z-index: 2;
+      left: 50%;
+      top: ${OVAL_TOP_PCT}%;
+      transform: translate(-50%, -50%);
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 8px;
+      text-align: center;
+      color: var(--lv-white);
+      text-shadow: 0 1px 6px rgba(0,0,0,0.5);
+    }
+    .lv-spinner {
+      width: 32px;
+      height: 32px;
+      border: 3px solid rgba(255,255,255,0.25);
+      border-top-color: var(--lv-white);
+      border-radius: 50%;
+      animation: lv-spin 0.9s linear infinite;
+    }
+    .lv-loading-text {
+      font-size: 13px;
+      font-weight: 500;
+      opacity: 0.9;
+    }
+    @keyframes lv-spin { to { transform: rotate(360deg); } }
 
     /* ── Dark overlay with oval cutout ──────────────────────────────────── */
     .lv-overlay {
@@ -257,7 +307,7 @@ export function startLivenessWithUI(options) {
     const container = options.container ?? document.body;
     // ── Root shell ─────────────────────────────────────────────────────────────
     const root = document.createElement("div");
-    root.className = "lv-root";
+    root.className = "lv-root lv-is-loading";
     root.appendChild(createStyles());
     // ── Video background ───────────────────────────────────────────────────────
     const videoBg = document.createElement("div");
@@ -266,6 +316,7 @@ export function startLivenessWithUI(options) {
     video.className = "lv-video";
     video.setAttribute("autoplay", "");
     video.setAttribute("playsinline", "");
+    video.setAttribute("webkit-playsinline", "");
     video.setAttribute("muted", "");
     videoBg.appendChild(video);
     root.appendChild(videoBg);
@@ -292,6 +343,14 @@ export function startLivenessWithUI(options) {
     hintIcon.className = "lv-hint-icon";
     hintIcon.setAttribute("aria-hidden", "true");
     root.appendChild(hintIcon);
+    // ── Loading spinner (shown until model is ready) ───────────────────────────
+    const loading = document.createElement("div");
+    loading.className = "lv-loading";
+    loading.innerHTML = `
+    <div class="lv-spinner" aria-hidden="true"></div>
+    <div class="lv-loading-text">Preparing camera...</div>
+  `;
+    root.appendChild(loading);
     // ── Header ─────────────────────────────────────────────────────────────────
     // const header = document.createElement("div");
     // header.className = "lv-header";
@@ -323,6 +382,8 @@ export function startLivenessWithUI(options) {
     const ringEl = ringWrap.querySelector(".lv-ring-progress");
     const dots = Array.from(dotsEl.querySelectorAll(".lv-dot"));
     const P = ELLIPSE_PERIMETER;
+    let isLoading = true;
+    let pendingChallenge = null;
     // ── UI helpers ──────────────────────────────────────────────────────────────
     function setProgress(completedSteps) {
         if (!ringEl)
@@ -355,8 +416,26 @@ export function startLivenessWithUI(options) {
         posHint.classList.toggle("visible", !inside);
         posHint.textContent = inside ? "" : (reason ?? "Move your face into the oval");
     }
+    function renderChallenge(stepIndex, stepLabel) {
+        if (stepIndex === -1) {
+            setProgress(LIVENESS_STEP_COUNT);
+            setCapturePulse();
+            setHint(null);
+            setDots(LIVENESS_STEP_COUNT);
+            instruction.textContent = stepLabel;
+            return;
+        }
+        setProgress(stepIndex);
+        setDots(stepIndex);
+        setHint(stepLabel);
+        instruction.textContent = stepLabel;
+        ringEl?.classList.remove("lv-ring-pulse");
+    }
     function cleanup() {
         engine.stop();
+        video.removeEventListener("playing", onVideoPlaying);
+        video.removeEventListener("pause", onVideoPause);
+        video.removeEventListener("waiting", onVideoPause);
         root.remove();
     }
     // ── Engine ─────────────────────────────────────────────────────────────────
@@ -364,6 +443,11 @@ export function startLivenessWithUI(options) {
     const sounds = options.sounds ?? {
         ...(Object.keys(DEFAULT_SOUND_DATA_URLS).length > 0 ? DEFAULT_SOUND_DATA_URLS : { baseUrl: "audios/" }),
     };
+    const onVideoPlaying = () => video.classList.add("is-playing");
+    const onVideoPause = () => video.classList.remove("is-playing");
+    video.addEventListener("playing", onVideoPlaying);
+    video.addEventListener("pause", onVideoPause);
+    video.addEventListener("waiting", onVideoPause);
     const engine = new LivenessEngine({
         videoElement: video,
         canvasElement: canvas,
@@ -372,20 +456,13 @@ export function startLivenessWithUI(options) {
         sounds,
         callbacks: {
             onChallengeChanged: (stepIndex, stepLabel) => {
-                if (stepIndex === -1) {
-                    setProgress(LIVENESS_STEP_COUNT);
-                    setCapturePulse();
-                    setHint(null);
-                    setDots(LIVENESS_STEP_COUNT);
-                    instruction.textContent = stepLabel;
-                    return;
+                pendingChallenge = { stepIndex, stepLabel };
+                if (!isLoading) {
+                    renderChallenge(stepIndex, stepLabel);
+                }
+                if (stepIndex !== -1) {
+                    options.callbacks.onChallengeChanged?.(stepIndex, stepLabel);
                 }
-                setProgress(stepIndex);
-                setDots(stepIndex);
-                setHint(stepLabel);
-                instruction.textContent = stepLabel;
-                ringEl?.classList.remove("lv-ring-pulse");
-                options.callbacks.onChallengeChanged?.(stepIndex, stepLabel);
             },
             onFaceInOval: (inside, reason) => {
                 setFaceInOval(inside, reason);
@@ -408,7 +485,12 @@ export function startLivenessWithUI(options) {
     setProgress(0);
     setDots(0);
     setHint(null);
-    engine.start().then(() => { }, (err) => {
+    engine.start().then(() => {
+        isLoading = false;
+        root.classList.remove("lv-is-loading");
+        if (pendingChallenge)
+            renderChallenge(pendingChallenge.stepIndex, pendingChallenge.stepLabel);
+    }, (err) => {
         cleanup();
         const reason = err instanceof LivenessError
             ? err.code

package/package.json

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

package/src/engine.ts

@@ -188,15 +188,15 @@ const config = {
   baselineFrames: 8,
 
   // ── Head turns (relative to baseline) ─────────────────────────────────────
-  yawTurnDelta:           12,   // degrees of YAW change needed from rest
+  yawTurnDelta:            9,   // degrees of YAW change needed from rest
   yawWrongDirDelta:       16,   // block if turned clearly the WRONG way
-  headTurnHoldMs:        120,   // sustain the turned pose for this long
+  headTurnHoldMs:         80,   // sustain the turned pose for this long
 
   // ── Nod (relative to baseline) ────────────────────────────────────────────
-  nodDownDelta:            8,   // chin must DROP by this many degrees from baseline
-  nodReturnFraction:      0.40, // return to 40% of peak nod depth to complete
-  nodReturnMaxDelta:       5,   // cap: never require returning past 5° from baseline
-  maxYawDuringNod:        22,
+  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,
 
   // ── Blink ──────────────────────────────────────────────────────────────────
   blinkClosedThreshold:  0.35,  // blendshape score = eyes closed
@@ -208,11 +208,11 @@ const config = {
   maxPitchDuringBlink:   25,
 
   // ── Mouth ──────────────────────────────────────────────────────────────────
-  mouthOpenThreshold:    0.28,  // jawOpen blendshape
-  mouthOpenMarThreshold: 0.28,
-  mouthHoldMs:          120,
-  maxYawDuringMouth:     25,
-  maxPitchDuringMouth:   25,
+  mouthOpenThreshold:    0.20,  // jawOpen blendshape
+  mouthOpenMarThreshold: 0.20,
+  mouthHoldMs:           50,
+  maxYawDuringMouth:     35,
+  maxPitchDuringMouth:   35,
 
   // ── Face-in-oval ───────────────────────────────────────────────────────────
   ovalCx:       0.50,

package/src/ui.ts

@@ -79,8 +79,58 @@ function createStyles(): HTMLStyleElement {
       object-fit: cover;
       /* Mirror so it feels like a selfie camera */
       transform: scaleX(-1);
+      opacity: 0;
+      transition: opacity 0.2s ease;
       /* Clip the video to the oval using clip-path on the parent */
     }
+    .lv-video.is-playing { opacity: 1; }
+    .lv-video::-webkit-media-controls,
+    .lv-video::-webkit-media-controls-panel,
+    .lv-video::-webkit-media-controls-play-button,
+    .lv-video::-webkit-media-controls-start-playback-button,
+    .lv-video::-webkit-media-controls-overlay-play-button,
+    .lv-video::-webkit-media-controls-enclosure {
+      display: none !important;
+      -webkit-appearance: none;
+    }
+
+    .lv-root.lv-is-loading .lv-ring-wrap,
+    .lv-root.lv-is-loading .lv-dots,
+    .lv-root.lv-is-loading .lv-instruction,
+    .lv-root.lv-is-loading .lv-pos-hint,
+    .lv-root.lv-is-loading .lv-hint-icon {
+      opacity: 0;
+      pointer-events: none;
+    }
+    .lv-root:not(.lv-is-loading) .lv-loading { display: none; }
+    .lv-loading {
+      position: absolute;
+      z-index: 2;
+      left: 50%;
+      top: ${OVAL_TOP_PCT}%;
+      transform: translate(-50%, -50%);
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 8px;
+      text-align: center;
+      color: var(--lv-white);
+      text-shadow: 0 1px 6px rgba(0,0,0,0.5);
+    }
+    .lv-spinner {
+      width: 32px;
+      height: 32px;
+      border: 3px solid rgba(255,255,255,0.25);
+      border-top-color: var(--lv-white);
+      border-radius: 50%;
+      animation: lv-spin 0.9s linear infinite;
+    }
+    .lv-loading-text {
+      font-size: 13px;
+      font-weight: 500;
+      opacity: 0.9;
+    }
+    @keyframes lv-spin { to { transform: rotate(360deg); } }
 
     /* ── Dark overlay with oval cutout ──────────────────────────────────── */
     .lv-overlay {
@@ -277,7 +327,7 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
 
   // ── Root shell ─────────────────────────────────────────────────────────────
   const root = document.createElement("div");
-  root.className = "lv-root";
+  root.className = "lv-root lv-is-loading";
   root.appendChild(createStyles());
 
   // ── Video background ───────────────────────────────────────────────────────
@@ -287,6 +337,7 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
   video.className = "lv-video";
   video.setAttribute("autoplay", "");
   video.setAttribute("playsinline", "");
+  video.setAttribute("webkit-playsinline", "");
   video.setAttribute("muted", "");
   videoBg.appendChild(video);
   root.appendChild(videoBg);
@@ -317,6 +368,15 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
   hintIcon.setAttribute("aria-hidden", "true");
   root.appendChild(hintIcon);
 
+  // ── Loading spinner (shown until model is ready) ───────────────────────────
+  const loading = document.createElement("div");
+  loading.className = "lv-loading";
+  loading.innerHTML = `
+    <div class="lv-spinner" aria-hidden="true"></div>
+    <div class="lv-loading-text">Preparing camera...</div>
+  `;
+  root.appendChild(loading);
+
   // ── Header ─────────────────────────────────────────────────────────────────
   // const header = document.createElement("div");
   // header.className = "lv-header";
@@ -354,6 +414,8 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
   const ringEl = ringWrap.querySelector(".lv-ring-progress") as SVGEllipseElement | null;
   const dots = Array.from(dotsEl.querySelectorAll(".lv-dot"));
   const P = ELLIPSE_PERIMETER;
+  let isLoading = true;
+  let pendingChallenge: { stepIndex: number; stepLabel: string } | null = null;
 
   // ── UI helpers ──────────────────────────────────────────────────────────────
 
@@ -389,8 +451,27 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
     posHint.textContent = inside ? "" : (reason ?? "Move your face into the oval");
   }
 
+  function renderChallenge(stepIndex: number, stepLabel: string): void {
+    if (stepIndex === -1) {
+      setProgress(LIVENESS_STEP_COUNT);
+      setCapturePulse();
+      setHint(null);
+      setDots(LIVENESS_STEP_COUNT);
+      instruction.textContent = stepLabel;
+      return;
+    }
+    setProgress(stepIndex);
+    setDots(stepIndex);
+    setHint(stepLabel);
+    instruction.textContent = stepLabel;
+    ringEl?.classList.remove("lv-ring-pulse");
+  }
+
   function cleanup(): void {
     engine.stop();
+    video.removeEventListener("playing", onVideoPlaying);
+    video.removeEventListener("pause", onVideoPause);
+    video.removeEventListener("waiting", onVideoPause);
     root.remove();
   }
 
@@ -400,6 +481,12 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
     ...(Object.keys(DEFAULT_SOUND_DATA_URLS).length > 0 ? DEFAULT_SOUND_DATA_URLS : { baseUrl: "audios/" }),
   };
 
+  const onVideoPlaying = () => video.classList.add("is-playing");
+  const onVideoPause = () => video.classList.remove("is-playing");
+  video.addEventListener("playing", onVideoPlaying);
+  video.addEventListener("pause", onVideoPause);
+  video.addEventListener("waiting", onVideoPause);
+
   const engine = new LivenessEngine({
     videoElement: video,
     canvasElement: canvas,
@@ -408,20 +495,13 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
     sounds,
     callbacks: {
       onChallengeChanged: (stepIndex, stepLabel) => {
-        if (stepIndex === -1) {
-          setProgress(LIVENESS_STEP_COUNT);
-          setCapturePulse();
-          setHint(null);
-          setDots(LIVENESS_STEP_COUNT);
-          instruction.textContent = stepLabel;
-          return;
+        pendingChallenge = { stepIndex, stepLabel };
+        if (!isLoading) {
+          renderChallenge(stepIndex, stepLabel);
+        }
+        if (stepIndex !== -1) {
+          options.callbacks.onChallengeChanged?.(stepIndex, stepLabel);
         }
-        setProgress(stepIndex);
-        setDots(stepIndex);
-        setHint(stepLabel);
-        instruction.textContent = stepLabel;
-        ringEl?.classList.remove("lv-ring-pulse");
-        options.callbacks.onChallengeChanged?.(stepIndex, stepLabel);
       },
       onFaceInOval: (inside, reason) => {
         setFaceInOval(inside, reason);
@@ -447,7 +527,11 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
   setHint(null);
 
   engine.start().then(
-    () => {},
+    () => {
+      isLoading = false;
+      root.classList.remove("lv-is-loading");
+      if (pendingChallenge) renderChallenge(pendingChallenge.stepIndex, pendingChallenge.stepLabel);
+    },
     (err) => {
       cleanup();
       const reason =