Tutorial: 42-advanced-face-detection

功能描述

本文档详细介绍了如何使用 TRTC Web SDK 的人脸检测插件，实时检测摄像头视频流中的人脸状态变化。该插件采用智能防抖逻辑，仅在人脸出现/消失状态真正变化时触发回调，避免因光线变化或短暂遮挡导致的误报。

前提条件

• TRTC Web SDK 版本 >= 5.15.0
• 需要先开启摄像头视频流

平台兼容性

实现流程

部署静态资源

该插件依赖一些静态资源文件，为保证浏览器可以正常加载和运行这些文件，你需要完成以下步骤：

1. 将 node_modules/trtc-sdk-v5/assets 目录发布至 CDN 或者静态资源服务器中。
2. 在创建 trtc 实例时传入您的 CDN 地址给 assetsPath 参数，例如： TRTC.create({ assetsPath: 'https://xxxx/assets' })，SDK 会按需加载相关资源文件。

• 若您的版本低于 v5.10.0，您需要下载解压 https://web.sdk.qcloud.com/trtc/webrtc/v5/assets/assets.zip 后，发布至 CDN 或者静态资源服务器中。
• 如果目录下文件的 Host URL 与网页应用的 Host URL 不一致，则需要开启访问文件域名的 CORS 策略。
• 不能把目录文件放在 HTTP 服务下，因为在 HTTPS 域名下加载 HTTP 资源会被浏览器安全策略禁止。

引入并注册插件

import { FaceDetection } from 'trtc-sdk-v5/plugins/video-effect/face-detection';
const trtc = TRTC.create({ 
  plugins: [FaceDetection], 
  assetsPath: 'https://xxxx/assets'  // 替换为您的静态资源地址
});

开启本地摄像头

await trtc.startLocalVideo();

开启人脸检测插件

await trtc.startPlugin('FaceDetection', {
  onFaceDetectionStateChanged: (hasFace) => {
    if (hasFace) {
      console.log('检测到人脸出现');
      // 执行人脸出现时的业务逻辑
    } else {
      console.log('检测到人脸消失');
      // 执行人脸消失时的业务逻辑
    }
  },
  detectionInterval: 300,    // 检测间隔，单位ms (可选，默认300)
  minConfidence: 0.8,        // 最小置信度阈值 (可选，默认0.8)
  missingTimeout: 1000       // 人脸消失确认时间，单位ms (可选，默认1000)
});

按需更新参数

// 更新检测参数 - 提高检测灵敏度
await trtc.updatePlugin('FaceDetection', {
  onFaceDetectionStateChanged: (hasFace) => {
    console.log('更新后的检测状态:', hasFace);
  },
  detectionInterval: 200,    // 缩短检测间隔，提高实时性
  minConfidence: 0.7,        // 降低置信度阈值，提高检测灵敏度
  missingTimeout: 1500       // 延长消失确认时间，减少误报
});

关闭人脸检测

await trtc.stopPlugin('FaceDetection');

核心特性

智能防抖逻辑

插件采用非对称防抖机制，确保状态变化的准确性：

• 人脸出现（true）：立即触发，实时响应
• 人脸消失（false）：延迟触发，需满足 missingTimeout 条件才确认

该设计有效避免了因以下情况导致的误报：

• 人脸短暂转头或低头
• 光线瞬间变化
• 物体短暂遮挡

视频流状态同步

当本地视频流状态变化时，插件会自动处理：

API 说明

trtc.startPlugin('FaceDetection', options)

用于开启人脸检测插件。

options

Example:

await trtc.startPlugin('FaceDetection', {
  onFaceDetectionStateChanged: (hasFace) => {
    if (hasFace) {
      console.log('人脸出现');
    } else {
      console.log('人脸消失');
    }
  },
  detectionInterval: 300,
  minConfidence: 0.8,
  missingTimeout: 1000
});

trtc.updatePlugin('FaceDetection', options)

可修改人脸检测参数。

options

Example:

await trtc.updatePlugin('FaceDetection', {
  detectionInterval: 200,
  minConfidence: 0.7,
  missingTimeout: 1500
});

trtc.stopPlugin('FaceDetection')

关闭人脸检测。

常见问题

1. 如何调整检测的灵敏度？

可以通过以下参数组合调整：

• 提高灵敏度：降低 minConfidence，缩短 detectionInterval
• 降低灵敏度：提高 minConfidence，延长 missingTimeout

2. 视频流恢复后需要重新开启检测吗？

不需要。插件会自动处理视频流状态变化，恢复后会继续检测。