UGX Face Liveness

Angular library for blink/smile liveness checks with snapshot/video capture.

Version compatibility

Use a package major line that matches your Angular major:

| ugx-face-liveness line | Angular support | Install |
| --- | --- | --- |
| 0.x (legacy) | 19.x | npm i ugx-face-liveness@0 |
| 1.x (current) | 16.x - 19.x | npm i ugx-face-liveness@1 |

Install

- Install the package line for your Angular version (see table above).
- The current 1.x line supports Angular 16.x - 19.x.
- For Angular 16-19 projects:
``bash
npm i ugx-face-liveness@1
`

Asset setup (required)

The library loads models from /assets/face-liveness/models. Add the assets block to your app (and test) builds in angular.json:
Also, load the face-api js file from https://cdn.jsdelivr.net/npm/face-api.js@0.22.2/dist/face-api.min.js ideally in your index.html file
Models are gotten from https://github.com/justadudewhohacks/face-api.js-models

`json
{
"glob": "*/",
"input": "projects/face-liveness/src/lib/assets",
"output": "assets/face-liveness"
}
`

Basic usage (standalone)

`ts
import { Component } from "@angular/core";
import { FaceLivenessComponent } from "ugx-face-liveness";

@Component({
selector: "app-root",
standalone: true,
imports: [FaceLivenessComponent],
template: ,
})
export class AppComponent {
onDone(result: { snapshot: Blob; video: Blob | null }) {
// handle result
}
}
`

Basic usage (NgModule)

`ts
import { NgModule } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";
import { FaceLivenessModule } from "ugx-face-liveness";
import { AppComponent } from "./app.component";

@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, FaceLivenessModule],
bootstrap: [AppComponent],
})
export class AppModule {}
`

Then drop in your templates.

Inputs

- showDebug: boolean – overlay debug info; defaults to false.
- faceDetectionOptions?: { detectionInterval?: number; scoreThreshold?: number; minConfidence?: number; maxFaceAngle?: number; singleAction?: 'blink' | 'smile'; singleActionMode?: boolean; } – tune detection cadence/thresholds and optionally force a single action flow. Prefer singleAction; singleActionMode is the deprecated equivalent of singleAction: 'smile'.

$3

Skip the full look-straight → blink → smile sequence and require only one action:

`html
[faceDetectionOptions]="{ singleAction: 'blink' }"
(livenessCompleted)="onDone($event)"
>
`

Valid actions: 'blink' or 'smile'. Legacy singleActionMode: true maps to singleAction: 'smile'.

Outputs

- (faceDetectionStatusChange)="onFaceStatusChange(isValid: boolean)" – alignment/validation status.
- (errorOccurred)="onError(message: string)" – user-facing error messages.
- (livenessCompleted)="onDone({ snapshot: Blob, video: Blob | null })" – final media payload.

$3

Snapshot is image/jpeg; video (when available) is video/webm (vp8/vp9). Convert to base64 if needed:

`ts
const toBase64 = async (blob: Blob) => data:${blob.type};base64,${btoa(String.fromCharCode(...new Uint8Array(await blob.arrayBuffer())))};
`

Common gotchas

- Camera permission + HTTPS/localhost required.
- Ensure assets are copied (see Asset setup); missing models will block detection.
- Blink/smile stages depend on lighting and frame rate; defaults use detectionInterval 120ms and blink EAR threshold 0.25.
- If video blob is null, check MediaRecorder support and MIME type (falls back to vp8).

Local development

- Build library: npm run build:lib (alias for ng build face-liveness).
- Serve demo app: npm start.
- Path alias is configured: "ugx-face-liveness": ["projects/face-liveness/src/public-api.ts", "dist/ugx-face-liveness"].

Publishing

After building, publish from the dist folder:

`bash
cd dist/ugx-face-liveness
npm publish
`

For compatibility-line releases, publish by major line:

- 0.x line: Angular 19-only maintenance releases.
- 1.x` line: Angular 16-19 compatibility releases.

Contributions

If you will love to contribute, follow the git link and raise a pr