@face-auth/face-id-video-guidelines

Visual face-alignment guides for browser video streams. Current package version: 0.0.5.

Installation

npm install @face-auth/face-id-video-guidelines

Public Exports

• FaceGuidelines
• GuidelinesOptions
• OvalDimensions

Quick Start

import { FaceGuidelines } from "@face-auth/face-id-video-guidelines";

const video = document.getElementById("videoRef") as HTMLVideoElement;
const guidelines = new FaceGuidelines(video);

navigator.mediaDevices.getUserMedia({ video: true }).then((stream) => {
  video.srcObject = stream;
  video.onloadedmetadata = () => {
    video.play();
    guidelines.start();
  };
});

FaceGuidelines

Creates and manages a canvas overlay synchronized with an existing HTMLVideoElement.

import { FaceGuidelines } from "@face-auth/face-id-video-guidelines";

const guidelines = new FaceGuidelines(videoElement, {
  oval: {
    line: {
      strokeStyle: "#22C55E",
    },
  },
});

Constructor

• new FaceGuidelines(videoElement: HTMLVideoElement, options?: GuidelinesOptions)

Methods

• start(): void
• stop(): void
• updateOptions(partialOptions: GuidelinesOptions): void
• getOvalDimensions(): OvalDimensions
• destroy(): void

Behavior summary

• start() begins the render loop and is safe to call again.
• stop() stops rendering and clears the current overlay.
• updateOptions(...) deep-merges partial changes into previous options.
• destroy() stops rendering, disconnects overlay syncing, and removes the overlay canvas from the DOM.

GuidelinesOptions

export interface GuidelinesOptions {
  text?: {
    drawText?: boolean | null;
    text?: string | null;
    textColor?: string | null;
    font?: string | null;
    x?: number | null;
    y?: number | null;
  };
  oval?: {
    size?: {
      x?: number | null;
      y?: number | null;
      radiusX?: number | null;
      radiusY?: number | null;
      scale?: number | null;
    };
    line?: {
      drawLine?: boolean | null;
      strokeStyle?: string | null;
      lineWidth?: number | null;
      lineDash?: number[] | null;
      lineDashOffset?: number | null;
      lineCap?: CanvasLineCap | null;
      lineJoin?: CanvasLineJoin | null;
      opacity?: number | null;
    };
    overlay?: {
      drawOverlay?: boolean | null;
      color?: string | null;
    };
  };
}

Defaults

Text

| Option | Default | | --- | --- | | text.drawText | false | | text.text | "Align your face" | | text.textColor | "#FFFFFF" | | text.font | "30px Arial" | | text.x | videoWidth / 2 | | text.y | videoHeight - 50 |

Oval

| Option | Default | | --- | --- | | oval.size.x | videoWidth / 2 | | oval.size.y | videoHeight / 2 - 20 | | oval.size.radiusX | 120 | | oval.size.radiusY | 160 | | oval.size.scale | 1 |

Line

| Option | Default | | --- | --- | | oval.line.drawLine | true | | oval.line.strokeStyle | "#FFFFFF" | | oval.line.lineWidth | 4 | | oval.line.lineDash | [10, 15] | | oval.line.lineDashOffset | 0 | | oval.line.lineCap | "round" | | oval.line.lineJoin | "round" | | oval.line.opacity | 0.8 |

Overlay

| Option | Default | | --- | --- | | oval.overlay.drawOverlay | true | | oval.overlay.color | "rgba(0, 0, 0, 0.35)" |

Runtime Update Semantics

updateOptions(...) is intended for visual changes driven by parent state.

• Partial updates preserve previous values for omitted fields.
• Values are sanitized before rendering.
• If the loop is active, changes are rendered immediately.
• If the loop is stopped, changes are applied on the next start().

Example:

guidelines.updateOptions({
  oval: {
    line: {
      strokeStyle: "#3B82F6",
      lineDash: [],
    },
  },
  text: {
    drawText: true,
    text: "Center your face",
  },
});

OvalDimensions

getOvalDimensions() returns:

{
  x: number;
  y: number;
  radiusX: number;
  radiusY: number;
  scale: number;
}

Browser Support

• Browser runtime only.
• Requires an existing HTMLVideoElement.
• For the first accurate render, call start() after video metadata is loaded.