@sssxyd/face-liveness-detector 0.2.31 → 0.2.33

package/README.md

@@ -31,53 +31,6 @@ pnpm add @sssxyd/face-liveness-detector @vladmandic/human @techstark/opencv-js
 
 > **Note**: `@vladmandic/human` and `@techstark/opencv-js` are peer dependencies and must be installed separately to avoid bundling large libraries. This keeps your final bundle size smaller if you're already using these libraries elsewhere in your project.
 
-## Quick Start - Using Local Model Files (Recommended)
-
-To improve performance and reduce external dependencies, you can download and use local copies of model files:
-
-### Step 1: Download Model Files
-
-```bash
-# Copy Human.js models locally
-node copy-human-models.js
-
-# Download TensorFlow.js WASM files
-node download-tensorflow-wasm.js
-```
-
-This will create:
-- `public/models/` - Human.js face detection models
-- `public/wasm/` - TensorFlow.js WASM backend files
-
-### Step 2: Initialize Engine with Local Files
-
-```typescript
-import FaceDetectionEngine from '@sssxyd/face-liveness-detector'
-
-// Configure to use local model files
-const engine = new FaceDetectionEngine({
-  human_model_path: '/models',      // Path to downloaded models
-  tensorflow_wasm_path: '/wasm',    // Path to WASM files
-  min_face_ratio: 0.5,
-  max_face_ratio: 0.9,
-  liveness_action_count: 1,
-  liveness_action_list: ['blink']
-})
-
-// Initialize and start detection
-await engine.initialize()
-const videoElement = document.getElementById('video') as HTMLVideoElement
-await engine.startDetection(videoElement)
-```
-
-### Step 3: Serve Static Files
-
-Make sure your web server serves the `public/` directory:
-
-```typescript
-// Express.js example
-app.use(express.static('public'))
-```
 
 ## Quick Start - Using Default CDN Files
 

package/dist/index.esm.js

