# @face-auth/face-detector 中文文档 规范地址：https://npmcn.com/package/%40face-auth/face-detector/ 版本：0\.0\.6 npm 元数据更新时间：2026-03-31T02:25:43.450Z 中文译文更新时间：2026-11-14T08:08:53.296Z 软件包许可：SEE LICENSE IN LICENSE 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40face-auth/face-detector 原文对照：https://npmcn.com/package/%40face-auth/face-detector/?lang=original 项目主页：https://www.face-auth.me/ ## 关键信息（来自 npm 元数据） - 包体积（解压后）：96.6 kB，24 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2025-08-29T01:56:44.162Z - 最新版本发布：2026-03-31T02:25:43.333Z - 近 30 天下载量：3005（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：6（近 12 个月 5 个） ## 中文简介 为浏览器视频流提供轻量级面相检测,提供有面相存在的回调,质量引导,和边框等功能. ## 安装 ```sh npm install @face-auth/face-detector ``` 也可以使用：`pnpm add @face-auth/face-detector`、`yarn add @face-auth/face-detector`、`bun add @face-auth/face-detector` ## README # @ face-auth/ 面部检测器 # ![Face Auth](https://www.face-auth.me/wp-content/uploads/2024/08/face-auth-logo-allblue.webp) ![Version](https://img.shields.io/badge/Version%20-%200.0.6-blue.svg) ![Last update](https://img.shields.io/badge/%F0%9F%93%85%20Last%20update%20-%20March%2030%2C%202026-brightgreen.svg) ![Browser only](https://img.shields.io/badge/%E2%9C%94%20Target%20Environment%20-%20Browser%20only-brightgreen.svg) 浏览器视频流的轻量级面部检测. 当前软件包版本 : `0.0.6`。 。 。 . ## 安装 ```bash npm install @face-auth/face-detector ``` ## 许可证 专有跑时专用许可证. 您可以执行软件包的未修改副本, 但不允许修改、再分配、分许可证和其他再利用. 见 `LICENSE`。 。 。 . ## 支助 - 主页 : `https://www.face-auth.me/` - 支助: `support@face-auth.me` ## 软件包格式 - `import` 决定一揽子无害环境管理捆绑. - `require` 解析到软件包 CommunityJS 捆绑. - 深度进口不是所支持的公共合同的一部分;只消费包的根入点. ## 公共 API ### 类 - `FaceVideoDetector` - `FaceImageDetector` ### 数字和助手 - `FaceAdjustment` - `getInscribedCircle(...)` - `isEllipseInside(...)` ### 导出类型 - `BoundingBox` - `Detection` - `DetectionParams` - `DetectionResult` - `ImageDetectionResult` - `FaceKeypoint` - `FacePoseMetrics` - `FaceQualityMetrics` - `FaceQualityGateResult` - `FaceQualityWarning` - `FaceQualityWarningMetric` - `QualityGateConfig` ## `FaceVideoDetector` 创建一个检测器 `HTMLVideoElement` 并发出检测结果. ```ts import { FaceVideoDetector } from '@face-auth/face-detector'; const videoElement = document.getElementById('video') as HTMLVideoElement; const detector = new FaceVideoDetector(videoElement); ``` ### 方法 - `startDetecting(params?: DetectionParams): Promise` - `stopDetecting(): Promise` - `onDetection(callback): void` - `offDetection(callback): void` `onDetection` 回调收到一个 `DetectionResult`数字 : ```ts { tick: number; detections: Detection[]; } ``` ## `FaceImageDetector` 在单一图像源上运行面相检测. ```ts import { FaceImageDetector } from '@face-auth/face-detector'; const imageDetector = new FaceImageDetector(); const result = await imageDetector.detect(fileOrCanvasOrImageBitmap, { qualityGateConfig: { strictShouldPass: true, }, }); ``` ### 方法 - `detect(image: ImageBitmapSource, options?): Promise` ## 检测输出( 摘要) ```ts { detections: Array<{ boundingBox: { x: number; y: number; width: number; height: number; }; score: number; keypoints: Array<{ x: number; y: number; normalizedX: number; normalizedY: number; label?: string; score?: number; }>; quality: { shouldPass: boolean; faceAdjustment: 'none' | 'move_closer' | 'move_farther' | 'show_full_face' | 'turn_face_left' | 'turn_face_right' | 'tilt_head_left' | 'tilt_head_right' | 'lower_chin' | 'raise_chin' | 'improve_lighting' | 'improve_focus'; warning: { metric?: string; measuredValue?: number; threshold?: number; } | null; metrics: { faceAreaRatio: number; blurVariance: number | null; blackClippingRatio: number | null; brightnessMean: number | null; pose: { rollDeg: number | null; yawRatio: number | null; pitchRatio: number | null; }; }; }; }>; } ``` 对于视频探测,回调有效载荷还包括: `tick`,则 `performance.now()` 这个处理过的相框的时标. 方向调整: - `turn_face_left` 编号 : `turn_face_right` 是当前检测到的姿势的正向转动提示. - `tilt_head_left` 编号 : `tilt_head_right` 是修正卷(从头到肩)提示. ## `FaceAdjustment` 参考文献 `faceAdjustment` 总是返回一个主要修正目标. | 数值 | 要求作何种更正 | | --- | --- | | `none` | 无需更正。 捕获质量目前是可以接受的. | | `move_closer` | 将相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. | | `move_farther` | 将相机上的脸移得更远(相机中的脸看起来太大了). | | `show_full_face` | 保持面部的清晰和前方,从而可以可靠地测量姿势. | | `turn_face_left` | 将脸部略向用户左侧,以提升正面对齐. | | `turn_face_right` | 将相貌稍微转向用户的右侧来改进正面对齐. | | `tilt_head_left` | 通过将头部略向用户左侧倾斜来正确滚动. | | `tilt_head_right` | 通过将头部略向用户右侧倾斜来正确滚动. | | `lower_chin` | 下巴再低一点. | | `raise_chin` | 略举下巴. | | `improve_lighting` | 改善面部照明/接触条件. | | `improve_focus` | 改进图像锐度/ 焦点( 减少模糊度) . | ## `FaceQualityWarningMetric` 参考文献 何时 `quality.warning` 在场, `metric` 可为: | 数值 | 计量意义 | | --- | --- | | `faceAreaRatio` | 相框中的相对面相大小( N)`face bounding box area / frame area`) (中文(简体) ). | | `blurVariance` | 锐度代理(拉普拉西安差异);低值表示模糊. | | `brightnessMean` | 抽样面部区域的平均亮度. | | `blackClippingRatio` | 面相区域近黑像素比例. | | `rollDeg` | 平面头向倾斜角以度为单位(相接相接). | | `yawRatio` | 水平转出/转出中心摆出比例. | | `pitchRatio` | 垂直下巴姿势比(上下). | ## 示例(视频) ```ts detector.startDetecting({ minIntervalMs: 120 }); detector.onDetection((result) => { const face = result.detections[0]; if (!face) return; console.log(face.boundingBox); console.log(face.quality.shouldPass); console.log(face.quality.faceAdjustment); console.log(face.quality.warning); console.log(face.quality.metrics); }); ``` ## 浏览器支持 - 仅浏览器运行时间 . - 要求数 `HTMLVideoElement` 编号 : `ImageBitmapSource` 输入. - `DetectionParams.minIntervalMs` 默认为 `100` 当省略时. ## 常见问题 ### @face-auth/face-detector 是什么？ 为浏览器视频流提供轻量级面相检测,提供有面相存在的回调,质量引导,和边框等功能\. ### 如何安装 @face-auth/face-detector？ 在项目目录运行 npm install @face-auth/face-detector，或使用 pnpm add / yarn add / bun add。 ### @face-auth/face-detector 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @face-auth/face-detector 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @face-auth/face-detector 可以商用吗？ @face-auth/face-detector 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。 ### @face-auth/face-detector 的下载量有多少？ 根据 npm 官方下载统计，@face-auth/face-detector 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,005 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @face-auth/face-detector 还在维护吗？ 最新版本 0\.0\.6 发布于 2026/03/31（7 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 5 个；首次发布于 2025/08/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。