shinobi-face-api

AI-powered Face Detection & Rotation Tracking, Face Description & Recognition, Age & Gender & Emotion Prediction for Node.js using TensorFlow.js

This is the Shinobi Systems maintained fork of FaceAPI.

• Based on @vladmandic/face-api 1.7.15 (TF.js 4.x modernization)
• Originally from justadudewhohacks/face-api.js 0.22.2

Why this fork?

The original face-api.js is pinned to TensorFlow.js 1.7 and is no longer maintained.
@vladmandic/face-api modernized it for TF.js 2–4 but is now archived.
Recursive Labs continues maintenance for browser and Node.js under @recursivelabs/face-api. This is a fork of the Recursive Labs version.

Features

• Face detection (TinyFaceDetector, SSD MobileNet v1)
• 68-point face landmarks (+ tiny variant)
• Face recognition descriptors & matching
• Expression recognition
• Age estimation & gender recognition
• Face angle (roll, yaw, pitch)
• Browser backends: WebGL, CPU, WASM, WebGPU
• Node backends: tfjs-node, tfjs-node-gpu, WASM

Install

npm install git+https://gitlab.com/Shinobi-Systems/face-api-js

Node.js

npm install git+https://gitlab.com/Shinobi-Systems/face-api-js @tensorflow/tfjs-node canvas

const tf = require('@tensorflow/tfjs-node');
const faceapi = require('shinobi-face-api');
const canvas = require('canvas');

const { Canvas, Image, ImageData } = canvas;
faceapi.env.monkeyPatch({ Canvas, Image, ImageData });

For GPU: use @tensorflow/tfjs-node-gpu and dist/face-api.node-gpu.js.
For WASM-only Node: use @tensorflow/tfjs + @tensorflow/tfjs-backend-wasm and dist/face-api.node-wasm.js.

Models

Pretrained weights live in ./model:

| Model | Purpose | |-------|---------| | tiny_face_detector_model | Fast face detection | | ssd_mobilenetv1_model | Higher-accuracy face detection | | face_landmark_68_model | 68 facial landmarks | | face_landmark_68_tiny_model | Smaller landmark model | | face_recognition_model | 128-d face descriptors | | face_expression_model | Expressions | | age_gender_model | Age & gender |

Load example:

await faceapi.nets.tinyFaceDetector.loadFromUri('/model');
await faceapi.nets.faceLandmark68Net.loadFromUri('/model');
await faceapi.nets.faceRecognitionNet.loadFromUri('/model');

const results = await faceapi
  .detectAllFaces(input, new faceapi.TinyFaceDetectorOptions())
  .withFaceLandmarks()
  .withFaceDescriptors();

In Node, prefer loadFromDisk:

await faceapi.nets.tinyFaceDetector.loadFromDisk('./model');

Bundle formats

| File | Format | TF.js bundled? | Target | |------|--------|----------------|--------| | dist/face-api.node.js | CJS | no | Node + tfjs-node | | dist/face-api.node-gpu.js | CJS | no | Node + tfjs-node-gpu | | dist/face-api.node-wasm.js | CJS | no | Node + WASM backend |

Package entry points:

• main → dist/face-api.node.js
• types → types/face-api.d.ts

See TUTORIAL.md for the full API walkthrough.

Develop / build

Requires Node.js 20–22 for develop/build and native @tensorflow/tfjs-node. TF.js native bindings are not compatible with Node 23+. On newer Node, use the WASM build (dist/face-api.node-wasm.js).

npm install
npm run build   # production bundles + typings
npm run lint
npm test        # Node smoke tests (needs native deps for full run)

## Breaking changes vs original face-api.js 0.22.2

- Compatible with **TensorFlow.js 4.x** (not 1.7)
- Package name: `shinobi-face-api` (was `@recursivelabs/face-api`)
- Model path: `./model` (was `./weights`); weight shards are consolidated `.bin` files
- **MTCNN removed** (non-functional in modern TF.js)
- ESM + CJS + IIFE platform builds (not a single UMD-only dist)
- TypeScript targets modern ES; types ship in `types/`
- Node engine: ≥ 18

## Credits

- Original project: [face-api.js](https://github.com/justadudewhohacks/face-api.js) by Vincent Mühler
- TF.js modernization: [vladmandic/face-api](https://github.com/vladmandic/face-api) by Vladimir Mandic
- Continued maintenance: [Recursive Labs](https://github.com/RecursiveLabsInc)
- This Fork : [shinobi-face-api](https://gitlab.com/Shinobi-Systems/face-api-js)

## License

MIT — see [LICENSE](./LICENSE)