@sssxyd/face-liveness-detector 0.4.0-alpha.7 → 0.4.0-alpha.9

package/README.md

@@ -1,445 +1,609 @@
-> **Languages:** [English](#) · [中文](./README.zh-Hans.md)
+<div align="center">
 
-# Face Detection Engine
+> **语言 / Languages:** [中文](#) · [English](./README.en.md)
 
-A pure frontend, real-time face liveness detection engine built on **[Human.js](https://github.com/vladmandic/human)** and **[OpenCV.js](https://github.com/TechStark/opencv-js)**. This TypeScript-based npm package provides real-time face detection, dual liveness verification (silent + action-based), automatic best frame selection, and anti-spoofing capabilities - all running 100% in the browser with zero backend dependency.
+# 人脸活体检测引擎
 
-## Features
+<p>
+  <strong>基于 TensorFlow + OpenCV 的纯前端实时人脸活体检测解决方案</strong>
+</p>
 
-- 💯 **Pure Frontend Implementation** - Zero backend dependency, all processing runs locally in the browser
-- 🔬 **Hybrid TensorFlow + OpenCV Solution** - Combines TensorFlow.js for AI detection with OpenCV.js for image processing
-- 🧠 **Dual Detection Modes** - Both silent liveness detection and action-based detection (blink, mouth open, nod) with automatic best frame selection
-- ⚡ **Pure JavaScript & Event-Driven** - 100% TypeScript, reactive event architecture, seamless integration with any frontend framework (Vue, React, Angular, Svelte, or vanilla JS)
-- 🎯 **Comprehensive Face Analysis** - Real-time anti-spoofing, quality assessment, frontality detection, and blur detection
+<p>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.0+-3178c6?logo=typescript">
+  <img alt="NPM Package" src="https://img.shields.io/npm/v/@sssxyd/face-liveness-detector?label=npm&color=cb3837">
+  <img alt="License" src="https://img.shields.io/badge/license-MIT-green">
+</p>
 
-## 🚀 Try Online Demo
+</div>
 
-**[👉 Live Demo: https://face.lowtechsoft.com/](https://face.lowtechsoft.com/)**
+---
 
-Scan the QR code with your phone to test the detection engine right now:
+## ✨ 功能特性
 
-[![Face Liveness Detection Demo QR Code](https://raw.githubusercontent.com/sssxyd/face-liveness-detector/main/demos/vue-demo/vue-demo.png)](https://face.lowtechsoft.com/)
-## Installation
+<table>
+  <tr>
+    <td>💯 <strong>纯前端实现</strong><br/>零后端依赖，所有处理在浏览器中本地运行</td>
+    <td>🔬 <strong>混合 AI 方案</strong><br/>TensorFlow + OpenCV 深度融合</td>
+  </tr>
+  <tr>
+    <td>🧠 <strong>双重活体验证</strong><br/>静默检测 + 动作识别（眨眼、张嘴、点头）</td>
+    <td>⚡ <strong>事件驱动架构</strong><br/>100% TypeScript，与任何框架无缝集成</td>
+  </tr>
+  <tr>
+    <td>🎯 <strong>全维度分析</strong><br/>质量、正对度、运动分数、屏幕检测</td>
+    <td>🛡️ <strong>多维反欺骗</strong><br/>照片、屏幕视频、莫尔纹、RGB发光检测</td>
+  </tr>
+</table>
+
+---
+
+## 🚀 在线演示
+
+<div align="center">
+
+**[👉 实时体验演示](https://face.lowtechsoft.com/) | 用手机扫码快速测试**
+
+[![人脸活体检测演示二维码](https://raw.githubusercontent.com/sssxyd/face-liveness-detector/main/demos/vue-demo/vue-demo.png)](https://face.lowtechsoft.com/)
+
+</div>
+
+---
+
+## 🧬 核心算法设计
+
+| 检测模块 | 技术方案 | 说明文档 |
+|---------|--------|--------|
+| **人脸识别** | Human.js BlazeFace + FaceMesh | 468个面部特征点 + 表情识别 |
+| **动作检测** | 多维度运动分析 | [运动检测算法](./docs/MOTION_DETECTION_ALGORITHM.md) - 光流、关键点方差、面部区域变化 |
+| **屏幕检测** | 三维特征融合 | [屏幕捕捉检测](./docs/SCREEN_CAPTURE_DETECTION_ALGORITHM.md) - 莫尔纹、RGB发光、色彩特征 |
+
+---
+
+## 📦 安装指南
+
+### 快速安装（3 个包）
 
 ```bash
 npm install @sssxyd/face-liveness-detector @vladmandic/human @techstark/opencv-js
 ```
 
-Or with yarn:
+<details>
+<summary><strong>其他包管理器</strong></summary>
+
 ```bash
+# Yarn
 yarn add @sssxyd/face-liveness-detector @vladmandic/human @techstark/opencv-js
-```
 
-Or with pnpm:
-```bash
+# pnpm
 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.
+</details>
+
+> 📝 **为什么需要三个包？**
+> `@vladmandic/human` 和 `@techstark/opencv-js` 是对等依赖（peer dependencies），需要单独安装以避免捆绑大型库，减小最终的打包体积。
+
+---
+
+## ⚠️ 必要配置步骤
 
-## Quick Start - Using Local Resources
+### 1️⃣ 修复 OpenCV.js ESM 兼容性问题
 
-> ⚠️ **CRITICAL**: `@techstark/opencv-js` contains an ESM incompatible UMD-format OpenCV.js library that **will cause load failures**. You MUST apply the patch script.
-> - **Issue**: https://github.com/TechStark/opencv-js/issues/44
-> - **Patch Script**: [patch-opencv.js](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/scripts/patch-opencv.js)
-> - **Setup**: Add to your `package.json` scripts as a `postinstall` hook to auto-apply after dependencies install
+`@techstark/opencv-js` 包含不兼容的 UMD 格式，**必须应用补丁脚本**。
 
-> ⚠️ **CRITICAL**: `@vladmandic/human` requires downloading large model files and TensorFlow WASM backend files. The component **will fail to load without these resources**. Download them to your project directory and configure the paths.
-> - **Models Download Script**: [copy-models.js](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/scripts/copy-models.js)
-> - **WASM Download Script**: [download-wasm.js](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/scripts/download-wasm.js)
-> - **Setup**: Run both scripts as `postinstall` hooks, then configure paths in your engine config
+**参考：**
+- 问题详情：[TechStark/opencv-js#44](https://github.com/TechStark/opencv-js/issues/44)
+- 补丁脚本：[patch-opencv.js](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/scripts/patch-opencv.js)
+
+**设置方法（推荐）：** 添加到 `package.json` 的 `postinstall` 钩子
+
+```json
+{
+  "scripts": {
+    "postinstall": "node patch-opencv.cjs"
+  }
+}
+```
 
+### 2️⃣ 下载 Human.js 模型文件
+
+`@vladmandic/human` 需要模型文件和 TensorFlow WASM 后端，**否则无法加载**。
+
+**下载脚本：**
+- 模型复制：[copy-models.js](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/scripts/copy-models.js)
+- WASM 下载：[download-wasm.js](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/scripts/download-wasm.js)
+
+**设置方法（推荐）：** 配置为 `postinstall` 钩子
+
+```json
+{
+  "scripts": {
+    "postinstall": "node scripts/copy-models.js && node scripts/download-wasm.js"
+  }
+}
+```
+
+---
+
+## 🎯 快速开始
+
+### 基础示例
 
 ```typescript
 import FaceDetectionEngine, { LivenessAction } from '@sssxyd/face-liveness-detector'
 
-// Initialize the engine with custom configuration
+// 初始化引擎
 const engine = new FaceDetectionEngine({
-  // Configure resource paths
+  // 资源路径配置
   human_model_path: '/models',
   tensorflow_wasm_path: '/wasm',
+  tensorflow_backend: 'auto',
   
-  // Detection settings
-  video_width: 640,
-  video_height: 640,
-  
-  // Quality settings
-  min_image_quality: 0.5,
-  min_face_frontal: 0.9,
-  
-  // Liveness settings - choose your preferred actions
-  liveness_action_count: 1,  // 0 for silent detection only, 1-3 for action-based
-  liveness_action_list: [LivenessAction.BLINK, LivenessAction.MOUTH_OPEN, LivenessAction.NOD]
+  // 检测设置（建议 ≥720p，否则屏幕检测准确率下降）
+  detect_video_ideal_width: 1920,
+  detect_video_ideal_height: 1080,
+  detect_video_mirror: true,
+  detect_video_load_timeout: 5000,
+  detect_frame_delay: 100,
+
+  // 采集质量要求
+  collect_min_collect_count: 3,        // 最少采集 3 张人脸
+  collect_min_face_ratio: 0.5,         // 人脸占比 50%+
+  collect_max_face_ratio: 0.9,         // 人脸占比 90% 以下
+  collect_min_face_frontal: 0.9,       // 人脸正对度 90%
+  collect_min_image_quality: 0.5,      // 图像质量 50%+
+
+  // 活体检测设置
+  action_liveness_action_count: 1,     // 需要 1 个动作
+  action_liveness_action_list: [LivenessAction.BLINK, LivenessAction.MOUTH_OPEN, LivenessAction.NOD],
+  action_liveness_action_randomize: true,
+  action_liveness_verify_timeout: 60000,
+
+  // 防欺骗设置
+  motion_liveness_min_motion_score: 0.15,
+  motion_liveness_strict_photo_detection: false,
+  screen_capture_confidence_threshold: 0.7,
 })
 
-// Listen for events
+// 监听核心事件
 engine.on('detector-loaded', (data) => {
-  console.log('✅ Engine is ready')
-  console.log(`OpenCV: ${data.opencv_version}`)
-  console.log(`Human.js: ${data.human_version}`)
+  if (data.success) {
+    console.log('✅ 引擎就绪', {
+      opencv: data.opencv_version,
+      human: data.human_version
+    })
+  }
 })
 
 engine.on('detector-info', (data) => {
-  // Real-time detection information
+  // 每帧实时数据
   console.log({
-    quality: (data.quality * 100).toFixed(1) + '%',
-    frontal: (data.frontal * 100).toFixed(1) + '%',
-    liveness: (data.live * 100).toFixed(1) + '%',
-    realness: (data.real * 100).toFixed(1) + '%'
+    status: data.code,
+    quality: (data.imageQuality * 100).toFixed(1) + '%',
+    frontal: (data.faceFrontal * 100).toFixed(1) + '%',
+    motion: (data.motionScore * 100).toFixed(1) + '%',
+    screen: (data.screenConfidence * 100).toFixed(1) + '%'
   })
 })
 
 engine.on('detector-action', (data) => {
-  // Action liveness prompts
-  if (data.status === 'started') {
-    console.log(`Please perform: ${data.action}`)
-  } else if (data.status === 'completed') {
-    console.log(`✅ Action recognized: ${data.action}`)
-  }
+  // 动作提示
+  console.log(`请执行动作: ${data.action} (${data.status})`)
 })
 
 engine.on('detector-finish', (data) => {
+  // 检测完成
   if (data.success) {
-    console.log('✅ Liveness verification passed!')
-    console.log({
-      silentDetections: data.silentPassedCount,
-      actionsCompleted: data.actionPassedCount,
-      imageQuality: (data.bestQualityScore * 100).toFixed(1) + '%',
-      totalTime: (data.totalTime / 1000).toFixed(2) + 's',
-      bestFrame: data.bestFrameImage,  // Base64 encoded
-      bestFace: data.bestFaceImage     // Base64 encoded
+    console.log('✅ 活体验证通过！', {
+      静默通过: data.silentPassedCount,
+      动作完成: data.actionPassedCount,
+      最佳质量: (data.bestQualityScore * 100).toFixed(1) + '%',
+      总耗时: (data.totalTime / 1000).toFixed(2) + 's'
     })
   } else {
-    console.log('❌ Liveness verification failed')
+    console.log('❌ 活体验证失败')
   }
 })
 
 engine.on('detector-error', (error) => {
-  console.error(`Error [${error.code}]: ${error.message}`)
+  console.error(`❌ 错误 [${error.code}]: ${error.message}`)
 })
 
-engine.on('detector-debug', (debug) => {
-  console.log(`[${debug.stage}] ${debug.message}`)
-})
-
-// Initialize and start detection
-async function runDetection() {
+// 启动检测
+async function startLivenessDetection() {
   try {
-    // Initialize libraries (models, TensorFlow WASM, etc.)
+    // 初始化库
     await engine.initialize()
     
-    // Get video element
-    const videoElement = document.getElementById('video') as HTMLVideoElement
+    // 获取视频元素并开始检测
+    const videoEl = document.getElementById('video') as HTMLVideoElement
+    await engine.startDetection(videoEl)
     
-    // Start detection on the video stream
-    await engine.startDetection(videoElement)
-    
-    // Detection runs until completion or error
-    // Stop manually if needed:
-    // engine.stopDetection(true)  // true to display best image
+    // 检测自动运行到完成或手动停止
+    // engine.stopDetection(true)  // 停止并显示最佳图像
   } catch (error) {
-    console.error('Failed to run detection:', error)
+    console.error('检测启动失败:', error)
   }
 }
 
-// Call when ready
-runDetection()
-```
+// 就绪时启动
+startLivenessDetection()
+```
+
+---
+
+## ⚙️ 详细配置参考
+
+### 资源路径配置
+
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `human_model_path` | `string` | Human.js 模型文件目录 | `undefined` |
+| `tensorflow_wasm_path` | `string` | TensorFlow WASM 文件目录 | `undefined` |
+| `tensorflow_backend` | `'auto' \| 'webgl' \| 'wasm'` | TensorFlow 后端引擎 | `'auto'` |
 
-## Configuration
+### 视频检测设置
 
-### FaceDetectionEngineConfig
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `detect_video_ideal_width` | `number` | 视频宽度（像素） | `1920` |
+| `detect_video_ideal_height` | `number` | 视频高度（像素） | `1080` |
+| `detect_video_mirror` | `boolean` | 水平翻转视频 | `true` |
+| `detect_video_load_timeout` | `number` | 加载超时（ms） | `5000` |
+| `detect_frame_delay` | `number` | 帧间延迟（ms） | `100` |
+| `detect_error_retry_delay` | `number` | 错误重试延迟（ms） | `200` |
 
-#### Resource Paths
+### 人脸采集质量要求
 
-| Property | Type | Description | Default |
-|----------|------|-------------|---------|
-| `human_model_path` | `string` | Path to Human.js model files | `undefined` |
-| `tensorflow_wasm_path` | `string` | Path to TensorFlow WASM files | `undefined` |
-| `tensorflow_backend` | `'auto' \| 'webgl' \| 'wasm'` | TensorFlow backend selection | `'auto'` |
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `collect_min_collect_count` | `number` | 最少采集数量 | `3` |
+| `collect_min_face_ratio` | `number` | 最小人脸占比 (0-1) | `0.5` |
+| `collect_max_face_ratio` | `number` | 最大人脸占比 (0-1) | `0.9` |
+| `collect_min_face_frontal` | `number` | 最小正对度 (0-1) | `0.9` |
+| `collect_min_image_quality` | `number` | 最小图像质量 (0-1) | `0.5` |
 
-#### Video Detection Settings
+### 人脸正对度参数
 
-| Property | Type | Description | Default |
-|----------|------|-------------|---------|
-| `video_width` | `number` | Video stream width in pixels | `640` |
-| `video_height` | `number` | Video stream height in pixels | `640` |
-| `video_mirror` | `boolean` | Mirror video horizontally | `true` |
-| `video_load_timeout` | `number` | Video stream loading timeout in ms | `5000` |
-| `detection_frame_delay` | `number` | Delay between detection frames in ms | `100` |
-| `error_retry_delay` | `number` | Error retry delay in ms | `200` |
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `yaw_threshold` | `number` | 偏航角阈值（度） | `3` |
+| `pitch_threshold` | `number` | 俯仰角阈值（度） | `4` |
+| `roll_threshold` | `number` | 翻滚角阈值（度） | `2` |
 
-#### Detection Quality Settings
+### 图像质量参数
 
-| Property | Type | Description | Default |
-|----------|------|-------------|---------|
-| `silent_detect_count` | `number` | Number of silent detections to collect | `3` |
-| `min_face_ratio` | `number` | Minimum face size ratio (0-1) | `0.5` |
-| `max_face_ratio` | `number` | Maximum face size ratio (0-1) | `0.9` |
-| `min_face_frontal` | `number` | Minimum face frontality score (0-1) | `0.9` |
-| `min_image_quality` | `number` | Minimum image quality score (0-1) | `0.5` |
-| `min_live_score` | `number` | Minimum liveness score (0-1) | `0.5` |
-| `min_real_score` | `number` | Minimum anti-spoofing score (0-1) | `0.85` |
-| `suspected_frauds_count` | `number` | Number of frauds to detect before fail | `3` |
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `require_full_face_in_bounds` | `boolean` | 人脸完全在边界内 | `false` |
+| `min_laplacian_variance` | `number` | 最小模糊检测值 | `40` |
+| `min_gradient_sharpness` | `number` | 最小清晰度 | `0.15` |
+| `min_blur_score` | `number` | 最小模糊分数 | `0.6` |
 
-#### Face Frontality Features (`face_frontal_features`)
+### 活体检测设置
 
-| Property | Type | Description | Default |
-|----------|------|-------------|---------|
-| `yaw_threshold` | `number` | Yaw angle threshold in degrees | `3` |
-| `pitch_threshold` | `number` | Pitch angle threshold in degrees | `4` |
-| `roll_threshold` | `number` | Roll angle threshold in degrees | `2` |
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `action_liveness_action_list` | `LivenessAction[]` | 动作列表 | `[BLINK, MOUTH_OPEN, NOD]` |
+| `action_liveness_action_count` | `number` | 需要完成的动作数 | `1` |
+| `action_liveness_action_randomize` | `boolean` | 随机化动作顺序 | `true` |
+| `action_liveness_verify_timeout` | `number` | 超时时间（ms） | `60000` |
+| `action_liveness_min_mouth_open_percent` | `number` | 最小张嘴比例 (0-1) | `0.2` |
 
-#### Image Quality Features (`image_quality_features`)
+### 动作活体检测（防照片攻击）
 
-| Property | Type | Description | Default |
-|----------|------|-------------|---------|
-| `require_full_face_in_bounds` | `boolean` | Require face completely within bounds | `false` |
-| `use_opencv_enhancement` | `boolean` | Use OpenCV enhancement for quality detection | `true` |
-| `min_laplacian_variance` | `number` | Minimum Laplacian variance for blur detection | `50` |
-| `min_gradient_sharpness` | `number` | Minimum gradient sharpness for blur detection | `0.15` |
-| `min_blur_score` | `number` | Minimum blur score | `0.6` |
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `motion_liveness_min_motion_score` | `number` | 最小运动分数 (0-1) | `0.15` |
+| `motion_liveness_min_keypoint_variance` | `number` | 最小关键点方差 (0-1) | `0.02` |
+| `motion_liveness_frame_buffer_size` | `number` | 帧缓冲区大小 | `5` |
+| `motion_liveness_eye_aspect_ratio_threshold` | `number` | 眨眼阈值 | `0.15` |
+| `motion_liveness_motion_consistency_threshold` | `number` | 一致性阈值 (0-1) | `0.3` |
+| `motion_liveness_min_optical_flow_threshold` | `number` | 最小光流幅度 (0-1) | `0.02` |
+| `motion_liveness_strict_photo_detection` | `boolean` | 严格照片检测模式 | `false` |
 
-#### Liveness Detection Settings
+### 屏幕采集检测
 
-| Property | Type | Description | Default |
-|----------|------|-------------|---------|
-| `liveness_action_list` | `LivenessAction[]` | List of liveness actions to detect | `[BLINK, MOUTH_OPEN, NOD]` |
-| `liveness_action_count` | `number` | Number of liveness actions to perform | `1` |
-| `liveness_action_randomize` | `boolean` | Randomize liveness actions order | `true` |
-| `liveness_verify_timeout` | `number` | Timeout for liveness verification in ms | `60000` |
-| `min_mouth_open_percent` | `number` | Minimum mouth open percentage (0-1) | `0.2` |
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `screen_capture_confidence_threshold` | `number` | 置信度阈值 (0-1) | `0.7` |
+| `screen_capture_detection_strategy` | `string` | 检测策略 | `'adaptive'` |
+| `screen_moire_pattern_threshold` | `number` | 莫尔纹阈值 (0-1) | `0.65` |
+| `screen_moire_pattern_enable_dct` | `boolean` | 启用 DCT 分析 | `true` |
+| `screen_moire_pattern_enable_edge_detection` | `boolean` | 启用边缘检测 | `true` |
 
+### 屏幕色彩特征
 
-## API Reference
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `screen_color_saturation_threshold` | `number` | 饱和度阈值 (%) | `40` |
+| `screen_color_rgb_correlation_threshold` | `number` | RGB相关性阈值 (0-1) | `0.75` |
+| `screen_color_pixel_entropy_threshold` | `number` | 熵值阈值 (0-8) | `6.5` |
+| `screen_color_gradient_smoothness_threshold` | `number` | 平滑性阈值 (0-1) | `0.7` |
+| `screen_color_confidence_threshold` | `number` | 置信度阈值 (0-1) | `0.65` |
 
-### Methods
+### 屏幕 RGB 发光检测
+
+| 选项 | 类型 | 说明 | 默认值 |
+|-----|------|------|--------|
+| `screen_rgb_low_freq_start_percent` | `number` | 低频段开始 (0-1) | `0.15` |
+| `screen_rgb_low_freq_end_percent` | `number` | 低频段结束 (0-1) | `0.35` |
+| `screen_rgb_energy_score_weight` | `number` | 能量权重 | `0.40` |
+| `screen_rgb_asymmetry_score_weight` | `number` | 不同步权重 | `0.40` |
+| `screen_rgb_difference_factor_weight` | `number` | 差异权重 | `0.20` |
+| `screen_rgb_confidence_threshold` | `number` | 置信度阈值 (0-1) | `0.65` |
+
+---
+
+## 🛠️ API 方法参考
+
+### 核心方法
 
 #### `initialize(): Promise<void>`
-Load and initialize detection libraries. Must be called before using detection.
+加载并初始化检测库。**必须在使用其他功能前调用。**
 
 ```typescript
 await engine.initialize()
 ```
 
 #### `startDetection(videoElement): Promise<void>`
-Start face detection on a video element.
+在视频元素上开始人脸检测。
 
 ```typescript
-const videoElement = document.getElementById('video') as HTMLVideoElement
-await engine.startDetection(videoElement)
+const videoEl = document.getElementById('video') as HTMLVideoElement
+await engine.startDetection(videoEl)
 ```
 
 #### `stopDetection(success?: boolean): void`
-Stop the detection process.
+停止检测过程。
 
 ```typescript
-engine.stopDetection(true)  // true to display best image
+engine.stopDetection(true)  // true: 显示最佳检测图像
 ```
 
 #### `updateConfig(config): void`
-Update configuration during runtime.
+运行时动态更新配置。
 
 ```typescript
 engine.updateConfig({
-  min_face_ratio: 0.6,
-  liveness_action_count: 2
+  collect_min_face_ratio: 0.6,
+  action_liveness_action_count: 0
 })
 ```
 
-#### `getConfig(): FaceDetectionEngineConfig`
-Get current configuration.
+#### `getOptions(): FaceDetectionEngineOptions`
+获取当前配置对象。
 
 ```typescript
-const config = engine.getConfig()
+const config = engine.getOptions()
 ```
 
-#### `getStatus(): Object`
-Get engine status.
+#### `getEngineState(): EngineState`
+获取引擎当前状态。
 
 ```typescript
-const { isReady, isDetecting, isInitializing } = engine.getStatus()
-```
-
-### Events
+const state = engine.getEngineState()
+```
+
+---
+
+## 📡 事件系统
+
+引擎采用 **TypeScript 事件发射器模式**，所有事件都是类型安全的。
+
+### 事件列表
+
+<table>
+<tr>
+<td><strong>detector-loaded</strong></td>
+<td>引擎初始化完成</td>
+</tr>
+<tr>
+<td><strong>detector-info</strong></td>
+<td>每帧实时检测数据</td>
+</tr>
+<tr>
+<td><strong>detector-action</strong></td>
+<td>动作活体提示与状态</td>
+</tr>
+<tr>
+<td><strong>detector-finish</strong></td>
+<td>检测完成（成功/失败）</td>
+</tr>
+<tr>
+<td><strong>detector-error</strong></td>
+<td>错误发生时触发</td>
+</tr>
+<tr>
+<td><strong>detector-debug</strong></td>
+<td>调试信息（开发用）</td>
+</tr>
+</table>
+
+---
+
+### 📋 detector-loaded
+
+**引擎初始化完成时触发**
 
-The engine uses a TypeScript event emitter pattern. All events are type-safe:
-
-#### `detector-loaded`
-Fired when the engine finishes initialization.
-
-**Data:**
 ```typescript
 interface DetectorLoadedEventData {
-  success: boolean        // Whether initialization succeeded
-  error?: string          // Error message if any
-  opencv_version?: string // OpenCV.js version
-  human_version?: string  // Human.js version
+  success: boolean        // 初始化是否成功
+  error?: string          // 错误信息（失败时）
+  opencv_version?: string // OpenCV.js 版本号
+  human_version?: string  // Human.js 版本号
 }
 ```
 
-**Example:**
+**示例：**
 ```typescript
 engine.on('detector-loaded', (data) => {
   if (data.success) {
-    console.log('✅ Engine ready')
-    console.log(`OpenCV: ${data.opencv_version}`)
-    console.log(`Human.js: ${data.human_version}`)
+    console.log('✅ 引擎就绪')
+    console.log(`OpenCV ${data.opencv_version} | Human.js ${data.human_version}`)
   } else {
-    console.error('Engine failed:', data.error)
+    console.error('❌ 初始化失败:', data.error)
   }
 })
 ```
 
-#### `detector-info`
-Real-time detection information for each frame.
+---
+
+### 📊 detector-info
+
+**每帧返回实时检测数据（高频事件）**
 
-**Data:**
 ```typescript
 interface DetectorInfoEventData {
-  passed: boolean     // Whether silent liveness check passed
-  code: DetectionCode // Detection status code
-  size: number        // Face size ratio (0-1)
-  frontal: number     // Face frontality score (0-1)
-  quality: number     // Image quality score (0-1)
-  real: number        // Anti-spoofing score (0-1)
-  live: number        // Liveness score (0-1)
+  passed: boolean         // 是否通过静默检测
+  code: DetectionCode     // 检测状态码
+  message: string         // 状态消息
+  faceCount: number       // 检测到的人脸数
+  faceRatio: number       // 人脸占比 (0-1)
+  faceFrontal: number     // 人脸正对度 (0-1)
+  imageQuality: number    // 图像质量分数 (0-1)
+  motionScore: number     // 运动分数 (0-1)
+  keypointVariance: number // 关键点方差 (0-1)
+  motionType: string      // 检测到的运动类型
+  screenConfidence: number // 屏幕采集置信度 (0-1)
 }
 ```
 
-**Detection Codes:**
+**检测状态码：**
 ```typescript
 enum DetectionCode {
-  VIDEO_NO_FACE = 'VIDEO_NO_FACE',        // No face detected
-  MULTIPLE_FACE = 'MULTIPLE_FACE',        // Multiple faces detected
-  FACE_TOO_SMALL = 'FACE_TOO_SMALL',      // Face too small
-  FACE_TOO_LARGE = 'FACE_TOO_LARGE',      // Face too large
-  FACE_NOT_FRONTAL = 'FACE_NOT_FRONTAL',  // Face not frontal enough
-  FACE_NOT_REAL = 'FACE_NOT_REAL',        // Suspected spoofing
-  FACE_NOT_LIVE = 'FACE_NOT_LIVE',        // Low liveness score
-  FACE_LOW_QUALITY = 'FACE_LOW_QUALITY',  // Image quality too low
-  FACE_CHECK_PASS = 'FACE_CHECK_PASS'     // All checks passed
+  VIDEO_NO_FACE = 'VIDEO_NO_FACE',           // 未检测到人脸
+  MULTIPLE_FACE = 'MULTIPLE_FACE',           // 检测到多张人脸
+  FACE_TOO_SMALL = 'FACE_TOO_SMALL',         // 人脸太小
+  FACE_TOO_LARGE = 'FACE_TOO_LARGE',         // 人脸太大
+  FACE_NOT_FRONTAL = 'FACE_NOT_FRONTAL',     // 人脸不够正面
+  FACE_NOT_REAL = 'FACE_NOT_REAL',           // 疑似欺骗
+  FACE_NOT_LIVE = 'FACE_NOT_LIVE',           // 活体分数过低
+  FACE_LOW_QUALITY = 'FACE_LOW_QUALITY',     // 图像质量过低
+  FACE_CHECK_PASS = 'FACE_CHECK_PASS'        // 所有检查通过 ✅
 }
 ```
 
-**Example:**
+**示例：**
 ```typescript
 engine.on('detector-info', (data) => {
   console.log({
-    passed: data.passed,
-    status: data.code,
-    quality: (data.quality * 100).toFixed(1) + '%',
-    frontal: (data.frontal * 100).toFixed(1) + '%',
-    liveness: (data.live * 100).toFixed(1) + '%',
-    realness: (data.real * 100).toFixed(1) + '%'
+    检测状态: data.code,
+    静默通过: data.passed ? '✅' : '❌',
+    图像质量: `${(data.imageQuality * 100).toFixed(1)}%`,
+    人脸正对度: `${(data.faceFrontal * 100).toFixed(1)}%`,
+    运动分数: `${(data.motionScore * 100).toFixed(1)}%`,
+    屏幕采集: `${(data.screenConfidence * 100).toFixed(1)}%`
   })
 })
 ```
 
-#### `detector-action`
-Action liveness prompts and status updates.
+---
+
+### 👤 detector-action
+
+**动作活体提示与识别状态**
 
-**Data:**
 ```typescript
 interface DetectorActionEventData {
-  action: LivenessAction    // The action to perform
-  status: LivenessActionStatus // Action status
+  action: LivenessAction          // 要执行的动作
+  status: LivenessActionStatus    // 动作状态
 }
-```
 
-**Action Types:**
-```typescript
 enum LivenessAction {
-  BLINK = 'blink',
-  MOUTH_OPEN = 'mouth_open',
-  NOD = 'nod'
+  BLINK = 'blink',           // 眨眼
+  MOUTH_OPEN = 'mouth_open', // 张嘴
+  NOD = 'nod'                // 点头
 }
-```
 
-**Action Status:**
-```typescript
 enum LivenessActionStatus {
-  STARTED = 'started',      // Action prompt started
-  COMPLETED = 'completed',  // Action recognized
-  TIMEOUT = 'timeout'       // Action recognition timeout
+  STARTED = 'started',      // 提示已开始
+  COMPLETED = 'completed',  // 成功识别
+  TIMEOUT = 'timeout'       // 识别超时
 }
 ```
 
-**Example:**
+**示例：**
 ```typescript
 engine.on('detector-action', (data) => {
+  const actionLabels = {
+    'blink': '眨眼',
+    'mouth_open': '张嘴',
+    'nod': '点头'
+  }
+  
   switch (data.status) {
     case 'started':
-      console.log(`👤 Please perform: ${data.action}`)
-      // Update UI to show action prompt
+      console.log(`👤 请执行: ${actionLabels[data.action]}`)
+      // 显示 UI 提示
       break
     case 'completed':
-      console.log(`✅ Action recognized: ${data.action}`)
-      // Update progress indicator
+      console.log(`✅ 已识别: ${actionLabels[data.action]}`)
+      // 更新进度条
       break
     case 'timeout':
-      console.log(`⏱️ Action timeout: ${data.action}`)
+      console.log(`⏱️ 超时: ${actionLabels[data.action]}`)
+      // 显示重试提示
       break
   }
 })
 ```
 
-#### `detector-finish`
-Fired when liveness detection completes (successfully or failed).
+---
+
+### ✅ detector-finish
+
+**检测流程完成（成功或失败）**
 
-**Data:**
 ```typescript
 interface DetectorFinishEventData {
-  success: boolean         // Whether liveness verification passed
-  silentPassedCount: number    // Number of silent detections passed
-  actionPassedCount: number    // Number of actions completed
-  totalTime: number        // Total detection time in ms
-  bestQualityScore: number // Best image quality score (0-1)
-  bestFrameImage: string | null  // Base64 encoded best frame image
-  bestFaceImage: string | null   // Base64 encoded best face image
+  success: boolean         // 是否通过验证
+  silentPassedCount: number    // 静默检测通过数
+  actionPassedCount: number    // 动作完成数
+  totalTime: number        // 总耗时（毫秒）
+  bestQualityScore: number // 最佳图像质量 (0-1)
+  bestFrameImage: string | null  // Base64 帧图像
+  bestFaceImage: string | null   // Base64 人脸图像
 }
 ```
 
-**Example:**
+**示例：**
 ```typescript
 engine.on('detector-finish', (data) => {
   if (data.success) {
-    console.log('✅ Liveness verification passed!')
-    console.log({
-      silentDetections: data.silentPassedCount,
-      actionsCompleted: data.actionPassedCount,
-      quality: (data.bestQualityScore * 100).toFixed(1) + '%',
-      time: (data.totalTime / 1000).toFixed(2) + 's'
+    console.log('🎉 活体验证成功！', {
+      静默通过: `${data.silentPassedCount} 次`,
+      动作完成: `${data.actionPassedCount} 次`,
+      最佳质量: `${(data.bestQualityScore * 100).toFixed(1)}%`,
+      总耗时: `${(data.totalTime / 1000).toFixed(2)}s`
     })
     
-    // Send results to server
+    // 上传结果到服务器
     if (data.bestFrameImage) {
-      uploadVerificationResult({
+      uploadToServer({
         image: data.bestFrameImage,
         quality: data.bestQualityScore,
         timestamp: new Date()
       })
     }
   } else {
-    console.log('❌ Liveness verification failed')
-    // Prompt user to try again
+    console.log('❌ 验证失败，请重试')
   }
 })
 ```
 
-#### `detector-error`
-Fired when an error occurs during detection.
+---
+
+### ⚠️ detector-error
+
+**检测过程中发生错误**
 
-**Data:**
 ```typescript
 interface DetectorErrorEventData {
-  code: ErrorCode // Error code
-  message: string // Error message
+  code: ErrorCode  // 错误代码
+  message: string  // 错误信息
 }
-```
 
-**Error Codes:**
-```typescript
 enum ErrorCode {
   DETECTOR_NOT_INITIALIZED = 'DETECTOR_NOT_INITIALIZED',
   CAMERA_ACCESS_DENIED = 'CAMERA_ACCESS_DENIED',
@@ -448,124 +612,118 @@ enum ErrorCode {
 }
 ```
 
-**Example:**
+**示例：**
 ```typescript
 engine.on('detector-error', (error) => {
-  console.error(`❌ Error [${error.code}]: ${error.message}`)
-  
-  switch (error.code) {
-    case 'CAMERA_ACCESS_DENIED':
-      showErrorMessage('Please grant camera permissions')
-      break
-    case 'STREAM_ACQUISITION_FAILED':
-      showErrorMessage('Failed to access camera')
-      break
-    case 'SUSPECTED_FRAUDS_DETECTED':
-      showErrorMessage('Spoofing detected - please try again')
-      break
-    default:
-      showErrorMessage('Detection failed: ' + error.message)
+  const errorMessages: Record<string, string> = {
+    'DETECTOR_NOT_INITIALIZED': '引擎未初始化',
+    'CAMERA_ACCESS_DENIED': '摄像头权限被拒绝',
+    'STREAM_ACQUISITION_FAILED': '无法获取摄像头数据流',
+    'SUSPECTED_FRAUDS_DETECTED': '检测到欺骗行为'
   }
+  
+  console.error(`❌ 错误 [${error.code}]: ${errorMessages[error.code] || error.message}`)
+  showUserErrorPrompt(errorMessages[error.code])
 })
 ```
 
-#### `detector-debug`
-Debug information for development and troubleshooting.
+---
+
+### 🐛 detector-debug
+
+**开发和故障排除的调试信息**
 
-**Data:**
 ```typescript
 interface DetectorDebugEventData {
-  level: 'info' | 'warn' | 'error'  // Debug level
-  stage: string                      // Current processing stage
-  message: string                    // Debug message
-  details?: Record<string, any>      // Additional details
-  timestamp: number                  // Unix timestamp
+  level: 'info' | 'warn' | 'error'  // 日志级别
+  stage: string                      // 处理阶段
+  message: string                    // 调试信息
+  details?: Record<string, any>      // 额外详情
+  timestamp: number                  // Unix 时间戳
 }
 ```
 
-**Example:**
+**示例：**
 ```typescript
 engine.on('detector-debug', (debug) => {
   const time = new Date(debug.timestamp).toLocaleTimeString()
-  console.log(`[${time}] [${debug.stage}] ${debug.message}`)
+  const prefix = `[${time}] [${debug.stage}]`
   
-  if (debug.details) {
-    console.log('Details:', debug.details)
-  }
-  
-  // Log errors for troubleshooting
   if (debug.level === 'error') {
-    logErrorToServer({
-      stage: debug.stage,
-      message: debug.message,
-      details: debug.details
-    })
+    console.error(`${prefix} ❌ ${debug.message}`, debug.details)
+  } else {
+    console.log(`${prefix} ℹ️ ${debug.message}`)
   }
 })
 ```
 
-## Enumerations
+---
+
+## 📖 类型定义
 
 ### LivenessAction
 ```typescript
 enum LivenessAction {
-  BLINK = 'blink',
-  MOUTH_OPEN = 'mouth_open',
-  NOD = 'nod'
+  BLINK = 'blink',           // 眨眼
+  MOUTH_OPEN = 'mouth_open', // 张嘴
+  NOD = 'nod'                // 点头
 }
 ```
 
 ### LivenessActionStatus
 ```typescript
 enum LivenessActionStatus {
-  STARTED = 'started',      // Action prompt has started
-  COMPLETED = 'completed',  // Action successfully recognized
-  TIMEOUT = 'timeout'       // Action recognition timeout
+  STARTED = 'started',      // 动作提示已开始
+  COMPLETED = 'completed',  // 动作成功识别
+  TIMEOUT = 'timeout'       // 动作识别超时
 }
 ```
 
 ### DetectionCode
 ```typescript
 enum DetectionCode {
-  VIDEO_NO_FACE = 'VIDEO_NO_FACE',            // No face detected in the video
-  MULTIPLE_FACE = 'MULTIPLE_FACE',            // Multiple faces detected
-  FACE_TOO_SMALL = 'FACE_TOO_SMALL',          // Face size below minimum threshold
-  FACE_TOO_LARGE = 'FACE_TOO_LARGE',          // Face size above maximum threshold
-  FACE_NOT_FRONTAL = 'FACE_NOT_FRONTAL',      // Face angle not frontal enough
-  FACE_NOT_REAL = 'FACE_NOT_REAL',            // Suspected spoofing detected
-  FACE_NOT_LIVE = 'FACE_NOT_LIVE',            // Liveness score below threshold
-  FACE_LOW_QUALITY = 'FACE_LOW_QUALITY',      // Image quality below minimum
-  FACE_CHECK_PASS = 'FACE_CHECK_PASS'         // All detection checks passed
+  VIDEO_NO_FACE = 'VIDEO_NO_FACE',           // 视频中未检测到人脸
+  MULTIPLE_FACE = 'MULTIPLE_FACE',           // 检测到多张人脸
+  FACE_TOO_SMALL = 'FACE_TOO_SMALL',         // 人脸尺寸小于最小阈值
+  FACE_TOO_LARGE = 'FACE_TOO_LARGE',         // 人脸尺寸大于最大阈值
+  FACE_NOT_FRONTAL = 'FACE_NOT_FRONTAL',     // 人脸角度不够正面
+  FACE_NOT_REAL = 'FACE_NOT_REAL',           // 检测到疑似欺骗
+  FACE_NOT_LIVE = 'FACE_NOT_LIVE',           // 活体分数低于阈值
+  FACE_LOW_QUALITY = 'FACE_LOW_QUALITY',     // 图像质量低于最小值
+  FACE_CHECK_PASS = 'FACE_CHECK_PASS'        // 所有检测检查通过 ✅
 }
 ```
 
 ### ErrorCode
 ```typescript
 enum ErrorCode {
-  DETECTOR_NOT_INITIALIZED = 'DETECTOR_NOT_INITIALIZED',  // Engine not initialized
-  CAMERA_ACCESS_DENIED = 'CAMERA_ACCESS_DENIED',          // Camera permission denied
-  STREAM_ACQUISITION_FAILED = 'STREAM_ACQUISITION_FAILED', // Failed to get video stream
-  SUSPECTED_FRAUDS_DETECTED = 'SUSPECTED_FRAUDS_DETECTED'  // Spoofing/fraud suspected
+  DETECTOR_NOT_INITIALIZED = 'DETECTOR_NOT_INITIALIZED',  // 引擎未初始化
+  CAMERA_ACCESS_DENIED = 'CAMERA_ACCESS_DENIED',          // 摄像头权限被拒
+  STREAM_ACQUISITION_FAILED = 'STREAM_ACQUISITION_FAILED', // 获取视频流失败
+  SUSPECTED_FRAUDS_DETECTED = 'SUSPECTED_FRAUDS_DETECTED'  // 检测到欺骗/欺诈
 }
 ```
 
-## Advanced Usage
+---
 
-For comprehensive examples and advanced usage patterns, please refer to the official demo project:
+## 🎓 高级用法与示例
 
-**👉 [Vue Demo Project](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/)**
+### 完整的 Vue 3 演示项目
 
-The demo includes:
-- Complete Vue 3 integration with TypeScript
-- Real-time detection visualization
-- Configuration panel for experimenting with different settings
-- Event handling examples for all engine events
-- Debug panel showing detailed detection information
-- Responsive UI design for mobile and desktop
-- Error handling and user feedback patterns
-- Result export and image capture examples
+有关全面的示例和高级使用模式，请参考官方演示项目：
 
-To run the demo locally:
+**[Vue 演示项目](https://github.com/sssxyd/face-liveness-detector/tree/main/demos/vue-demo/)** 包括：
+
+- ✅ 完整的 Vue 3 + TypeScript 集成
+- ✅ 实时检测结果可视化
+- ✅ 动态配置面板
+- ✅ 所有引擎事件的完整处理
+- ✅ 实时调试面板
+- ✅ 响应式移动端 + 桌面端 UI
+- ✅ 错误处理和用户反馈
+- ✅ 结果导出和图像捕获
+
+**快速启动演示：**
 
 ```bash
 cd demos/vue-demo
@@ -573,123 +731,116 @@ npm install
 npm run dev
 ```
 
-Then open your browser to the displayed local URL to see the detection engine in action.
+然后在浏览器中打开显示的本地 URL。
+
+---
 
-## Downloading and Hosting Model Files
+## 📥 本地部署模型文件
 
-To avoid CDN dependencies and improve performance, you can download model files locally:
+### 为什么需要本地部署？
 
-### Available Download Scripts
+- 🚀 **提升性能** - 避免 CDN 延迟
+- 🔒 **隐私保护** - 完全离线运行
+- 🌐 **网络独立** - 不依赖外部连接
 
-Two scripts are provided in the root directory:
+### 可用脚本
 
-#### 1. Copy Human.js Models
+项目根目录提供两个下载脚本：
+
+#### 1️⃣ 复制 Human.js 模型
 
 ```bash
-node copy-human-models.js
+node copy-models.js
 ```
 
-**What it does:**
-- Copies face detection models from `node_modules/@vladmandic/human/models`
-- Saves to `public/models/` directory
-- Downloads both `.json` and `.bin` model files
-- Shows file size and progress
+**功能：**
+- 从 `node_modules/@vladmandic/human/models` 复制模型
+- 保存到 `public/models/` 目录
+- 包含 `.json` 和 `.bin` 模型文件
+- 自动显示文件大小和进度
 
-#### 2. Download TensorFlow.js WASM Files
+#### 2️⃣ 下载 TensorFlow WASM 文件
 
 ```bash
-node download-tensorflow-wasm.js
+node download-wasm.js
 ```
 
-**What it does:**
-- Downloads TensorFlow.js WASM backend files
-- Saves to `public/wasm/` directory
-- Downloads 4 critical files:
+**功能：**
+- 自动下载 TensorFlow.js WASM 后端
+- 保存到 `public/wasm/` 目录
+- 下载 4 个关键文件：
   - `tf-backend-wasm.min.js`
   - `tfjs-backend-wasm.wasm`
   - `tfjs-backend-wasm-simd.wasm`
   - `tfjs-backend-wasm-threaded-simd.wasm`
-- **Supports multiple CDN sources** with automatic fallback:
-  1. unpkg.com (primary)
-  2. cdn.jsdelivr.net (backup)
-  3. esm.sh (fallback)
-  4. cdn.esm.sh (last resort)
+- **智能多 CDN 源** 自动回退：
+  1. unpkg.com（推荐）
+  2. cdn.jsdelivr.net
+  3. esm.sh
+  4. cdn.esm.sh
 
-### Configuration to Use Local Files
+### 配置项目使用本地文件
 
-Once downloaded, configure the engine to use these local files:
+下载完成后，在引擎初始化时指定本地路径：
 
 ```typescript
 const engine = new FaceDetectionEngine({
-  // Use local files instead of CDN
+  // 使用本地文件而不是 CDN
   human_model_path: '/models',
   tensorflow_wasm_path: '/wasm',
   
-  // ... rest of configuration
+  // 其他配置...
 })
 ```
 
-## Browser Requirements
+### 自动化设置（推荐）
+
+在 `package.json` 中配置 `postinstall` 钩子实现自动下载：
+
+```json
+{
+  "scripts": {
+    "postinstall": "node scripts/copy-models.js && node scripts/download-wasm.js"
+  }
+}
+```
+
+---
+
+## 🌐 浏览器兼容性
 
-- Modern browsers with WebRTC support (Chrome, Firefox, Edge, Safari 11+)
-- HTTPS required for getUserMedia
-- WebGL or WASM backend support
+| 浏览器 | 版本 | 支持 | 备注 |
+|--------|------|------|------|
+| Chrome | 60+ | ✅ | 完全支持 |
+| Firefox | 55+ | ✅ | 完全支持 |
+| Safari | 11+ | ✅ | 完全支持 |
+| Edge | 79+ | ✅ | 完全支持 |
 
-## Performance Tips
+**系统要求：**
 
-1. **Adjust detection frame delay** - Higher delay = lower CPU usage but slower detection
-   ```typescript
-   engine.updateConfig({ detection_frame_delay: 200 })
-   ```
+- 📱 支持 **WebRTC** 的现代浏览器
+- 🔒 **HTTPS 环境**（开发可用 localhost）
+- ⚙️ **WebGL** 或 **WASM** 后端支持
+- 📹 **用户授权** - 需要摄像头权限
 
-2. **Reduce canvas size** - Smaller canvases process faster
-   ```typescript
-   engine.updateConfig({ 
-     video_width: 480,
-     video_height: 480
-   })
-   ```
+---
 
-3. **Optimize light conditions** - Better lighting = better detection
-   - Avoid backlighting
-   - Ensure face is well-lit
+## 📄 许可证
 
-4. **Monitor debug output** - Use debug events to identify bottlenecks
-   ```typescript
-   engine.on('detector-debug', (debug) => {
-     if (debug.stage === 'detection') {
-       console.time(debug.message)
-     }
-   })
-   ```
+[MIT License](./LICENSE) - 自由使用和修改
 
-## Troubleshooting
+## 🤝 贡献
 
-### "Camera access denied"
-- Ensure HTTPS is used (or localhost for development)
-- Check browser permissions
-- User must grant camera access
+欢迎提交 Issue 和 Pull Request！
 
-### "Video loading timeout"
-- Check internet connection
-- Verify model files are accessible
-- Increase `video_load_timeout`
+---
 
-### Poor detection accuracy
-- Ensure good lighting
-- Keep face centered in frame
-- Face should be 50-90% of frame
-- Face should be frontal (not tilted)
+<div align="center">
 
-### High CPU usage
-- Increase `detection_frame_delay`
-- Reduce `video_width` and `video_height`
-- Disable `show_action_prompt` if not needed
+**[⬆ 返回顶部](#人脸活体检测引擎)**
 
-## License
+Made with ❤️ by [sssxyd](https://github.com/sssxyd)
 
-MIT
+</div>
 
-## Support
 
-For issues and questions, please visit: https://github.com/sssxyd/face-liveness-detector/issues