@rick427/react-native-liveness 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Richard
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LivenessCamera.podspec

@@ -0,0 +1,26 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "LivenessCamera"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "13.0" }
+  s.source       = { :git => "https://github.com/rick427/react-native-liveness.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.swift_version = "5.7"
+
+  # Vision Camera frame processor plugin
+  s.dependency "VisionCamera"
+
+  # ML Kit Face Detection
+  s.dependency "GoogleMLKit/FaceDetection", "~> 7.0"
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,167 @@
+# @rick427/react-native-liveness
+
+A React Native library for real-time **liveness detection** using the device's front camera. Powered by [Vision Camera v4](https://github.com/mrousavy/react-native-vision-camera) and **ML Kit Face Detection** — no server required, fully on-device.
+
+The library scores each camera frame against a set of liveness signals (face size, head pose, eye openness), confirms liveness after a sustained high-score window, then automatically counts down **3 → 2 → 1**, plays a shutter sound, and captures the photo.
+
+---
+
+## Features
+
+- Real-time passive liveness detection (no gestures required)
+- On-device ML — works fully offline (ML Kit)
+- Face guide oval with live feedback hints
+- Animated countdown (React Native built-in `Animated`)
+- Auto photo capture via Vision Camera's `takePhoto()`
+- Optional shutter sound
+- Fully typed TypeScript API
+
+---
+
+## Prerequisites
+
+Install and link these peer dependencies in your project before using `@rick427/react-native-liveness`:
+
+| Package | Version |
+|---|---|
+| `react-native-vision-camera` | `>= 4.0.0` |
+| `react-native-worklets-core` | `>= 1.0.0` |
+| `react-native-svg` | `>= 13.0.0` |
+
+```sh
+npm install react-native-vision-camera react-native-worklets-core react-native-svg
+```
+
+---
+
+## Installation
+
+```sh
+npm install @rick427/react-native-liveness
+# or
+yarn add @rick427/react-native-liveness
+```
+
+Then install the peer dependencies if you haven't already:
+
+```sh
+npm install react-native-vision-camera react-native-worklets-core react-native-svg
+cd ios && pod install
+```
+
+### iOS
+
+Add the ML Kit pod (already declared in the podspec, but run pod install):
+
+```sh
+cd ios && pod install
+```
+
+Add `NSCameraUsageDescription` to your `Info.plist`:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Camera access is required for liveness verification.</string>
+```
+
+### Android
+
+The ML Kit dependency is included in `build.gradle` automatically. No extra steps needed.
+
+---
+
+## Usage
+
+### Drop-in component
+
+```tsx
+import { LivenessCamera } from '@rick427/react-native-liveness';
+import type { CaptureResult } from '@rick427/react-native-liveness';
+
+export default function VerificationScreen() {
+  const handleCapture = (result: CaptureResult) => {
+    console.log('Photo path:', result.photo.path);
+    console.log('Liveness score:', result.livenessScore); // 0.0 – 1.0
+  };
+
+  return (
+    <LivenessCamera
+      style={{ flex: 1 }}
+      onCapture={handleCapture}
+      onLivenessConfirmed={() => console.log('Live face confirmed!')}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onCapture` | `(result: CaptureResult) => void` | **required** | Fired after photo is taken. |
+| `onLivenessConfirmed` | `() => void` | — | Fired the moment liveness is confirmed, before the countdown. |
+| `onError` | `(err: Error) => void` | — | Fired on unrecoverable errors. |
+| `countdownFrom` | `number` | `3` | Countdown start value. |
+| `livenessThreshold` | `number` | `0.75` | Score (0–1) required per frame to be considered live. |
+| `confirmFrames` | `number` | `15` | Consecutive high-score frames required (~500 ms at 30 fps). |
+| `soundEnabled` | `boolean` | `true` | Play the native system shutter sound on capture. Respects silent mode. |
+| `style` | `ViewStyle` | — | Style for the root container. |
+
+### CaptureResult
+
+```ts
+type CaptureResult = {
+  photo: PhotoFile;      // Vision Camera PhotoFile
+  livenessScore: number; // rolling average score at time of capture (0–1)
+  timestamp: number;     // Date.now() at capture
+};
+```
+
+---
+
+## How liveness scoring works
+
+Each camera frame is scored across four signals:
+
+| Signal | Weight | Detail |
+|---|---|---|
+| Face detected | 20% | ML Kit found a face in the frame |
+| Face size | 20% | Face width is 20%–65% of the frame (not too far, not too close) |
+| Head pose | 30% | Yaw < ±20° and pitch < ±20° from frontal |
+| Eyes open | 30% | Average of left/right eye open probability from ML Kit |
+
+A rolling window of the last 20 frame scores is maintained. Liveness is confirmed once `confirmFrames` consecutive frames all score above `livenessThreshold`.
+
+---
+
+## Architecture
+
+```
+Camera frame (30fps)
+  ↓  [worklet thread — Vision Camera frame processor]
+Native plugin (Swift / Kotlin)
+  → ML Kit Face Detection
+  → { bounds, yawAngle, pitchAngle, leftEyeOpenProbability, … }
+  ↓  [runOnJS → JS thread]
+useLivenessCamera hook
+  → scoreFrame() per frame
+  → rolling 20-frame window
+  → 15 consecutive frames > threshold → liveness confirmed
+  ↓
+Countdown 3 → 2 → 1  (React Native Animated)
+  ↓
+camera.takePhoto() → onCapture({ photo, livenessScore, timestamp })
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow and pull request guidelines.
+
+---
+
+## License
+
+MIT © [Richard](https://github.com/rick427)

package/android/build.gradle

@@ -0,0 +1,80 @@
+buildscript {
+  ext.LivenessCamera = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+    return LivenessCamera[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.livenesscamera"
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  kotlinOptions {
+    jvmTarget = "1.8"
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+
+  // Vision Camera
+  implementation "com.mrousavy.camera:react-native-vision-camera:+"
+
+  // ML Kit Face Detection
+  implementation "com.google.mlkit:face-detection:16.1.7"
+
+  // Google Play Services Tasks (for Tasks.await() synchronous execution)
+  implementation "com.google.android.gms:play-services-tasks:18.1.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/livenesscamera/LivenessCameraPackage.kt

@@ -0,0 +1,28 @@
+package com.livenesscamera
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+import com.mrousavy.camera.frameprocessors.FrameProcessorPluginRegistry
+
+class LivenessCameraPackage : ReactPackage {
+
+  companion object {
+    init {
+      // Register the frame processor plugin under the name "detectLiveness".
+      // JS side calls VisionCameraProxy.initFrameProcessorPlugin('detectLiveness').
+      FrameProcessorPluginRegistry.addFrameProcessorPlugin("detectLiveness") { proxy, options ->
+        LivenessCameraPlugin(proxy, options)
+      }
+    }
+  }
+
+  override fun createNativeModules(
+    reactContext: ReactApplicationContext
+  ): MutableList<NativeModule> = mutableListOf()
+
+  override fun createViewManagers(
+    reactContext: ReactApplicationContext
+  ): MutableList<ViewManager<*, *>> = mutableListOf()
+}

package/android/src/main/java/com/livenesscamera/LivenessCameraPlugin.kt

@@ -0,0 +1,63 @@
+package com.livenesscamera
+
+import android.media.Image
+import com.google.android.gms.tasks.Tasks
+import com.google.mlkit.vision.common.InputImage
+import com.google.mlkit.vision.face.FaceDetection
+import com.google.mlkit.vision.face.FaceDetectorOptions
+import com.mrousavy.camera.frameprocessors.Frame
+import com.mrousavy.camera.frameprocessors.FrameProcessorPlugin
+import com.mrousavy.camera.frameprocessors.VisionCameraProxyHolder
+
+class LivenessCameraPlugin(
+  proxy: VisionCameraProxyHolder,
+  options: Map<String, Any>?
+) : FrameProcessorPlugin(proxy, options) {
+
+  private val faceDetector = FaceDetection.getClient(
+    FaceDetectorOptions.Builder()
+      .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_FAST)
+      .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
+      .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_NONE)
+      .setContourMode(FaceDetectorOptions.CONTOUR_MODE_NONE)
+      .build()
+  )
+
+  override fun callback(frame: Frame, arguments: Map<String, Any>?): Any {
+    val mediaImage: Image = frame.image
+    val rotationDegrees = frame.orientation.toDegrees()
+
+    val inputImage = InputImage.fromMediaImage(mediaImage, rotationDegrees)
+
+    return try {
+      // Tasks.await blocks the frame-processor thread synchronously.
+      // ML Kit face detection is fast (~5-10ms) so this is acceptable.
+      val faces = Tasks.await(faceDetector.process(inputImage))
+
+      if (faces.isEmpty()) {
+        return mapOf("detected" to false)
+      }
+
+      val face = faces.first()
+      val box = face.boundingBox
+
+      mapOf(
+        "detected" to true,
+        "bounds" to mapOf(
+          "x" to box.left.toFloat(),
+          "y" to box.top.toFloat(),
+          "width" to box.width().toFloat(),
+          "height" to box.height().toFloat()
+        ),
+        "yawAngle" to face.headEulerAngleY,
+        "pitchAngle" to face.headEulerAngleX,
+        "rollAngle" to face.headEulerAngleZ,
+        "leftEyeOpenProbability" to (face.leftEyeOpenProbability ?: -1f),
+        "rightEyeOpenProbability" to (face.rightEyeOpenProbability ?: -1f),
+        "smilingProbability" to (face.smilingProbability ?: -1f)
+      )
+    } catch (e: Exception) {
+      mapOf("detected" to false)
+    }
+  }
+}

package/ios/LivenessCameraPlugin-Bridging-Header.h

@@ -0,0 +1,3 @@
+#import <VisionCamera/FrameProcessorPlugin.h>
+#import <VisionCamera/FrameProcessorPluginRegistry.h>
+#import <VisionCamera/VisionCameraProxyHolder.h>

package/ios/LivenessCameraPlugin.m

@@ -0,0 +1,8 @@
+#import <VisionCamera/FrameProcessorPlugin.h>
+#import <VisionCamera/FrameProcessorPluginRegistry.h>
+#import <VisionCamera/VisionCameraProxyHolder.h>
+
+// Registers the Swift class "LivenessCameraPlugin" under the JS name "detectLiveness".
+// VisionCameraProxy.initFrameProcessorPlugin('detectLiveness') on the JS side
+// will resolve to this class.
+VISION_EXPORT_FRAME_PROCESSOR(LivenessCameraPlugin, detectLiveness)

package/ios/LivenessCameraPlugin.swift

@@ -0,0 +1,69 @@
+import VisionCamera
+import MLKitFaceDetection
+import MLKitVision
+import UIKit
+import AVFoundation
+
+@objc(LivenessCameraPlugin)
+public class LivenessCameraPlugin: FrameProcessorPlugin {
+
+  private var faceDetector: FaceDetector
+
+  public override init(
+    proxy: VisionCameraProxyHolder,
+    options: [AnyHashable: Any]? = [:]
+  ) {
+    let detectorOptions = FaceDetectorOptions()
+    detectorOptions.performanceMode = .fast
+    detectorOptions.classificationMode = .all   // gives eye/smile probabilities
+    detectorOptions.landmarkMode = .none
+    detectorOptions.contourMode = .none
+    detectorOptions.isTrackingEnabled = false
+    self.faceDetector = FaceDetector.faceDetector(options: detectorOptions)
+    super.init(proxy: proxy, options: options)
+  }
+
+  public override func callback(
+    _ frame: Frame,
+    withArguments arguments: [AnyHashable: Any]?
+  ) -> Any {
+    // Vision Camera frames arrive rotated 90° — swap width/height for ML Kit
+    let image = VisionImage(buffer: frame.buffer)
+    image.orientation = imageOrientation(from: frame.orientation)
+
+    do {
+      let faces = try faceDetector.results(in: image)
+      guard let face = faces.first else {
+        return ["detected": false]
+      }
+
+      return [
+        "detected": true,
+        "bounds": [
+          "x": face.frame.origin.x,
+          "y": face.frame.origin.y,
+          "width": face.frame.size.width,
+          "height": face.frame.size.height,
+        ],
+        "yawAngle": face.headEulerAngleY,
+        "pitchAngle": face.headEulerAngleX,
+        "rollAngle": face.headEulerAngleZ,
+        "leftEyeOpenProbability": face.leftEyeOpenProbability,
+        "rightEyeOpenProbability": face.rightEyeOpenProbability,
+        "smilingProbability": face.smilingProbability,
+      ]
+    } catch {
+      return ["detected": false]
+    }
+  }
+
+  // MARK: - Helpers
+
+  private func imageOrientation(
+    from orientation: UIImage.Orientation
+  ) -> UIImage.Orientation {
+    // Vision Camera already exposes the correct UIImage.Orientation from
+    // frame.orientation in v4; return it directly for ML Kit.
+    return orientation
+  }
+}