@@ -310,21 +310,26 @@ function _isWebGLAvailable() {
 }
 function _detectBrowserEngine(userAgent) {
     const ua = userAgent.toLowerCase();
-    // 检测 Gecko (Firefox)
+    // 1. 检测 Gecko (Firefox)
     if (/firefox/i.test(ua) && !/seamonkey/i.test(ua)) {
         return 'gecko';
     }
-    // 检测 WebKit (Safari, iOS browsers)
-    // Safari 的特征：有 Safari 但没有 Chrome
-    if (/safari/i.test(ua) && !/chrome|chromium|crios|edge|edgios|edg|brave|opera|vivaldi|whale|arc|yabrowser|samsung|kiwi|ghostery/i.test(ua)) {
-        return 'webkit';
-    }
-    // 检测 Chromium/Blink
+    // 2. 检测 Chromium/Blink（必须在 WebKit 之前，因为 Chrome 的 user-agent 也包含 WebKit）
     // Chrome-based browsers: Chrome, Chromium, Edge, Brave, Opera, Vivaldi, Whale, Arc, etc.
     if (/chrome|chromium|crios|edge|edgios|edg|brave|opera|vivaldi|whale|arc|yabrowser|samsung|kiwi|ghostery/i.test(ua)) {
         return 'chromium';
     }
-    // 默认为 other
+    // 3. 检测 WebKit（真正的 Safari 和 iOS 浏览器）
+    // 注意：真正的 WebKit 浏览器（Safari）user-agent 不包含 Chrome 标识
+    // 包括：Safari、iOS 浏览器、以及那些虽然包含 Chrome 标识但实际是 WebKit 的浏览器（Quark、支付宝、微信等）
+    if (/webkit/i.test(ua)) {
+        // WebKit 特征明显，包括以下几种情况：
+        // - 真正的 Safari（有 Safari 标识）
+        // - iOS 浏览器（有 Mobile Safari 标识）
+        // - Quark、支付宝、微信等虽然包含 Chrome 标识但是基于 WebKit 的浏览器
+        return 'webkit';
+    }
+    // 4. 其他浏览器 - 保守方案，使用 WASM
     return 'other';
 }
 function _getOptimalBackendForEngine(engine) {
@@ -563,15 +568,11 @@ function getCvSync() {
     return null;
 }
 /**
- * Load Human.js
- * @param modelPath - Path to model files (optional)
- * @param wasmPath - Path to WASM files (optional)
- * @param preferredBackend - Preferred TensorFlow backend: 'auto' | 'webgl' | 'wasm' (default: 'auto')
- * @returns Promise that resolves with Human instance
+ * Create Human.js configuration object
  */
-async function loadHuman(modelPath, wasmPath, preferredBackend) {
+function _createHumanConfig(backend, modelPath, wasmPath) {
     const config = {
-        backend: _detectOptimalBackend(preferredBackend),
+        backend,
         face: {
             enabled: true,
             detector: { rotation: false, return: true },
@@ -585,102 +586,196 @@ async function loadHuman(modelPath, wasmPath, preferredBackend) {
         object: { enabled: false },
         gesture: { enabled: true }
     };
-    // 只在提供了路径时才设置，否则让 Human.js 使用默认加载策略
     if (modelPath) {
         config.modelBasePath = modelPath;
     }
     if (wasmPath) {
         config.wasmPath = wasmPath;
     }
-    console.log('[FaceDetectionEngine] Human.js config:', {
-        backend: config.backend,
-        modelBasePath: config.modelBasePath || '(using default)',
-        wasmPath: config.wasmPath || '(using default)',
-        userAgent: navigator.userAgent,
-        platform: navigator.platform
+    return config;
+}
+/**
+ * Load and verify Human.js models
+ */
+async function _loadAndVerifyHuman(human) {
+    const modelLoadStartTime = performance.now();
+    try {
+        await human.load();
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        const errorStack = error instanceof Error ? error.stack : 'N/A';
+        console.error('[FaceDetectionEngine] Error during human.load():', {
+            errorMsg,
+            stack: errorStack,
+            backend: human.config?.backend,
+            hasModels: !!human.models,
+            modelsKeys: human.models ? Object.keys(human.models).length : 0
+        });
+        throw new Error(`Model loading error: ${errorMsg}`);
+    }
+    const loadTime = performance.now() - modelLoadStartTime;
+    console.log('[FaceDetectionEngine] Human.js loaded successfully', {
+        modelLoadTime: `${loadTime.toFixed(2)}ms`,
+        version: human.version,
+        config: human.config
     });
+    // 验证加载后的 Human 实例有必要的方法和属性
+    if (typeof human.detect !== 'function') {
+        throw new Error('Human.detect method not available after loading');
+    }
+    if (!human.version) {
+        console.warn('[FaceDetectionEngine] Human.js loaded but version is missing');
+    }
+    // 关键验证：检查模型是否真的加载了
+    if (!human.models || Object.keys(human.models).length === 0) {
+        console.error('[FaceDetectionEngine] CRITICAL: human.models is empty after loading!');
+        throw new Error('No models were loaded - human.models is empty');
+    }
+    // 详细检查每个关键模型及其结构
+    const criticalModels = ['face', 'antispoof', 'liveness'];
+    const missingModels = [];
+    for (const modelName of criticalModels) {
+        const model = human.models[modelName];
+        if (!model) {
+            missingModels.push(modelName);
+            console.error(`[FaceDetectionEngine] CRITICAL: Model '${modelName}' is missing!`);
+        }
+        else {
+            const isLoaded = model.loaded || model.state === 'loaded' || !!model.model;
+            // 检查模型是否有必要的内部结构（防止 "Cannot read properties of undefined (reading 'inputs')" 错误）
+            const hasExecutor = !!model['executor'];
+            const hasInputs = !!model.inputs && Array.isArray(model.inputs) && model.inputs.length > 0;
+            const hasModelUrl = !!model['modelUrl'];
+            console.log(`[FaceDetectionEngine] Model '${modelName}':`, {
+                loaded: isLoaded,
+                state: model.state,
+                hasModel: !!model.model,
+                hasExecutor,
+                hasInputs,
+                hasModelUrl,
+                inputsType: typeof model.inputs,
+                inputsLength: Array.isArray(model.inputs) ? model.inputs.length : 'N/A'
+            });
+            // 严格检查：模型必须有以下结构才能正常工作
+            if (!isLoaded || !hasExecutor || !hasModelUrl) {
+                missingModels.push(`${modelName} (incomplete)`);
+                console.error(`[FaceDetectionEngine] WARNING: Model '${modelName}' may not be fully loaded - missing structure`);
+            }
+            // 如果 inputs 未定义会导致 "Cannot read properties of undefined (reading 'inputs')" 错误
+            if (!hasInputs && modelName !== 'antispoof') {
+                console.warn(`[FaceDetectionEngine] WARNING: Model '${modelName}' has no inputs - may cause errors during detection`);
+                missingModels.push(`${modelName} (no inputs)`);
+            }
+        }
+    }
+    if (missingModels.length > 0) {
+        console.error('[FaceDetectionEngine] Some critical models failed to load:', missingModels);
+        throw new Error(`Critical models not loaded: ${missingModels.join(', ')}`);
+    }
+    // 打印加载的模型信息
+    if (human.models) {
+        const loadedModels = Object.entries(human.models).map(([name, model]) => ({
+            name,
+            loaded: model?.loaded || model?.state === 'loaded',
+            type: typeof model,
+            hasModel: !!model?.model
+        }));
+        console.log('[FaceDetectionEngine] All loaded models:', {
+            backend: human.config?.backend,
+            modelBasePath: human.config?.modelBasePath,
+            wasmPath: human.config?.wasmPath,
+            totalModels: Object.keys(human.models).length,
+            models: loadedModels,
+            allModelNames: Object.keys(human.models)
+        });
+    }
+}
+/**
+ * Try to load Human with a specific backend
+ * @param config The configuration object
+ * @param backend The backend to try
+ * @returns Human instance or null if fails
+ */
+async function _tryLoadHumanWithBackend(backend, modelPath, wasmPath) {
+    const config = _createHumanConfig(backend, modelPath, wasmPath);
     const initStartTime = performance.now();
-    console.log('[FaceDetectionEngine] Creating Human instance...');
     let human;
     try {
         human = new Human(config);
     }
     catch (error) {
         const errorMsg = error instanceof Error ? error.message : 'Unknown error during Human instantiation';
-        console.error('[FaceDetectionEngine] Failed to create Human instance:', errorMsg);
-        throw new Error(`Human instantiation failed: ${errorMsg}`);
+        const stack = error instanceof Error ? error.stack : 'N/A';
+        console.error(`[FaceDetectionEngine] Failed to create Human instance (${backend}):`, {
+            errorMsg,
+            stack,
+            backend: config.backend,
+            userAgent: navigator.userAgent
+        });
+        return null;
     }
-    const instanceCreateTime = performance.now() - initStartTime;
-    console.log(`[FaceDetectionEngine] Human instance created, took ${instanceCreateTime.toFixed(2)}ms`);
     // 验证 Human 实例
     if (!human) {
-        throw new Error('Human instance is null after creation');
+        console.error(`[FaceDetectionEngine] Human instance is null (${backend})`);
+        return null;
+    }
+    // 验证 Human 实例结构（早期检测 WASM 问题）
+    if (!human.config) {
+        console.warn('[FaceDetectionEngine] Warning: human.config is missing');
     }
-    console.log('[FaceDetectionEngine] Loading Human.js models...');
-    const modelLoadStartTime = performance.now();
     try {
-        // 添加超时机制防止无限等待
-        const loadTimeout = new Promise((_, reject) => {
-            const timeoutId = setTimeout(() => {
-                reject(new Error('Human.js load() timeout after 60 seconds - possible issue with model loading on mobile'));
-            }, 60000);
-        });
-        // 竞速：哪个先完成就用哪个
-        await Promise.race([
-            human.load(),
-            loadTimeout
-        ]);
-        const loadTime = performance.now() - modelLoadStartTime;
+        await _loadAndVerifyHuman(human);
         const totalTime = performance.now() - initStartTime;
-        console.log('[FaceDetectionEngine] Human.js loaded successfully', {
-            modelLoadTime: `${loadTime.toFixed(2)}ms`,
-            totalInitTime: `${totalTime.toFixed(2)}ms`,
-            version: human.version,
-            config: human.config
-        });
-        // 验证加载后的 Human 实例有必要的方法和属性
-        if (typeof human.detect !== 'function') {
-            throw new Error('Human.detect method not available after loading');
-        }
-        if (!human.version) {
-            console.warn('[FaceDetectionEngine] Human.js loaded but version is missing');
-        }
-        // 打印加载的模型信息
-        if (human.models) {
-            const loadedModels = Object.entries(human.models).map(([name, model]) => ({
-                name,
-                loaded: model?.loaded || model?.state === 'loaded',
-                type: typeof model
-            }));
-            console.log('[FaceDetectionEngine] Loaded models:', {
-                totalModels: Object.keys(human.models).length,
-                models: loadedModels,
-                allModels: Object.keys(human.models)
-            });
-        }
-        else {
-            console.warn('[FaceDetectionEngine] human.models is not available');
-        }
-        // 额外验证：检查模型是否加载成功
-        if (!human.models || Object.keys(human.models).length === 0) {
-            console.warn('[FaceDetectionEngine] Warning: human.models appears to be empty after loading');
-        }
+        console.log(`[FaceDetectionEngine] Successfully loaded Human.js with ${backend} backend in ${totalTime.toFixed(2)}ms`);
         return human;
     }
     catch (error) {
         const errorMsg = error instanceof Error ? error.message : 'Unknown error';
-        const stack = error instanceof Error ? error.stack : 'N/A';
-        console.error('[FaceDetectionEngine] Human.js load failed:', {
-            errorMsg,
-            stack,
-            userAgent: navigator.userAgent,
-            platform: navigator.platform,
-            humanVersion: human?.version,
-            humanConfig: human?.config
-        });
-        throw new Error(`Human.js loading failed: ${errorMsg}`);
+        console.error(`[FaceDetectionEngine] Failed to load models with ${backend} backend:`, errorMsg);
+        return null;
     }
 }
+/**
+ * Load Human.js
+ * @param modelPath - Path to model files (optional)
+ * @param wasmPath - Path to WASM files (optional)
+ * @param preferredBackend - Preferred TensorFlow backend: 'auto' | 'webgl' | 'wasm' (default: 'auto')
+ * @returns Promise that resolves with Human instance
+ */
+async function loadHuman(modelPath, wasmPath, preferredBackend) {
+    const selectedBackend = _detectOptimalBackend(preferredBackend);
+    console.log('[FaceDetectionEngine] Starting Human.js initialization:', {
+        selectedBackend,
+        modelBasePath: modelPath || '(using default)',
+        wasmPath: wasmPath || '(using default)',
+        userAgent: navigator.userAgent,
+        platform: navigator.platform
+    });
+    // 尝试用主后端加载
+    const human = await _tryLoadHumanWithBackend(selectedBackend, modelPath, wasmPath);
+    if (human) {
+        return human;
+    }
+    console.log(`[FaceDetectionEngine] Human.js loading failed with ${selectedBackend} backend.`);
+    // 尝试用备选后端加载（最多一次降级）
+    let fallbackBackend;
+    if (selectedBackend === 'wasm' && _isWebGLAvailable()) {
+        fallbackBackend = 'webgl';
+    }
+    else if (selectedBackend === 'webgl') {
+        fallbackBackend = 'wasm';
+    }
+    if (fallbackBackend) {
+        console.warn(`[FaceDetectionEngine] Primary backend (${selectedBackend}) failed, attempting fallback to ${fallbackBackend}...`);
+        const humanFallback = await _tryLoadHumanWithBackend(fallbackBackend, modelPath, wasmPath);
+        if (humanFallback) {
+            return humanFallback;
+        }
+        throw new Error(`Human.js loading failed: both ${selectedBackend} and ${fallbackBackend} backends failed`);
+    }
+    throw new Error(`Human.js loading failed: ${selectedBackend} backend failed (no fallback available)`);
+}
 /**
  * Extract OpenCV version from getBuildInformation
  * @returns version string like "4.12.0"
@@ -1719,28 +1814,59 @@ class FaceDetectionEngine extends SimpleEventEmitter {
             }
             catch (humanError) {
                 const errorMsg = humanError instanceof Error ? humanError.message : 'Unknown error';
-                console.error('[FaceDetectionEngine] Human.js loading failed with error:', errorMsg);
-                this.emitDebug('initialization', 'Human.js loading failed with exception', {
+                const stack = humanError instanceof Error ? humanError.stack : 'N/A';
+                // 分析错误类型，提供针对性的建议
+                let errorContext = {
                     error: errorMsg,
-                    stack: humanError instanceof Error ? humanError.stack : 'N/A',
+                    stack,
                     userAgent: navigator.userAgent,
                     platform: navigator.platform,
-                    browser: this.detectBrowserInfo()
-                }, 'error');
+                    browser: this.detectBrowserInfo(),
+                    backend: this.config.tensorflow_backend,
+                    source: 'human.js'
+                };
+                // 特定错误类型的诊断
+                if (errorMsg.includes('inputs')) {
+                    errorContext.diagnosis = 'Human.js internal error: Model structure incomplete';
+                    errorContext.rootCause = 'Human.js library issue - models not fully loaded or WASM backend initialization incomplete';
+                    errorContext.suggestion = 'This is a Human.js library issue. Models may not have proper executor or inputs structure. Check WASM initialization and model integrity.';
+                }
+                else if (errorMsg.includes('timeout')) {
+                    errorContext.diagnosis = 'Model loading timeout';
+                    errorContext.suggestion = 'Network issue or model file too large - check network conditions';
+                }
+                else if (errorMsg.includes('Critical models not loaded')) {
+                    errorContext.diagnosis = 'Human.js failed to load required models';
+                    errorContext.rootCause = 'Models (face, antispoof, liveness) are missing or incomplete';
+                    errorContext.suggestion = 'Check model files and ensure WASM backend is properly initialized';
+                }
+                else if (errorMsg.includes('empty')) {
+                    errorContext.diagnosis = 'Models object is empty after loading';
+                    errorContext.suggestion = 'Model path may be incorrect or HTTP response failed';
+                }
+                else if (errorMsg.includes('incomplete')) {
+                    errorContext.diagnosis = 'Models loaded but structure is incomplete';
+                    errorContext.rootCause = 'Human.js internal issue - missing executor, inputs, or modelUrl';
+                    errorContext.suggestion = 'Ensure all model resources are fully loaded and accessible';
+                }
+                console.error('[FaceDetectionEngine] Human.js loading failed with detailed error:', errorContext);
+                this.emitDebug('initialization', 'Human.js loading failed with exception', errorContext, 'error');
                 this.emit('detector-loaded', {
                     success: false,
-                    error: `Failed to load Human.js: ${errorMsg}`
+                    error: `Failed to load Human.js: ${errorMsg}`,
+                    details: errorContext
                 });
                 this.emit('detector-error', {
                     code: ErrorCode.DETECTOR_NOT_INITIALIZED,
-                    message: `Human.js loading error: ${errorMsg}`
+                    message: `Human.js loading error: ${errorMsg}`,
+                    details: errorContext
                 });
                 return;
             }
             const humanLoadTime = performance.now() - humanStartTime;
             if (!this.human) {
                 const errorMsg = 'Failed to load Human.js: instance is null';
-                console.log('[FaceDetectionEngine] ' + errorMsg);
+                console.error('[FaceDetectionEngine] ' + errorMsg);
                 this.emitDebug('initialization', errorMsg, { loadTime: humanLoadTime }, 'error');
                 this.emit('detector-loaded', {
                     success: false,