@face-auth/face-id-video/README.md

Utility library for capturing photos from webcam video streams in the browser. Handles camera selection, image formatting, and output for face authentication APIs.

# @face-auth/face-id-video

Browser-only webcam utilities for starting video streams and capturing still images.
Current package version: `0.0.3`.

## Installation

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

## License

Proprietary runtime-only license. You may execute unmodified copies of the package,
but modification, redistribution, sublicensing, and other reuse are not permitted.
See `LICENSE`.

## Public API

Import from the package root only. Deep imports into `dist/` or `dist/src/` are not part of the public contract.

### Class

- `FaceVideo`

### Exported types

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

## `FaceVideo`

Creates a camera/capture manager over an `HTMLVideoElement`.

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

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

### Methods

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

## Camera selection

You can ask the browser for available video inputs:

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

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

To start the stream, either provide `preferredFacingMode` or pass a specific `deviceId` as the second argument.

```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 output

`capture()` returns a `CaptureResult` with a `blob` and the resolved `imageType`.

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

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

If `imageType` is omitted, the package uses `image/png` by default.

## Camera started event

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

faceVideo.onCameraStarted(handleCameraStarted);

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

faceVideo.offCameraStarted(handleCameraStarted);
```

## Runtime contracts

### `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;
}
```

### Camera errors

When `start()` fails, the thrown error may include one of these `code` values:

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

## Notes

- `capture()` must be called after `start()`.
- The package currently returns captured images as `Blob`. It does not return Base64 directly.
- The target environment is the browser.