@rick427/react-native-liveness 0.2.4 → 0.3.0

package/src/livenessScoring.ts

@@ -1,98 +1,61 @@
 import type { FaceData, FeedbackMessage } from './types';
 
-// Eye openness is intentionally excluded — passive liveness detection does not
-// require gestures. Natural blinks are involuntary and must never penalise the
-// user. Liveness is confirmed via face presence, size, and frontal pose only.
-const WEIGHTS = {
-  faceDetected: 0.25,
-  faceSize: 0.3,
-  headPose: 0.45,
-} as const;
-
-// Loosened from 0.20 / 0.65 — gives more room for the user to breathe
+// ─── Thresholds ───────────────────────────────────────────────────────────────
 const FACE_SIZE_MIN = 0.15;
 const FACE_SIZE_MAX = 0.8;
-const FACE_SIZE_SOFT_MARGIN = 0.05; // gradient ramp at each edge
-
-// Loosened from 20° — ML Kit head pose is noisy, 25° still rejects clear tilts
-const MAX_YAW_DEG = 25;
-const MAX_PITCH_DEG = 25;
 
-export type FrameScore = {
-  total: number;
-  faceSize: number;
-  headPose: number;
-  eyesOpen: number;
+// ─── Challenge step ───────────────────────────────────────────────────────────
+export type ChallengeStep = {
+  /** Text shown to the user while this step is active. */
+  instruction: FeedbackMessage;
+  /** How many consecutive ML Kit frames must pass the check to complete the step. */
+  framesRequired: number;
+  /** Returns true when the face satisfies this step's condition. */
+  check: (face: FaceData, frameWidth: number) => boolean;
 };
 
-export function scoreFrame(face: FaceData, frameWidth: number): FrameScore {
-  if (!face.detected || frameWidth === 0) {
-    return { total: 0, faceSize: 0, headPose: 0, eyesOpen: 0 };
-  }
-
-  const faceWidthRatio = face.bounds.width / frameWidth;
-
-  // Soft-edge face size: smooth ramp into / out of the valid range so a face
-  // sitting just outside the threshold doesn't score hard 0.
-  let faceSize: number;
-  if (faceWidthRatio >= FACE_SIZE_MIN && faceWidthRatio <= FACE_SIZE_MAX) {
-    faceSize = 1.0;
-  } else if (faceWidthRatio < FACE_SIZE_MIN) {
-    faceSize = Math.max(
-      0,
-      (faceWidthRatio - (FACE_SIZE_MIN - FACE_SIZE_SOFT_MARGIN)) /
-        FACE_SIZE_SOFT_MARGIN
-    );
-  } else {
-    faceSize = Math.max(
-      0,
-      (FACE_SIZE_MAX + FACE_SIZE_SOFT_MARGIN - faceWidthRatio) /
-        FACE_SIZE_SOFT_MARGIN
-    );
-  }
-
-  // Soft-edge head pose: full score inside threshold, linear decay outside
-  const yawScore =
-    Math.abs(face.yawAngle) <= MAX_YAW_DEG
-      ? 1.0
-      : Math.max(0, 1 - (Math.abs(face.yawAngle) - MAX_YAW_DEG) / MAX_YAW_DEG);
-  const pitchScore =
-    Math.abs(face.pitchAngle) <= MAX_PITCH_DEG
-      ? 1.0
-      : Math.max(
-          0,
-          1 - (Math.abs(face.pitchAngle) - MAX_PITCH_DEG) / MAX_PITCH_DEG
-        );
-  const headPose = (yawScore + pitchScore) / 2;
-
-  const total =
-    WEIGHTS.faceDetected * 1.0 +
-    WEIGHTS.faceSize * faceSize +
-    WEIGHTS.headPose * headPose;
-
-  return { total, faceSize, headPose, eyesOpen: 0 };
-}
-
-export function rollingAverage(scores: number[]): number {
-  if (scores.length === 0) return 0;
-  return scores.reduce((a, b) => a + b, 0) / scores.length;
-}
-
-export function getFeedback(
-  face: FaceData,
-  frameWidth: number,
-  livenessConfirmed: boolean
-): FeedbackMessage {
-  if (livenessConfirmed) return 'Liveness confirmed';
-  if (!face.detected) return 'Position your face in the circle';
-
-  const faceWidthRatio = face.bounds.width / frameWidth;
-  if (faceWidthRatio < FACE_SIZE_MIN) return 'Move closer';
-  if (faceWidthRatio > FACE_SIZE_MAX) return 'Move farther away';
-
-  const yawBad = Math.abs(face.yawAngle) >= MAX_YAW_DEG;
-  const pitchBad = Math.abs(face.pitchAngle) >= MAX_PITCH_DEG;
-  if (yawBad || pitchBad) return 'Look straight ahead';
-
-  return 'Hold still...';
-}
+/**
+ * Sequential liveness challenges.
+ * Each step completes when `framesRequired` consecutive frames pass `check`.
+ * The progress arc fills 1/N per step, then turns green at the end.
+ */
+export const CHALLENGE_STEPS: readonly ChallengeStep[] = [
+  {
+    instruction: 'Position your face in the circle',
+    framesRequired: 5,
+    check: (face, fw) => {
+      if (!face.detected || fw === 0) return false;
+      const ratio = face.bounds.width / fw;
+      return (
+        ratio >= FACE_SIZE_MIN &&
+        ratio <= FACE_SIZE_MAX &&
+        Math.abs(face.yawAngle) < 20 &&
+        Math.abs(face.pitchAngle) < 20
+      );
+    },
+  },
+  {
+    instruction: 'Turn your head slightly',
+    framesRequired: 4,
+    check: (face) => face.detected && Math.abs(face.yawAngle) > 15,
+  },
+  {
+    instruction: 'Now look straight ahead',
+    framesRequired: 5,
+    check: (face) =>
+      face.detected &&
+      Math.abs(face.yawAngle) < 10 &&
+      Math.abs(face.pitchAngle) < 15,
+  },
+  {
+    instruction: 'Now blink',
+    framesRequired: 2,
+    check: (face) => {
+      if (!face.detected) return false;
+      const l = face.leftEyeOpenProbability;
+      const r = face.rightEyeOpenProbability;
+      // -1 means ML Kit couldn't classify — don't count as a blink
+      return l >= 0 && l < 0.3 && r >= 0 && r < 0.3;
+    },
+  },
+] as const;

package/src/types.ts

@@ -28,16 +28,15 @@ export type LivenessState =
 
 export type FeedbackMessage =
   | 'Position your face in the circle'
-  | 'Move closer'
-  | 'Move farther away'
-  | 'Look straight ahead'
-  | 'Hold still...'
-  | 'Stay still'
+  | 'Turn your head slightly'
+  | 'Now look straight ahead'
+  | 'Now blink'
   | 'Liveness confirmed'
   | '';
 
 export type CaptureResult = {
   photo: PhotoFile;
+  /** Always 1.0 — all challenges were passed before capture. */
   livenessScore: number;
   timestamp: number;
 };
@@ -63,19 +62,6 @@ export type LivenessCameraProps = {
    */
   countdownFrom?: number;
 
-  /**
-   * Per-frame score (0–1) a frame must reach to count as a good frame.
-   * Defaults to 0.65. Scored on face presence, size, and head pose only —
-   * eye openness is not used (passive detection, no gestures required).
-   */
-  livenessThreshold?: number;
-
-  /**
-   * Number of consecutive good frames required to confirm liveness.
-   * Defaults to 7 (~350ms at 20fps).
-   */
-  confirmFrames?: number;
-
   /**
    * Style applied to the root container.
    */

package/src/useLivenessCamera.ts

@@ -3,7 +3,7 @@ import type { Camera, Frame } from 'react-native-vision-camera';
 import { runAtTargetFps, useFrameProcessor } from 'react-native-vision-camera';
 import { Worklets } from 'react-native-worklets-core';
 import { useLivenessPlugin } from './LivenessDetector';
-import { getFeedback, rollingAverage, scoreFrame } from './livenessScoring';
+import { CHALLENGE_STEPS } from './livenessScoring';
 import type {
   CaptureResult,
   FaceData,
@@ -11,14 +11,9 @@ import type {
   LivenessState,
 } from './types';
 
-const WINDOW_SIZE = 20;
-// How many frames to decay consecutiveGood by on a bad frame.
-// 1 means a single noisy/blink frame only undoes one good frame.
-const CONSECUTIVE_DECAY = 1;
+const TOTAL_STEPS = CHALLENGE_STEPS.length;
 
 type Options = {
-  livenessThreshold: number;
-  confirmFrames: number;
   countdownFrom: number;
   soundEnabled: boolean;
   cameraRef: React.RefObject<Camera | null>;
@@ -29,6 +24,7 @@ type Options = {
 
 type LivenessCameraState = {
   livenessState: LivenessState;
+  /** Challenge progress 0–1. Drives the arc. */
   livenessScore: number;
   countdown: number | null;
   feedback: FeedbackMessage;
@@ -36,8 +32,6 @@ type LivenessCameraState = {
 
 export function useLivenessCamera(options: Options) {
   const {
-    livenessThreshold,
-    confirmFrames,
     countdownFrom,
     soundEnabled,
     cameraRef,
@@ -48,27 +42,17 @@ export function useLivenessCamera(options: Options) {
 
   const plugin = useLivenessPlugin();
 
-  // Mutable refs — updated every frame, never cause re-renders
-  const frameScores = useRef<number[]>([]);
-  const consecutiveGood = useRef(0);
-  const frameWidth = useRef(0);
+  // ── Step machine refs — mutated every frame, never cause re-renders ────────
+  const currentStepIdx = useRef(0);
+  const stepFrameCount = useRef(0);
   const stateRef = useRef<LivenessState>('scanning');
   const isCaptured = useRef(false);
 
-  // Feedback debouncing: only update the displayed text after the same message
-  // has been stable for FEEDBACK_DEBOUNCE_MS. Prevents rapid flickering when
-  // ML Kit oscillates between two states on consecutive frames.
-  const FEEDBACK_DEBOUNCE_MS = 400;
-  const feedbackTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const pendingFeedback = useRef<FeedbackMessage>(
-    'Position your face in the circle'
-  );
-
   const [state, setState] = useState<LivenessCameraState>({
     livenessState: 'scanning',
     livenessScore: 0,
     countdown: null,
-    feedback: 'Position your face in the circle',
+    feedback: CHALLENGE_STEPS[0]!.instruction,
   });
 
   const setLivenessState = useCallback((next: LivenessState) => {
@@ -76,37 +60,29 @@ export function useLivenessCamera(options: Options) {
     setState((prev) => ({ ...prev, livenessState: next }));
   }, []);
 
-  // ─── Capture ──────────────────────────────────────────────────────────────
-
+  // ── Capture ────────────────────────────────────────────────────────────────
   const capture = useCallback(async () => {
     if (isCaptured.current || !cameraRef.current) return;
     isCaptured.current = true;
-
     setLivenessState('capturing');
-
     try {
       const photo = await cameraRef.current.takePhoto({
         flash: 'off',
         enableShutterSound: soundEnabled,
       });
-      const score = rollingAverage(frameScores.current);
-
       setLivenessState('done');
-      onCapture({ photo, livenessScore: score, timestamp: Date.now() });
+      onCapture({ photo, livenessScore: 1, timestamp: Date.now() });
     } catch (err) {
       setLivenessState('error');
       onError?.(err instanceof Error ? err : new Error(String(err)));
     }
   }, [cameraRef, onCapture, onError, soundEnabled, setLivenessState]);
 
-  // ─── Countdown ────────────────────────────────────────────────────────────
-
+  // ── Countdown ──────────────────────────────────────────────────────────────
   const startCountdown = useCallback(() => {
     setLivenessState('countdown');
     let tick = countdownFrom;
-
     setState((prev) => ({ ...prev, countdown: tick }));
-
     const interval = setInterval(() => {
       tick -= 1;
       if (tick <= 0) {
@@ -117,23 +93,21 @@ export function useLivenessCamera(options: Options) {
         setState((prev) => ({ ...prev, countdown: tick }));
       }
     }, 1000);
-
     return () => clearInterval(interval);
   }, [capture, countdownFrom, setLivenessState]);
 
-  // ─── Per-frame face handler (runs on JS thread, called from worklet) ──────
-
+  // ── Per-frame face handler (runs on JS thread, called from worklet) ────────
   const handleFaceData = useCallback(
     (face: FaceData | null, width: number) => {
+      const s = stateRef.current;
       if (
-        stateRef.current === 'capturing' ||
-        stateRef.current === 'done' ||
-        stateRef.current === 'error'
-      ) {
+        s === 'confirmed' ||
+        s === 'countdown' ||
+        s === 'capturing' ||
+        s === 'done' ||
+        s === 'error'
+      )
         return;
-      }
-
-      frameWidth.current = width;
 
       const safeFace: FaceData = face ?? {
         detected: false,
@@ -146,65 +120,54 @@ export function useLivenessCamera(options: Options) {
         smilingProbability: -1,
       };
 
-      const { total } = scoreFrame(safeFace, width);
-
-      frameScores.current.push(total);
-      if (frameScores.current.length > WINDOW_SIZE) {
-        frameScores.current.shift();
-      }
-
-      const avgScore = rollingAverage(frameScores.current);
+      const step = CHALLENGE_STEPS[currentStepIdx.current]!;
+      const stepMet = step.check(safeFace, width);
 
-      // Decay on bad frames instead of hard reset — one noisy ML Kit result
-      // won't wipe out progress the user has already built up.
-      if (total >= livenessThreshold) {
-        consecutiveGood.current += 1;
+      // Advance or gently decay the frame counter
+      if (stepMet) {
+        stepFrameCount.current += 1;
       } else {
-        consecutiveGood.current = Math.max(
-          0,
-          consecutiveGood.current - CONSECUTIVE_DECAY
-        );
+        stepFrameCount.current = Math.max(0, stepFrameCount.current - 1);
       }
 
-      // Consecutive-frames gate only. The avgScore is displayed on the arc but
-      // not used as a confirmation gate — the rolling window starts empty so
-      // early frames (before the face was positioned) drag the average down and
-      // would prevent confirmation even when the face is clearly live.
-      const isLive = consecutiveGood.current >= confirmFrames;
-
-      // Debounce the feedback text: only apply a new message after it has been
-      // stable for FEEDBACK_DEBOUNCE_MS, preventing rapid label flickering.
-      const newFeedback = getFeedback(safeFace, width, isLive);
-      if (newFeedback !== pendingFeedback.current) {
-        pendingFeedback.current = newFeedback;
-        if (feedbackTimer.current) clearTimeout(feedbackTimer.current);
-        feedbackTimer.current = setTimeout(() => {
+      // Step complete?
+      if (stepFrameCount.current >= step.framesRequired) {
+        stepFrameCount.current = 0;
+        const nextIdx = currentStepIdx.current + 1;
+
+        if (nextIdx >= TOTAL_STEPS) {
+          // All challenges done — confirm liveness
+          setState((prev) => ({
+            ...prev,
+            livenessScore: 1,
+            feedback: 'Liveness confirmed',
+          }));
+          setLivenessState('confirmed');
+          onLivenessConfirmed?.();
+          startCountdown();
+        } else {
+          // Advance to next challenge
+          currentStepIdx.current = nextIdx;
           setState((prev) => ({
             ...prev,
-            feedback: pendingFeedback.current,
+            livenessScore: nextIdx / TOTAL_STEPS,
+            feedback: CHALLENGE_STEPS[nextIdx]!.instruction,
           }));
-        }, FEEDBACK_DEBOUNCE_MS);
+        }
+        return;
       }
 
-      setState((prev) => ({ ...prev, livenessScore: avgScore }));
-
-      if (isLive && stateRef.current === 'scanning') {
-        setLivenessState('confirmed');
-        onLivenessConfirmed?.();
-        startCountdown();
-      }
+      // Smooth arc progress within the current step
+      const progress =
+        (currentStepIdx.current +
+          stepFrameCount.current / step.framesRequired) /
+        TOTAL_STEPS;
+      setState((prev) => ({ ...prev, livenessScore: progress }));
     },
-    [
-      confirmFrames,
-      livenessThreshold,
-      onLivenessConfirmed,
-      setLivenessState,
-      startCountdown,
-    ]
+    [onLivenessConfirmed, setLivenessState, startCountdown]
   );
 
-  // ─── Frame processor ──────────────────────────────────────────────────────
-
+  // ── Frame processor ────────────────────────────────────────────────────────
   const handleFaceDataJS = useMemo(
     () => Worklets.createRunOnJS(handleFaceData),
     [handleFaceData]
@@ -213,8 +176,6 @@ export function useLivenessCamera(options: Options) {
   const frameProcessor = useFrameProcessor(
     (frame: Frame) => {
       'worklet';
-      // Camera preview renders at full fps (60). ML Kit only needs ~20fps —
-      // running it on every frame would block the render thread unnecessarily.
       runAtTargetFps(20, () => {
         'worklet';
         const face = plugin.detectLiveness(frame);
@@ -226,10 +187,9 @@ export function useLivenessCamera(options: Options) {
 
   useEffect(() => {
     return () => {
-      frameScores.current = [];
-      consecutiveGood.current = 0;
+      currentStepIdx.current = 0;
+      stepFrameCount.current = 0;
       isCaptured.current = false;
-      if (feedbackTimer.current) clearTimeout(feedbackTimer.current);
     };
   }, []);