biometry-angular-components
v1.9.1
Published
Angular UI component library for capturing biometric data
Maintainers
Readme
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-componentsRuntime 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/recordedvsconfirmCapture/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. |
Camera hardware controls (added in 1.9.0, BM-489). On a device that reports the capability, the preview
also offers camera switching, a torch toggle and tap-to-focus. There are no inputs
to configure: each control is read from the active MediaStreamTrack and is
absent from the DOM when the hardware does not support it, rather than present
and inert — a flash button on a laptop looks like a broken feature, not a missing one.
| Control | Shown when | Notes |
| ------- | ---------- | ----- |
| Switch camera | more than one video input | Wraps through the list. Resolution and frame rate still come from the adaptive constraints, so a switched camera is configured like the first. A retake keeps the camera the user chose. |
| Torch | the track reports torch | Reflects the hardware state: a device that advertises a torch and then refuses it leaves the control off rather than lying. |
| Tap-to-focus | the track reports focusMode single-shot or manual | Tapping the preview sets pointsOfInterest, normalised against the displayed box. The crosshair cursor appears only where tapping does something. |
Capabilities are re-read on every camera switch, and cleared when the stream stops.
getCapabilities() is not implemented in every browser (notably Firefox); where it
is missing, no controls are offered and capture is unaffected.
<bio-voice-recorder>
Records a spoken passphrase for voice enrollment. The user is shown a nine-digit sequence (1-9) to read aloud during a fixed 10-second recording (after a 3-second countdown), and this repeats for takes recordings before the component emits. Each take uses a different sequence from a fixed published set — the same set for every user. A high-contrast "Recording n of m" chip with progress dots is shown throughout, so the multi-step flow is clear without extra copy.
Three things here are enrollment requirements, not styling choices:
- No zero. Auraya's design guide asks for random digits to avoid
0, because English speakers say it as "zero", "oh", "naught" or "nil" and biometrics works better when phonemes are consistent. Its own random-phrase standard is a permutation of123456789. Speech recognition also runs in front of the engine's quality gate, so "oh" against an expected "zero" is a phrase mismatch rather than a near miss. - Fixed prompts, not random ones. "Random prompting is only required at verification time." Presenting every user the same sequences is what makes cross-user calibration accurate, and calibration is what sets the acceptance threshold. The published set is chosen so the sequences contain no duplicate two-digit contexts, because performance depends on the co-articulation between adjacent digits.
- Five takes. Four is the documented floor; the guide says to use more where possible and puts the number at five where it is specific. Supplying fewer than four does not fail — the gateway pads the request by duplicating a take — but the print then carries only the supplied takes' worth of acoustic variation, and the enrollment is returned with a warning.
| Input | Type | Default | Description |
| ----- | ---- | ------- | ----------- |
| takes | number | 5 | How many recordings to collect before emitting confirmRecording. Prompts are drawn in order from ENROLMENT_DIGIT_SEQUENCES (eight available, wrapping beyond that). Lowering it below four produces a weaker print and a warned enrollment. |
| 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 } | A single recording finished (WebM audio + the spoken phrase), before confirmation. Fires once per take. |
| confirmRecording | { files: File[]; phrases: string[] } | All takes confirmed. Upload them together as one enrollment. |
phrases are positional: phrases[i] is what was spoken in files[i], spelled out in words (e.g. "one two three ..."). Each take gets its own sequence from the fixed set.
Breaking change in 1.3.0:
confirmRecordingpreviously emitted a single{ file, phrase }. It now emits every take at once as{ files, phrases }. A consumer that only needs one recording can set[takes]="1"and readfiles[0]/phrases[0]— but see the enrollment requirements above before doing so.
<bio-face-recorder>
Records a liveness video in which the user reads a digit challenge aloud. Produces a WebM video 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). |
| emitAudio | boolean | false | Also record a separate audio track and emit it as audio. Off by default — see below. |
| Output | Payload | Description |
| ------ | ------- | ----------- |
| recorded | { file: File; audio?: File; phrase: string } | Recording finished, before confirmation. audio is present only when emitAudio is set. |
| confirmRecording | { file: File; audio?: File; phrase: string } | User confirmed the recording. |
Changed in 1.8.0 (BM-446): the separate
audiofile is no longer produced by default andaudiois now optional. The blob was byte-identical to the video's own audio track — RecordRTC gives both encoders the sameMediaStreamTrack— so it was a second Opus encode of the same samples for a file nothing read. Uploadfile; the backend extracts the voice from the video it already verified for liveness. Set[emitAudio]="true"to restore the old behaviour.
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-componentsTo try a change in a browser, including on a phone, run the demo app: see
example/README.md.
Publishing
Publish from dist/, not from the repo root. ng build writes a complete,
self-contained package there — including a generated package.json with the
exports map and root-relative fesm2022/ paths. The root package.json is the
source manifest: publishing it would ship the source tree with a main pointing
at a directory that does not exist at that level.
# 1. bump the version in the ROOT package.json (ng-packagr copies it into dist/)
npm version minor --no-git-tag-version # e.g. 1.7.0 → 1.8.0
# 2. build, then publish the built package
npm run build
cd dist && npm publishCheck before you publish — dist/ should be the smaller of the two:
cd dist && npm pack --dry-run # ~24 files
npm pack --dry-run # ~51 files — the source tree, wrongThe file count should match what is already on npm:
npm view biometry-angular-components dist.fileCountThe
prepublishOnlyhook on the rootpackage.jsononly fires when publishing from the root, which is the case to avoid — so runnpm run buildyourself. A published version number can never be reused, so publish from a cleanmainafter the PR has merged.
License
MIT
