react-native-vision-camera-spoof-detector 1.1.26 → 1.2.0

package/README.md

@@ -3,31 +3,31 @@
 [![npm version](https://badge.fury.io/js/react-native-vision-camera-spoof-detector.svg)](https://badge.fury.io/js/react-native-vision-camera-spoof-detector)
 [![GitHub](https://img.shields.io/badge/GitHub-Repository-blue)](https://github.com/dpraful/react-native-vision-camera-spoof-detector)
 
-High-performance face anti-spoofing and liveness detection module for React Native Vision Camera. Features TensorFlow Lite with GPU acceleration, optimized YUV processing, and real-time blink detection for robust liveness verification.
+High-performance face anti-spoofing and liveness detection for React Native Vision Camera. The current implementation exposes a native Vision Camera output that processes frames on Android and iOS and reports a `FaceAntiSpoofingResult` back to JavaScript.
 
-## 🎯 Features
+## Features
 
-- **🚀 Real-time Performance**: GPU-accelerated TensorFlow Lite processing for smooth 60fps detection
-- **🎯 High Accuracy**: Advanced ML models for distinguishing live faces from spoofing attempts
-- **👁️ Blink Detection**: Native blink detection for enhanced liveness verification
-- **📱 Optimized YUV Processing**: Efficient image data handling for React Native
-- **🔧 Easy Integration**: Seamlessly integrates with `react-native-vision-camera`
-- **⚡ Face Stability Tracking**: Automatic stable face detection with customizable thresholds
-- **🛡️ Face Centering**: Intelligent face positioning validation in frame
-- **📊 Anti-spoofing Confidence**: Detailed confidence scores with multiple detection models
-- **🔄 Batched Updates**: Optimized state management with minimal re-renders
+- Native Android and iOS detection pipeline
+- Vision Camera 5 `CameraOutput` integration via Nitro hybrid objects
+- TensorFlow Lite inference with GPU or NNAPI fallback on Android
+- Optimized BGRA/RGBA frame sampling, filtering, and resolution handling
+- JS callbacks for `onResult` and `onError`
+- Optional explicit availability and initialization checks
+- No separate face-detector output is required for the basic anti-spoof camera-output flow
 
-## 📋 Requirements
+## Requirements
 
-- React Native >= 0.76.0
-- React Native Vision Camera `^5.0.0`
+- React Native `>= 0.60.0` (Vision Camera 5.x usage is the intended path)
+- `react-native-vision-camera` `^5.0.0`
+- `react-native-nitro-modules` `^0.37.1`
+- `react-native-worklets` `^0.12.0`
 - `react-native-vision-camera-worklets` `^5.0.0`
 - iOS 11.0 or later
-- `react-native-vision-camera-face-detector` (required for the face-gated example below)
+- Android support through the package's native modules and bundled TensorFlow Lite model
 
-## 📦 Installation
+## Installation
 
-### Step 1: Install the package
+### 1) Install package
 
 ```bash
 npm install react-native-vision-camera-spoof-detector
@@ -35,17 +35,17 @@ npm install react-native-vision-camera-spoof-detector
 yarn add react-native-vision-camera-spoof-detector
 ```
 
-### Step 2: Install peer dependencies
+### 2) Install required peer dependencies
 
 ```bash
-npm install react-native-vision-camera react-native-reanimated react-native-worklets react-native-vision-camera-worklets react-native-vision-camera-face-detector
+npm install react-native-vision-camera react-native-nitro-modules react-native-worklets react-native-vision-camera-worklets
 # or
-yarn add react-native-vision-camera react-native-reanimated react-native-worklets react-native-vision-camera-worklets react-native-vision-camera-face-detector
+yarn add react-native-vision-camera react-native-nitro-modules react-native-worklets react-native-vision-camera-worklets
 ```
 
-### Step 3: Configure iOS
+### 3) iOS setup
 
-Install the CocoaPods dependencies from the iOS directory:
+Run pod install for the app:
 
 ```bash
 cd ios
@@ -53,87 +53,66 @@ pod install
 cd ..
 ```
 
-Add a camera usage description to `ios/<YourApp>/Info.plist`:
+Add camera permission text to the app Info.plist:
 
 ```xml
 <key>NSCameraUsageDescription</key>
 <string>This app uses the camera for face liveness verification.</string>
 ```
 
-Open the generated `.xcworkspace` in Xcode, or run the app with the React Native CLI. The package pod bundles `FaceAntiSpoofing.tflite` and declares its `TensorFlowLiteSwift` and `VisionCamera` dependencies automatically. No manual model copy is required.
+### 4) Android setup
 
-### Step 4: Configure Android (if not auto-linked)
+For modern React Native projects, the native module is auto-linked by the app build. If your project is not auto-linked, ensure the library is included in the app build and Gradle resolves the Android native dependencies.
 
-Add to `android/app/build.gradle`:
+## Quick start
 
-```gradle
-dependencies {
-    implementation project(':react-native-vision-camera-spoof-detector')
-}
-```
-
-### Step 5: Link native module (for React Native < 0.60)
-
-```bash
-react-native link react-native-vision-camera-spoof-detector
-```
-
-## 🚀 Quick Start
-
-Vision Camera 5 uses camera outputs for this package. The anti-spoof output can be combined with the face detector output and enabled only while a face is visible.
+This package exposes a native output hook that can be attached directly to the `Camera` component.
 
-```javascript
-import React, { useEffect, useState } from 'react';
-import { StyleSheet, Text, useWindowDimensions, View } from 'react-native';
+```tsx
+import React, { useEffect } from 'react';
+import { SafeAreaView, Text, View, StyleSheet } from 'react-native';
 import {
   Camera,
   useCameraDevice,
   useCameraPermission,
 } from 'react-native-vision-camera';
-import { useFaceDetectorOutput } from 'react-native-vision-camera-face-detector';
 import { useFaceAntiSpoofFrameOutput } from 'react-native-vision-camera-spoof-detector';
 
-const CameraScreen = () => {
+export default function AntiSpoofScreen() {
   const device = useCameraDevice('front');
   const { hasPermission, requestPermission } = useCameraPermission();
-  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
-  const [faces, setFaces] = useState([]);
-  const [detectionError, setDetectionError] = useState(null);
-  const [spoofResult, setSpoofResult] = useState(null);
 
   useEffect(() => {
-    if (!hasPermission) requestPermission();
+    if (!hasPermission) {
+      requestPermission();
+    }
   }, [hasPermission, requestPermission]);
 
-  const faceDetectorOutput = useFaceDetectorOutput({
-    cameraFacing: 'front',
-    autoMode: true,
-    windowWidth,
-    windowHeight,
-    performanceMode: 'fast',
-    trackingEnabled: true,
-    onFacesDetected(detectedFaces) {
-      setDetectionError(null);
-      setFaces(detectedFaces);
-      if (detectedFaces.length === 0) setSpoofResult(null);
-    },
-    onError(error) {
-      setDetectionError(error.message);
-    },
-  });
-
   const antiSpoofOutput = useFaceAntiSpoofFrameOutput({
+    targetResolution: { width: 720, height: 1280 },
     onResult(result) {
-      setSpoofResult(result);
+      console.log('anti-spoof result:', result);
+    },
+    onError(error) {
+      console.warn('anti-spoof error:', error);
     },
   });
 
-  const outputs = faces.length > 0
-    ? [faceDetectorOutput, antiSpoofOutput]
-    : [faceDetectorOutput];
-
-  if (!hasPermission) return <Message text="Camera permission is required." />;
-  if (!device) return <Message text="No front camera is available." />;
+  if (!hasPermission) {
+    return (
+      <SafeAreaView style={styles.centered}>
+        <Text>Camera permission is required.</Text>
+      </SafeAreaView>
+    );
+  }
+
+  if (!device) {
+    return (
+      <SafeAreaView style={styles.centered}>
+        <Text>No front camera available.</Text>
+      </SafeAreaView>
+    );
+  }
 
   return (
     <View style={styles.container}>
@@ -141,65 +120,33 @@ const CameraScreen = () => {
         style={StyleSheet.absoluteFill}
         device={device}
         isActive
-        outputs={outputs}
+        outputs={[antiSpoofOutput]}
       />
-
-      <View style={styles.statusContainer}>
-        <Text style={styles.statusText}>
-          {detectionError ?? `${faces.length} face${faces.length === 1 ? '' : 's'} detected`}
-        </Text>
-        <Text style={styles.statusText}>
-          {faces.length === 0
-            ? 'Waiting for face...'
-            : spoofResult
-              ? JSON.stringify(spoofResult)
-              : 'Anti-spoof processing...'}
-        </Text>
-      </View>
     </View>
   );
-};
-
-const Message = ({ text }) => (
-  <View style={styles.messageContainer}>
-    <Text style={styles.messageText}>{text}</Text>
-  </View>
-);
+}
 
 const styles = StyleSheet.create({
   container: { flex: 1 },
-  messageContainer: {
+  centered: {
     flex: 1,
-    alignItems: 'center',
     justifyContent: 'center',
-    paddingHorizontal: 24,
-  },
-  messageText: { fontSize: 16, textAlign: 'center' },
-  statusContainer: {
-    position: 'absolute',
-    top: 56,
-    alignSelf: 'center',
-    paddingHorizontal: 14,
-    paddingVertical: 8,
-    borderRadius: 16,
-    backgroundColor: 'rgba(0, 0, 0, 0.65)',
+    alignItems: 'center',
   },
-  statusText: { color: '#ffffff', fontSize: 14, marginVertical: 2 },
 });
-
-export default CameraScreen;
 ```
 
-The anti-spoof output callback receives a result after native inference. No manual `runOnJS`, frame processor, or explicit initialization call is required for this output API. The output may be omitted until a face is detected, as shown above.
+The callback fires from the native detection pipeline after each processed frame. This output path is designed to be used directly with the Vision Camera `outputs` array.
 
-## 📚 API Reference
+## API reference
 
 ### `useFaceAntiSpoofFrameOutput(options?)`
 
-Creates a Vision Camera 5 camera output for native anti-spoofing inference.
+Creates a native Vision Camera 5 output for anti-spoofing inference.
 
-```javascript
+```tsx
 const antiSpoofOutput = useFaceAntiSpoofFrameOutput({
+  targetResolution: { width: 720, height: 1280 },
   onResult(result) {
     console.log(result);
   },
@@ -209,178 +156,123 @@ const antiSpoofOutput = useFaceAntiSpoofFrameOutput({
 });
 ```
 
-Pass the returned output in the `Camera` component's `outputs` array. The callback runs on the React Native runtime after native inference.
+Returned value should be included in the `Camera` component `outputs` array.
+
+Options:
 
-**Options**: `onResult(result)` and optional `onError(error)`.
+```ts
+interface UseFaceAntiSpoofFrameOutputOptions {
+  targetResolution?: { width: number; height: number };
+  onResult?: (result: FaceAntiSpoofingResult) => void;
+  onError?: (error: Error) => void;
+}
+```
 
 ---
 
 ### `initializeFaceAntiSpoof()`
 
-Initializes the native module when an application needs an explicit startup check or model-loading diagnostics. It is not required when using `useFaceAntiSpoofFrameOutput()`.
+Starts the native module and performs a basic model/init check.
 
-```javascript
-const success = await initializeFaceAntiSpoof();
+```ts
+const initialized = await initializeFaceAntiSpoof();
 ```
 
-**Returns**: `Promise<boolean>` - True if successful
+Returns `Promise<boolean>`.
 
 ---
 
 ### `isFaceAntiSpoofAvailable()`
 
-Checks if the module is available on the device.
+Checks whether the native module is present for the current device/platform.
 
-```javascript
+```ts
 const available = isFaceAntiSpoofAvailable();
 ```
 
-**Returns**: `boolean`
+Returns `boolean`.
 
 ---
 
 ### `FaceAntiSpoofingResult`
 
-```typescript
+```ts
 interface FaceAntiSpoofingResult {
-  isLive: boolean;              // Real face (true) or spoof (false)
-  label: string;                // Usually "live", "spoof", or "error"
-  neuralNetworkScore: number;   // 0.0-1.0 confidence
-  laplacianScore: number;       // Image quality score
-  combinedScore: number;        // Weighted average
-  error?: string;               // Error message if any
+  isLive: boolean;
+  label: string;
+  neuralNetworkScore: number;
+  laplacianScore: number;
+  combinedScore: number;
+  confidence: number;
+  error?: string;
 }
 ```
 
-## 🔧 Configuration
-
-```javascript
-// Anti-spoofing sensitivity (0.0-1.0, lower = more lenient)
-const antispooflevel = 0.35;
-
-// Liveness verification mode
-// 0: Anti-spoofing only
-// 1: Anti-spoofing + blink detection
-const livenessLevel = 1;
-
-// Customizable thresholds
-const FACE_STABILITY_THRESHOLD = 3;           // Frames for stable face
-const FACE_MOVEMENT_THRESHOLD = 15;           // Max pixel movement
-const BLINK_THRESHOLD = 0.3;                  // Eye closure probability
-const REQUIRED_BLINKS = 3;                    // Blinks for liveness
-const REQUIRED_CONSECUTIVE_LIVE_FRAMES = 3;   // Consecutive live frames
-const REAL_LAPLACIAN_THRESHOLD = 3500;        // Image quality threshold
-const FACE_CENTER_THRESHOLD_X = 0.2;          // X-axis tolerance
-const FACE_CENTER_THRESHOLD_Y = 0.15;         // Y-axis tolerance
-```
-
-## 🎮 Complete Examples
-
-The [Quick Start](#-quick-start) above shows the basic frame-processor integration. For the complete capture flow, face detection, liveness, and UI patterns, see the [project wiki](https://github.com/dpraful/react-native-vision-camera-spoof-detector/wiki).
+Result fields:
 
-## 🔍 Attack Detection Capabilities
+- `isLive`: true for a likely real face, false for a spoof attempt
+- `label`: human-readable label such as `Live Face` or `Spoof Face`
+- `neuralNetworkScore`: raw model score from the TFLite classifier
+- `laplacianScore`: image variance / quality score used to detect blur or non-real textures
+- `combinedScore`: combined weighted score constructed by the native implementation
+- `confidence`: derived confidence value for the final decision
 
-The module detects and prevents:
-- ✅ Print attacks (photos)
-- ✅ Display attacks (screens/tablets)
-- ✅ Mask attacks (with blink detection)
-- ✅ Replay attacks (videos)
+## Android and iOS implementation notes
 
-Performance depends on:
-- Image quality
-- Lighting conditions
-- Face angle and positioning
-- Device camera specs
+### Android
 
-## ⚙️ Performance Tips
+- Uses a native `ImageAnalysis`-based output pipeline
+- Reads RGBA frame data and applies brightness / variance gating before inference
+- Uses the bundled TensorFlow Lite model and prefers GPU delegate, with NNAPI/CPU fallback
+- Normalizes frames for model input and returns a JS callback result after evaluation
 
-1. Use `performanceMode: 'fast'` in Face Detector
-2. Module automatically batches state updates
-3. Adjust `FRAME_PROCESSOR_MIN_INTERVAL_MS` as needed
-4. GPU acceleration is used automatically when available
-5. Proper frame release prevents memory leaks
+### iOS
 
-## 📱 Platform Support
+- Uses an `AVCaptureVideoDataOutput` pipeline with a native sample-buffer delegate
+- Converts BGRA pixel buffers to a normalized RGB input for the detector
+- Filters frames using brightness and variance checks before inference
+- Returns the evaluation result through the same `onResult` callback contract
 
-| Platform | Status | GPU | Notes |
-|----------|--------|-----|-------|
-| Android  | ✅ Supported | Yes | TensorFlow Lite model bundled in the AAR |
-| iOS      | ✅ Supported | CPU | Requires CocoaPods and iOS 11+ |
-| Web      | ❌ No | N/A | Not applicable |
+## Troubleshooting
 
-## 🐛 Troubleshooting
+### Module not available
 
-**Module won't initialize**
-```javascript
-const available = isFaceAntiSpoofAvailable();
-if (!available) {
-  console.log('Not available on this device');
+```ts
+if (!isFaceAntiSpoofAvailable()) {
+  console.warn('Face anti-spoofing native module is unavailable on this device.');
 }
 ```
 
-- iOS: run `pod install` from the `ios` directory and rebuild the app from the generated workspace.
-- iOS: verify `NSCameraUsageDescription` exists in the app's `Info.plist`.
-- Check the initialization promise result and inspect the native logs for model-loading errors.
-
-**Low accuracy**
-- Check lighting conditions
-- Ensure face is centered
-- Adjust `antispooflevel` parameter
-- Verify the `FaceAntiSpoofing.tflite` model is bundled (the package does this automatically on iOS)
-
-**Performance issues**
-- Reduce frame processing frequency
-- Use lower camera resolution
-- Enable fast performance mode
-- Check device temperature
-
-**Face detection fails**
-- Ensure clear face visibility
-- Check camera permissions
-- Verify sufficient lighting
-- Check minimum face size threshold
-
-## 📖 Documentation
+### iOS issues
 
-- [Project Wiki](https://github.com/dpraful/react-native-vision-camera-spoof-detector/wiki)
-- [Changelog](./CHANGELOG.md)
-- [Contributing Guide](./CONTRIBUTING.md)
+- Ensure `NSCameraUsageDescription` exists in the app's Info.plist
+- Run `pod install` inside the iOS folder after dependency updates
+- Rebuild the generated `.xcworkspace` in Xcode
 
-## 🤝 Contributing
+### Android issues
 
-Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+- Confirm the app has camera permissions
+- Ensure the module is properly linked in the app project
+- Check native logs for TFLite loading or delegate errors
 
-## 📄 License
+## Platform support
 
-JESCON TECHNOLOGIES PVT LTD License - see [LICENSE](./LICENSE) file for details.
+| Platform | GPU acceleration | Status | Notes |
+|----------|------------------|--------|-------|
+| Android | ✅ Yes | ✅ Supported | Uses TensorFlow Lite GPU delegate when available, with NNAPI/CPU fallback |
+| iOS | ✅ Yes | ✅ Supported | Uses TensorFlow Lite Metal GPU delegate when available, with CPU fallback |
+| Web | ❌ No | ❌ Not supported | Native camera processing only |
 
-## 👨‍💼 Author
+## License
 
-**PRAFULDAS M M**
-- Company: JESCON TECHNOLOGIES PVT LTD
-- Location: Thrissur, Kerala, India
-- Email: jescontechnologies@gmail.com
+MIT. See [LICENSE](./LICENSE).
 
-## 🔗 Quick Links
+## Repository
 
-- [NPM Package](https://www.npmjs.com/package/react-native-vision-camera-spoof-detector)
-- [GitHub Repository](https://github.com/dpraful/react-native-vision-camera-spoof-detector)
-- [React Native Vision Camera](https://react-native-vision-camera.com)
-- [TensorFlow Lite](https://www.tensorflow.org/lite)
+- GitHub: https://github.com/dpraful/react-native-vision-camera-spoof-detector
+- NPM: https://www.npmjs.com/package/react-native-vision-camera-spoof-detector
 
-## 📞 Support & Community
+## Author
 
-- 🐛 [Report Issues](https://github.com/dpraful/react-native-vision-camera-spoof-detector/issues)
-- 💬 [GitHub Discussions](https://github.com/dpraful/react-native-vision-camera-spoof-detector/discussions)
-- 📧 Email: jescontechnologies@gmail.com
-
-## 🙏 Acknowledgments
-
-Built with:
-- [TensorFlow Lite](https://www.tensorflow.org/lite)
-- [React Native Vision Camera](https://react-native-vision-camera.com)
-- [React Native Worklets](https://docs.swmansion.com/react-native-worklets/)
-
----
+JESCON TECHNOLOGIES PVT LTD
 
-Made with ❤️ by JESCON TECHNOLOGIES PVT LTD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-vision-camera-spoof-detector",
-  "version": "1.1.26",
+  "version": "1.2.0",
   "description": "High-performance face anti-spoofing and liveness detection module for React Native Vision Camera. Uses TensorFlow Lite with GPU acceleration and optimized YUV processing.",
   "homepage": "https://github.com/dpraful/react-native-vision-camera-spoof-detector",
   "repository": {