@sssxyd/face-liveness-detector 0.2.30 → 0.2.32

package/dist/index.js

@@ -88,6 +88,7 @@
         // resource paths
         human_model_path: undefined,
         tensorflow_wasm_path: undefined,
+        tensorflow_backend: 'auto', // 'auto' | 'webgl' | 'wasm'
         // DetectionSettings defaults
         video_width: 640,
         video_height: 640,
@@ -140,6 +141,9 @@
         if (userConfig.tensorflow_wasm_path !== undefined) {
             merged.tensorflow_wasm_path = userConfig.tensorflow_wasm_path;
         }
+        if (userConfig.tensorflow_backend !== undefined) {
+            merged.tensorflow_backend = userConfig.tensorflow_backend;
+        }
         if (userConfig.video_width !== undefined) {
             merged.video_width = userConfig.video_width;
         }
@@ -326,18 +330,72 @@
             return false;
         }
     }
-    function _detectOptimalBackend() {
+    function _detectBrowserEngine(userAgent) {
+        const ua = userAgent.toLowerCase();
+        // 1. 检测 Gecko (Firefox)
+        if (/firefox/i.test(ua) && !/seamonkey/i.test(ua)) {
+            return 'gecko';
+        }
+        // 2. 检测 WebKit
+        // 包括：Safari、iOS 浏览器、以及那些虽然包含 Chrome 标识但实际是 WebKit 的浏览器（Quark、支付宝、微信等）
+        if (/webkit/i.test(ua)) {
+            // WebKit 特征明显，包括以下几种情况：
+            // - 真正的 Safari（有 Safari 标识）
+            // - iOS 浏览器（有 Mobile Safari 标识）
+            // - Quark、支付宝、微信等虽然包含 Chrome 标识但是基于 WebKit 的浏览器
+            return 'webkit';
+        }
+        // 3. 检测 Chromium/Blink
+        // 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';
+        }
+        // 4. 其他浏览器 - 保守方案，使用 WASM
+        return 'other';
+    }
+    function _getOptimalBackendForEngine(engine) {
+        // 针对不同内核的优化策略
+        const backendConfig = {
+            chromium: 'webgl', // Chromium 内核：优先 WebGL
+            webkit: 'wasm', // WebKit（Safari、iOS）：使用 WASM
+            gecko: 'webgl', // Firefox：优先 WebGL
+            other: 'wasm' // 未知浏览器：保守使用 WASM
+        };
+        return backendConfig[engine];
+    }
+    function _detectOptimalBackend(preferredBackend) {
+        // If user explicitly specified a backend, honor it (unless it's 'auto')
+        if (preferredBackend && preferredBackend !== 'auto') {
+            console.log('[Backend Detection] Using user-specified backend:', {
+                backend: preferredBackend,
+                userAgent: navigator.userAgent
+            });
+            return preferredBackend;
+        }
         const userAgent = navigator.userAgent.toLowerCase();
-        // Special browsers: prefer WASM
-        if ((/safari/.test(userAgent) && !/chrome/.test(userAgent)) ||
-            /micromessenger/i.test(userAgent) ||
-            /alipay/.test(userAgent) ||
-            /qq/.test(userAgent) ||
-            /(wechat|alipay|qq)webview/i.test(userAgent)) {
-            return 'wasm';
-        }
-        // Desktop: prefer WebGL
-        return _isWebGLAvailable() ? 'webgl' : 'wasm';
+        const engine = _detectBrowserEngine(userAgent);
+        console.log('[Backend Detection] Detected browser engine:', {
+            engine,
+            userAgent: navigator.userAgent
+        });
+        // 获取该内核的推荐后端
+        let preferredBackendForEngine = _getOptimalBackendForEngine(engine);
+        // 对于 Chromium 和 Gecko，检查 WebGL 是否可用
+        if (preferredBackendForEngine === 'webgl') {
+            const hasWebGL = _isWebGLAvailable();
+            console.log('[Backend Detection] WebGL availability check:', {
+                engine,
+                hasWebGL,
+                selectedBackend: hasWebGL ? 'webgl' : 'wasm'
+            });
+            return hasWebGL ? 'webgl' : 'wasm';
+        }
+        // 对于 WebKit 和 other，直接使用 WASM
+        console.log('[Backend Detection] Using backend for engine:', {
+            engine,
+            backend: preferredBackendForEngine
+        });
+        return preferredBackendForEngine;
     }
     /**
      * 预加载 OpenCV.js 以确保全局 cv 对象可用
@@ -534,11 +592,13 @@
      * 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) {
+    async function loadHuman(modelPath, wasmPath, preferredBackend) {
+        const selectedBackend = _detectOptimalBackend(preferredBackend);
         const config = {
-            backend: _detectOptimalBackend(),
+            backend: selectedBackend,
             face: {
                 enabled: true,
                 detector: { rotation: false, return: true },
@@ -562,30 +622,176 @@
         console.log('[FaceDetectionEngine] Human.js config:', {
             backend: config.backend,
             modelBasePath: config.modelBasePath || '(using default)',
-            wasmPath: config.wasmPath || '(using default)'
+            wasmPath: config.wasmPath || '(using default)',
+            userAgent: navigator.userAgent,
+            platform: navigator.platform
         });
         const initStartTime = performance.now();
         console.log('[FaceDetectionEngine] Creating Human instance...');
-        const human = new Human(config);
+        let human;
+        try {
+            human = new Human(config);
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : 'Unknown error during Human instantiation';
+            const stack = error instanceof Error ? error.stack : 'N/A';
+            console.error('[FaceDetectionEngine] Failed to create Human instance:', {
+                errorMsg,
+                stack,
+                backend: config.backend,
+                userAgent: navigator.userAgent
+            });
+            throw new Error(`Human instantiation failed: ${errorMsg}`);
+        }
         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');
+        }
+        // 验证 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 {
-            await human.load();
+            // 添加超时机制防止无限等待
+            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);
+            });
+            // 竞速：哪个先完成就用哪个
+            try {
+                await Promise.race([
+                    human.load(),
+                    loadTimeout
+                ]);
+            }
+            catch (raceError) {
+                // 如果是超时错误，直接抛出
+                if (raceError instanceof Error && raceError.message.includes('timeout')) {
+                    throw raceError;
+                }
+                // 其他错误，提供更多上下文
+                const raceErrorMsg = raceError instanceof Error ? raceError.message : 'Unknown error';
+                const raceErrorStack = raceError instanceof Error ? raceError.stack : 'N/A';
+                console.error('[FaceDetectionEngine] Error during human.load():', {
+                    errorMsg: raceErrorMsg,
+                    stack: raceErrorStack,
+                    backend: config.backend,
+                    hasModels: !!human.models,
+                    modelsKeys: human.models ? Object.keys(human.models).length : 0
+                });
+                throw new Error(`Model loading error: ${raceErrorMsg}`);
+            }
             const loadTime = performance.now() - modelLoadStartTime;
             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
+                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:', {
+                    totalModels: Object.keys(human.models).length,
+                    models: loadedModels,
+                    allModelNames: Object.keys(human.models)
+                });
+            }
             return human;
         }
         catch (error) {
             const errorMsg = error instanceof Error ? error.message : 'Unknown error';
-            console.error('[FaceDetectionEngine] Human.js load failed:', errorMsg);
-            throw 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,
+                backend: config.backend
+            });
+            // 如果是 WASM 后端失败，尝试降级到 WebGL
+            if (selectedBackend === 'wasm' && !errorMsg.includes('timeout') && _isWebGLAvailable()) {
+                console.warn('[FaceDetectionEngine] WASM backend failed, attempting fallback to WebGL...');
+                config.backend = 'webgl';
+                try {
+                    console.log('[FaceDetectionEngine] Retrying with WebGL backend');
+                    human = new Human(config);
+                    await human.load();
+                    console.log('[FaceDetectionEngine] Successfully loaded with WebGL fallback');
+                    return human;
+                }
+                catch (fallbackError) {
+                    const fallbackMsg = fallbackError instanceof Error ? fallbackError.message : 'Unknown error';
+                    console.error('[FaceDetectionEngine] WebGL fallback also failed:', fallbackMsg);
+                }
+            }
+            throw new Error(`Human.js loading failed: ${errorMsg}`);
         }
     }
     /**
@@ -1621,11 +1827,64 @@
                 console.log('[FaceDetectionEngine] Loading Human.js models...');
                 this.emitDebug('initialization', 'Loading Human.js...');
                 const humanStartTime = performance.now();
-                this.human = await loadHuman(this.config.human_model_path, this.config.tensorflow_wasm_path);
+                try {
+                    this.human = await loadHuman(this.config.human_model_path, this.config.tensorflow_wasm_path, this.config.tensorflow_backend);
+                }
+                catch (humanError) {
+                    const errorMsg = humanError instanceof Error ? humanError.message : 'Unknown error';
+                    const stack = humanError instanceof Error ? humanError.stack : 'N/A';
+                    // 分析错误类型，提供针对性的建议
+                    let errorContext = {
+                        error: errorMsg,
+                        stack,
+                        userAgent: navigator.userAgent,
+                        platform: navigator.platform,
+                        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}`,
+                        details: errorContext
+                    });
+                    this.emit('detector-error', {
+                        code: exports.ErrorCode.DETECTOR_NOT_INITIALIZED,
+                        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,
@@ -1637,13 +1896,35 @@
                     });
                     return;
                 }
+                // Verify Human.js instance has required properties
+                if (!this.human.version || typeof this.human.detect !== 'function') {
+                    const errorMsg = 'Human.js instance is incomplete: missing version or detect method';
+                    console.error('[FaceDetectionEngine] ' + errorMsg);
+                    this.emitDebug('initialization', errorMsg, {
+                        hasVersion: !!this.human.version,
+                        hasDetect: typeof this.human.detect === 'function',
+                        instanceKeys: Object.keys(this.human || {})
+                    }, 'error');
+                    this.emit('detector-loaded', {
+                        success: false,
+                        error: errorMsg
+                    });
+                    this.emit('detector-error', {
+                        code: exports.ErrorCode.DETECTOR_NOT_INITIALIZED,
+                        message: errorMsg
+                    });
+                    return;
+                }
                 this.emitDebug('initialization', 'Human.js loaded successfully', {
                     loadTime: `${humanLoadTime.toFixed(2)}ms`,
-                    version: this.human.version
+                    version: this.human.version,
+                    backend: this.human.config?.backend || 'unknown',
+                    config: this.human.config
                 });
                 console.log('[FaceDetectionEngine] Human.js loaded successfully', {
                     loadTime: `${humanLoadTime.toFixed(2)}ms`,
-                    version: this.human.version
+                    version: this.human.version,
+                    backend: this.human.config?.backend || 'unknown'
                 });
                 this.isReady = true;
                 const loadedData = {
@@ -1920,13 +2201,31 @@
             try {
                 // Check video is ready
                 if (this.videoElement.readyState < HTMLMediaElement.HAVE_CURRENT_DATA) {
-                    this.scheduleNextDetection(this.config.error_retry_delay); // ERROR_RETRY_DELAY
+                    this.scheduleNextDetection(this.config.error_retry_delay);
                     return;
                 }
                 // Perform face detection
-                const result = await this.human.detect(this.videoElement);
+                let result;
+                try {
+                    result = await this.human.detect(this.videoElement);
+                }
+                catch (detectError) {
+                    const errorMsg = detectError instanceof Error ? detectError.message : 'Unknown error';
+                    this.emitDebug('detection', 'Human.detect() call failed', {
+                        error: errorMsg,
+                        stack: detectError instanceof Error ? detectError.stack : 'N/A',
+                        hasHuman: !!this.human,
+                        humanVersion: this.human?.version,
+                        videoReadyState: this.videoElement?.readyState,
+                        videoWidth: this.videoElement?.videoWidth,
+                        videoHeight: this.videoElement?.videoHeight
+                    }, 'error');
+                    this.scheduleNextDetection(this.config.error_retry_delay);
+                    return;
+                }
                 if (!result) {
-                    this.scheduleNextDetection(this.config.error_retry_delay); // DETECTION_FRAME_DELAY
+                    this.emitDebug('detection', 'Face detection returned null result', {}, 'warn');
+                    this.scheduleNextDetection(this.config.error_retry_delay);
                     return;
                 }
                 const faces = result.face || [];
@@ -1939,11 +2238,12 @@
                 }
             }
             catch (error) {
-                this.emitDebug('detection', 'Detection error', {
-                    error: error.message,
-                    stack: error.stack
+                const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+                this.emitDebug('detection', 'Unexpected error in detection loop', {
+                    error: errorMsg,
+                    stack: error instanceof Error ? error.stack : 'N/A'
                 }, 'error');
-                this.scheduleNextDetection(this.config.error_retry_delay); // ERROR_RETRY_DELAY
+                this.scheduleNextDetection(this.config.error_retry_delay);
             }
         }
         getPerformActionCount() {
@@ -2307,6 +2607,29 @@
             };
             this.emit('status-prompt', promptData);
         }
+        /**
+         * Detect browser information for debugging
+         */
+        detectBrowserInfo() {
+            const ua = navigator.userAgent.toLowerCase();
+            if (/quark/i.test(ua))
+                return 'Quark Browser';
+            if (/micromessenger/i.test(ua))
+                return 'WeChat';
+            if (/alipay/i.test(ua))
+                return 'Alipay';
+            if (/qq/i.test(ua))
+                return 'QQ';
+            if (/safari/i.test(ua) && !/chrome/i.test(ua))
+                return 'Safari';
+            if (/chrome/i.test(ua))
+                return 'Chrome';
+            if (/firefox/i.test(ua))
+                return 'Firefox';
+            if (/edge/i.test(ua))
+                return 'Edge';
+            return 'Unknown';
+        }
         /**
          * Emit debug event
          */