face-track

Real-time face detection and 68-point landmark tracking using TensorFlow.js. Ships with pre-trained model weights — no external downloads needed.

Install

npm install face-track @tensorflow/tfjs

@tensorflow/tfjs is a peer dependency.

Usage

import * as tf from '@tensorflow/tfjs'
import { FaceTracker, calculateFaceOrientation, drawResults } from 'face-track'

const tracker = new FaceTracker()
await tracker.loadModels('/models/')

// Detect faces + landmarks from a video element
const results = await tracker.detectFacesWithLandmarks(videoElement)

for (const { detection, landmarks } of results) {
  console.log('Box:', detection.box)        // { x, y, width, height }
  console.log('Landmarks:', landmarks)       // 68 points with { x, y }

  const orientation = calculateFaceOrientation(landmarks)
  console.log('Yaw/Pitch/Roll:', orientation) // { yaw, pitch, roll } in degrees
}

// Draw results on a canvas
const ctx = canvas.getContext('2d')
drawResults(ctx, results, canvas.width, canvas.height)

API

| Export | Description | |---|---| | FaceTracker | High-level class: load models, detect faces + landmarks | | calculateFaceOrientation(landmarks) | Estimate yaw/pitch/roll from 68 landmarks | | drawResults(ctx, results, w, h) | Draw bounding boxes + landmarks on canvas | | drawLandmarkPoints(ctx, landmarks) | Draw landmark dots | | drawLandmarkConnections(ctx, landmarks) | Draw landmark group connections | | FACE_LANDMARKS | Named index groups (JAW, LEFT_EYE, NOSE_TIP, etc.) | | TinyFaceDetector | Low-level face detection network | | FaceLandmark68Net | Low-level landmark network | | postProcessLandmarks(raw, box, w, h) | Convert raw network output to pixel coordinates |

Models

Pre-trained weights are in the models/ directory. Pass the serving URL to loadModels():

// Serve models from your public directory
await tracker.loadModels('/models/')

// Or from a CDN/custom path
await tracker.loadModels('https://cdn.example.com/face-track-models/')

Demo

See examples/react-demo/ for a working React app:

cd examples/react-demo
npm install
npm run dev

License

MIT