biometry-angular-components

Angular UI component library for capturing biometric data — face photos, document scans, voice recordings, and liveness video — in the browser. Each component is standalone, handles its own camera/microphone permissions, and emits ready-to-upload File objects.

Features

• Face capture — take a framed selfie photo.
• Document scan — capture a document (ID card, passport) inside a fixed aspect-ratio frame.
• Voice recorder — record a short spoken passphrase of random digits.
• Face recorder — record a liveness video where the user reads a digit challenge aloud, producing separate video + audio files.
• Adaptive capture quality based on device class (desktop / mobile / low-end).
• Automatic microphone/camera permission handling and stream cleanup.
• All components are standalone — no NgModule required.

Requirements

| Peer dependency | Version | | --------------- | ------- | | @angular/core | ^18.2.0 | | @angular/common | ^18.2.0 |

Capture relies on the browser MediaDevices and MediaRecorder APIs, so it must run in a secure context (https:// or localhost).

Installation

npm install biometry-angular-components

Runtime dependencies (recordrtc, fix-webm-duration, tslib) are installed automatically.

Quick start

Every component is standalone — import it directly into a standalone component (or an NgModule's imports):

import { Component } from '@angular/core';
import { FaceCaptureComponent } from 'biometry-angular-components';

@Component({
  selector: 'app-verify',
  standalone: true,
  imports: [FaceCaptureComponent],
  template: `
    <bio-face-capture
      (capture)="onCapture($event)"
      (confirmCapture)="onConfirm($event)">
    </bio-face-capture>
  `,
})
export class VerifyComponent {
  onCapture(file: File) {
    // Fired the instant the photo is taken (before the user confirms).
  }
  onConfirm(file: File) {
    // Fired when the user taps the confirm (tick) button — upload this file.
  }
}

capture/recorded vs confirmCapture/confirmRecording: the first fires immediately when media is captured, the second only after the user reviews and confirms it. Use the confirm events for the file you actually upload.

Components

<bio-face-capture>

Takes a single selfie photo inside a portrait frame.

| Input | Type | Default | Description | | ----- | ---- | ------- | ----------- | | rectWidth | number | 360 | Frame width in px. | | rectHeight | number | 576 | Frame height in px. | | noShadow | boolean | false | Disable the card drop shadow. |

| Output | Payload | Description | | ------ | ------- | ----------- | | capture | File | Photo taken (JPEG, face.jpg), before confirmation. | | confirmCapture | File | User confirmed the photo. |

<bio-doc-scan>

Captures a document inside a fixed aspect-ratio frame (landscape by default), centre-cropped to the frame.

| Input | Type | Default | Description | | ----- | ---- | ------- | ----------- | | rectWidth | number | 640 | Frame width in px. | | rectHeight | number | 400 | Frame height in px. | | noShadow | boolean | false | Disable the card drop shadow. |

| Output | Payload | Description | | ------ | ------- | ----------- | | capture | File | Photo taken (JPEG, document.jpg), before confirmation. | | confirmCapture | File | User confirmed the photo. |

<bio-voice-recorder>

Records a short spoken passphrase. The user is shown a random sequence of digits to read aloud during a fixed 7-second recording (after a 3-second countdown).

| Input | Type | Default | Description | | ----- | ---- | ------- | ----------- | | rectWidth | number | 360 | Component width in px. | | rectHeight | number | undefined | Optional height in px. | | noShadow | boolean | false | Disable the card drop shadow. | | className | string | undefined | Extra CSS class on the root element. | | style | { [k: string]: any } | undefined | Inline styles on the root element. |

| Output | Payload | Description | | ------ | ------- | ----------- | | recorded | { file: File; phrase: string } | Recording finished (WebM audio + the spoken phrase), before confirmation. | | confirmRecording | { file: File; phrase: string } | User confirmed the recording. |

phrase is the digit sequence spelled out in words (e.g. "four one seven ..."), matching what the user was asked to say.

<bio-face-recorder>

Records a liveness video in which the user reads a digit challenge aloud. Produces separate video and audio files (both WebM) plus the spoken phrase. Flow: preparation → countdown → recording → review.

| Input | Type | Default | Description | | ----- | ---- | ------- | ----------- | | countdownSeconds | number | 3 | Countdown before recording starts. | | recordingSeconds | number | 7 | Recording duration. | | rectWidth | number | 720 | Frame width in px. | | rectHeight | number | 1280 | Frame height in px. | | challengeDigits | number[] \| null | undefined | Server-issued challenge digits (each 0–9) the user must read. When provided, these are used instead of a randomly generated challenge so the backend can verify the spoken digits against what it issued. Invalid/empty values fall back to a random challenge. Only applied while idle (not mid-capture). |

| Output | Payload | Description | | ------ | ------- | ----------- | | recorded | { file: File; audio: File; phrase: string } | Recording finished (video file + separate audio), before confirmation. | | confirmRecording | { file: File; audio: File; phrase: string } | User confirmed the recording. |

Using a server-issued challenge:

<bio-face-recorder
  [challengeDigits]="challenge"
  (confirmRecording)="onRecording($event)">
</bio-face-recorder>

challenge = [4, 1, 7, 0, 9, 2, 5]; // fetched from your backend
onRecording(e: { file: File; audio: File; phrase: string }) {
  // Upload e.file + e.audio; backend verifies the spoken digits.
}

Services and utilities

These are exported for advanced use if you want to build your own capture UI.

| Export | Kind | Description | | ------ | ---- | ----------- | | PermissionsService | injectable | requestCamera({ width, height, audio }), requestMicrophone(), stopStream(stream). Applies device-adaptive constraints. | | RecorderService | injectable | start(stream, type), stop(): Promise<Blob>, cancel(). Wraps RecordRTC with WebM duration fixing. | | getSupportedMimeType() | function | Best supported recording MIME type for the current browser. | | generateRandomDigits(count) | function | Random shuffled digit array (values 0–9, no repeats). | | numbersToPhrase(digits) | function | Spell a digit array as space-separated words. |

Local development

This repo is an Angular CLI workspace containing the library (src/) and a demo app (example/).

# Build the library
ng build biometry-angular-components   # → dist/

# Run unit tests
ng test biometry-angular-components

Publishing

npm publish runs the build automatically via the prepublishOnly hook, so from the repo root:

npm version minor   # bump the version (e.g. 1.1.1 → 1.2.0)
npm publish         # builds, then publishes to npm

License

MIT