flutter_face_liveness 2.7.0

Production-ready Flutter SDK for face detection, liveness verification, and anti-spoof protection using ML Kit and TensorFlow Lite.

2.7.0

Bug Fixes

• iOS headLeft / headRight detection inverted — iOS front-camera delivers horizontally-mirrored BGRA8888 frames; _buildInputImage() passes them to ML Kit with rotation0deg and no mirror correction. This caused ML Kit to report a flipped headEulerAngleY sign: physical right turn produced positive yaw (mapped to turnLeft), physical left turn produced negative yaw (mapped to turnRight). Fixed in FaceData.fromFace() by negating headEulerAngleY on Platform.isIOS, aligning both platforms to the same convention (positive yaw = user physically turned left). Android is unaffected — ML Kit's sensor-rotation correction already provides the correct sign there.

---

2.5.0

Bug Fixes

• Added library; declaration to flutter_face_liveness.dart — fixes dangling library doc comment lint warning
• Enclosed for loop body in face_embedding_model.dart with braces — fixes curly_braces_in_flow_control_structures lint warning
• Wrapped home screen Column in SingleChildScrollView in example app — fixes RenderFlex overflow on small screens; replaced Spacer() with SizedBox(height: 20) (Spacer is incompatible with scroll views)

---

2.6.0

Improvements

• Added Swift Package Manager (SPM) support for iOS — ios/flutter_face_liveness/Package.swift added with correct Sources/ structure

Bug Fixes

• Removed unnecessary as List<double> cast in TFLiteService._runInference() (line 88) — type was already inferred correctly from List.filled
• Removed unused _Float32Reshape extension on Float32List — reshape() call it depended on was already commented out

---

2.2.0

Improvements

• Added banner image to README for pub.dev and GitHub documentation
• Upgraded Android Gradle Plugin to 8.9.1 (required by androidx.camera:1.6.0)
• Upgraded Gradle wrapper to 8.11.1
• Updated permission_handler to ^12.0.1 (requires Flutter 3.24+ / Dart 3.5+)
• Example app Face ID history screen — locally stores and displays all registered Face IDs with match/new status

---

2.0.0

New Features

Persistent Face Identity (Face ID)

• FaceIdentityService — assigns a stable FID-XXXX identifier to each unique face that persists across all app sessions using SharedPreferences
• FaceEmbeddingModel — wraps a FaceNet TFLite model (128-dim L2-normalised embeddings); model is auto-downloaded on first use (~23 MB, cached permanently)
• FaceModelDownloader — streaming HTTP download with progress callback; primary URL + fallback URL; re-downloads automatically if the cached file is corrupted
• FacePreprocessor — crops + resizes face region to 160×160, normalises pixels to [-1, 1]; runs in a compute() isolate; handles both NV21 (Android) and BGRA8888 (iOS) input
• LivenessConfig.enableFaceId flag (default false) — zero-config opt-in; no model file to bundle
• LivenessConfig.faceIdSimilarityThreshold (default 0.65) — cosine-similarity cutoff for same-face matching
• LivenessResult.faceId — returned alongside sessionId on successful verification
• LivenessController.clearFaceIdentities() — removes all stored embeddings (e.g. on logout)
• Embedding adaptation — stored embedding is updated toward each confirmed new observation (75% old + 25% new, then re-normalised) so the template improves over time

Isolate-based ML Preprocessing

• FrameProcessor — YUV→NV21 conversion, brightness, blur score, and FNV-1a hash all computed in a background compute() isolate; UI thread stays at 60 fps

Frame Quality Validation

• Per-frame brightness check with debounce (6 consecutive bad frames required before reporting lowLight/overExposed, absorbing camera auto-exposure settling time)
• Platform-correct brightness calculation: iOS BGRA8888 uses BT.601 luminance (Y = (77R + 150G + 29B) >> 8); Android NV21 uses Y-plane directly
• Blur detection via Y-plane variance

Anti-Spoof Engine

• 7-signal composite scoring: eye variance, face geometry, head pose naturalness, eye-open probability, face tracking continuity, micro-motion (yaw/pitch variance), and frame quality
• Rolling 12-frame history — no model file required

Security

• SessionManager — cryptographically unique session IDs using Random.secure() (12-char timestamp hex + 8-char secure random hex, e.g. LV-018F3A2B9C4E-D7E31F08)
• FrameHasher — FNV-1a sliding-window replay detection
• Fisher-Yates shuffle for randomised action sequences

New Liveness Action

• LivenessAction.openMouth — detected via bounding-box height growth (>8%) with low smile probability

UI

• LivenessStepIndicator — animated progress dots for current / completed / remaining steps
• Download-progress loading screen — shows % while FaceNet model downloads on first run
• Dark / light theme support via LivenessConfig.themeMode
• @Deprecated showDebugInfo — replaced by LivenessConfig.showDebugOverlay

New Exports

• FaceIdentityService, FaceModelDownloader, FaceModelDownloadException
• AntiSpoofEngine, AntiSpoofResult, TFLiteService
• SessionManager, RawFrameData

Bug Fixes

• iOS brightness falsely reported as "too dark" — single-plane BGRA frames were being sampled as if they were NV21 Y-plane data (Blue channel average ≠ luminance); fixed with BT.601 per-pixel luminance
• iOS face crop height clamping — _resampleBgra used w-1 for both axes; portrait/landscape frames could produce out-of-bounds crops; fixed to h-1 for the Y axis
• iOS raw frame bytes mismatch — RawFrameData stored NV21-converted bytes even on iOS where FacePreprocessor expects BGRA8888; now stores image.planes[0].bytes (original BGRA) on iOS
• Same face → different Face ID — similarity threshold 0.78 was too strict for cross-session lighting/angle variation; lowered to 0.65; stored embedding now adapts toward each confirmed match
• Session ID collision — old generator used deterministic XOR of timestamp; replaced with Random.secure()
• tflite_flutter 0.10.4 compilation failure on Dart ≥ 3.4 — UnmodifiableUint8ListView was removed from dart:typed_data; resolved by overriding to tflite_flutter git main (v0.12.1)
• completedActions / remainingActions not defined on LivenessController — fixed broken _EngineSequence extension; getters added directly to controller
• brightness > 0.90 false overexposure — threshold raised to 0.92 to match real sensor output

Breaking Changes

• Android minSdkVersion raised from 21 → 26 — required by tflite_flutter 0.12.1
• LivenessResult gains optional faceId field (non-breaking; null when enableFaceId is false)
• brightnessMin default changed from 0.20 → 0.12
• brightnessMax default changed from 0.90 → 0.92

Dependencies Added

tflite_flutter: (git main — v0.12.1)
shared_preferences: ^2.2.2
http: ^1.2.1
path_provider: ^2.1.3

---

1.0.0

• Initial release
• Real-time face detection via Google ML Kit Face Detection
• Liveness actions: blink, turnLeft, turnRight, lookUp, lookDown, smile
• Anti-spoofing heuristic validator (5-signal composite score)
• Animated face overlay with status indicator and progress bar
• Clean architecture: Camera → ML → Liveness engine → UI layers
• Full null-safety support (Dart 3 / Flutter 3.10+)
• Android API 21+ and iOS 13+ support
• Example app with standard and custom challenge modes