# @face-auth/face-id-video 中文文档

规范地址：https://npmcn.com/package/%40face-auth/face-id-video/

版本：0\.0\.3
npm 元数据更新时间：2026-03-13T02:54:24.112Z
中文译文更新时间：2026-11-14T08:09:00.285Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40face-auth/face-id-video
原文对照：https://npmcn.com/package/%40face-auth/face-id-video/?lang=original
项目主页：https://www.face-auth.me/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：17.7 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-08-01T19:16:28.440Z
- 最新版本发布：2026-03-13T02:54:23.980Z
- 近 30 天下载量：2187（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 1 个）

## 中文简介

用于在浏览器中捕捉从 Webcam 视频流取相片的功能库. 处理相机选择,图像格式化,以及用于面相认证API的输出.

## 安装

```sh
npm install @face-auth/face-id-video
```

也可以使用：`pnpm add @face-auth/face-id-video`、`yarn add @face-auth/face-id-video`、`bun add @face-auth/face-id-video`

## README

# @face-auth/face-id-video (英语)

只浏览器的 Webcam 工具, 用于启动视频流并捕获静态图像 . 当前软件包版本 : `0.0.3`。 。 。 .

## 安装

```bash
npm install @face-auth/face-id-video
```

## 许可证

专有跑时专用许可证. 您可以执行软件包的未修改副本, 但不允许修改、再分配、分许可证和其他再利用. 见 `LICENSE`。 。 。 .

## 公共 API

只从软件包根导入 。 深度进口 `dist/` 或者说 `dist/src/` 不属于公共合同.

### 类

-   `FaceVideo`

### 导出类型

-   `CameraError`
-   `CameraOptions`
-   `CaptureOptions`
-   `CaptureResult`
-   `FaceVideoElement`
-   `OvalDimensions`

## `FaceVideo`

创建一个相机/抓取管理器 `HTMLVideoElement`。 。 。 .

```ts
import { FaceVideo } from "@face-auth/face-id-video";

const videoElement = document.getElementById("videoRef") as HTMLVideoElement;
const faceVideo = new FaceVideo(videoElement);
```

### 方法

-   `getDevices(): Promise<MediaDeviceInfo[]>`
-   `start(options?: CameraOptions, deviceId?: string): Promise<void>`
-   `capture(options: CaptureOptions): Promise<CaptureResult>`
-   `stop(): void`
-   `onCameraStarted(callback): void`
-   `offCameraStarted(callback): void`

## 相机选择

您可以向浏览器询问可用的视频输入 :

```ts
const devices = await faceVideo.getDevices();

devices.forEach((device) => {
  console.log(device.deviceId, device.label);
});
```

要启动溪流,要么提供 `preferredFacingMode` 或通过特定的 `deviceId` 作为第二个论点.

```ts
await faceVideo.start({
  preferredFacingMode: "user",
  idealResolution: { width: 1280, height: 720 }
});
```

```ts
const devices = await faceVideo.getDevices();
const selectedDeviceId = devices[0]?.deviceId;

await faceVideo.start(
  {
    preferredFacingMode: "environment",
    idealResolution: { width: 1280, height: 720 }
  },
  selectedDeviceId
);
```

## 抓取输出

`capture()` 返回 a `CaptureResult` 带有 `blob` 决议 `imageType`。 。 。 .

```ts
const result = await faceVideo.capture({
  imageType: "image/jpeg"
});

console.log(result.blob);
console.log(result.imageType);
```

若为 `imageType` ,软件包使用 `image/png` 默认.

## 相机启动事件

```ts
const handleCameraStarted = () => {
  console.log("Camera is ready");
};

faceVideo.onCameraStarted(handleCameraStarted);

await faceVideo.start({
  preferredFacingMode: "user"
});

faceVideo.offCameraStarted(handleCameraStarted);
```

## 运行时间合同

### `CameraOptions`

```ts
interface CameraOptions {
  preferredFacingMode?: "user" | "environment";
  idealResolution?: { width: number; height: number };
}
```

### `CaptureOptions`

```ts
interface CaptureOptions {
  imageType?: string;
}
```

### `CaptureResult`

```ts
interface CaptureResult {
  blob: Blob;
  imageType: string;
}
```

### 相机错误

何时 `start()` 失败, 抛出的错误可能包括其中之一 `code` 值 :

-   `PERMISSION_DENIED`
-   `NO_DEVICES`
-   `OVERCONSTRAINED`
-   `UNKNOWN`

## 页:1

-   `capture()` 必须在后面调用 `start()`。 。 。 .
-   软件包目前返回抓取的图像为 `Blob`它不直接返回 Base64.
-   目标环境为浏览器.

## 常见问题

### @face-auth/face-id-video 是什么？

用于在浏览器中捕捉从 Webcam 视频流取相片的功能库\. 处理相机选择,图像格式化,以及用于面相认证API的输出\.

### 如何安装 @face-auth/face-id-video？

在项目目录运行 npm install @face-auth/face-id-video，或使用 pnpm add / yarn add / bun add。

### @face-auth/face-id-video 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @face-auth/face-id-video 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @face-auth/face-id-video 可以商用吗？

@face-auth/face-id-video 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @face-auth/face-id-video 的下载量有多少？

根据 npm 官方下载统计，@face-auth/face-id-video 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,187 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @face-auth/face-id-video 还在维护吗？

最新版本 0\.0\.3 发布于 2026/03/13（8 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 1 个；首次发布于 2025/08/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。