Skip to content
BranchesTags

Repository files navigation

FacePlugin

🌐 Company Site - Here

🤗 Hugging Face - Here

🛟 Help Center - Here

🐳 Docker Hub - Here

Face Liveness SDK — Linux / Docker (Fully On-Premise)

Introduction

FacePlugin Face Liveness SDK detects presentation attacks (photo, screen, print, replay) from a single RGB face image.

This repository is standalone. Pull Docker Hub (no Drive) or download the runtime into this repo and run — no other FacePlugin repository is required.

This is an on-premise SDK. All processing stays on your server — no biometric data is sent to FacePlugin cloud.

One repository for Linux SDK + Docker. Native libraries are linux/amd64. The Docker image runs on Linux, Windows, and macOS hosts (Apple Silicon uses amd64 emulation).

Test with curl, Postman, or the local Gradio demo (demo.py).

Main functionalities

Feature Supported
RGB liveness (all engines combined) ✓
Photo / screen / print / replay PAD ✓
Score, Real/Spoof, pass ✓

Score ≥ 0.5 → result: "Real", pass: true. Score < 0.5 → result: "Spoof", pass: false.

Product list

Platform Repository
Android FaceLiveness-Android
iOS FaceLiveness-iOS
Windows FaceLiveness-Windows-App
Linux / Docker FaceLiveness-Linux-App
Flutter FaceLiveness-Flutter
React Native FaceLiveness-ReactNative
Python FaceLiveness-Python
C# FaceLiveness-CSharp

Before you start

Step What you need
1 A Linux host or Docker
2 Docker Hub pull does not require Google Drive downloads. Populate ./lib/cpu/ only for Compose or ./run.sh — see Download runtime libraries
3 You do not need a license to start the API for the first time. Simply launch it without a key, then locate the machine code ( FPMC1.…) in the logs or via GET /api/machinecode. Submit this code to FacePlugin(contact) to get activation key ( FP1.…) and unlock product endpoints.

System requirements

Item Minimum Recommended
CPU 2 cores 8 cores
RAM 4 GB 8 GB
Disk 4 GB 8 GB
OS Ubuntu 20.04+ (x86_64) Ubuntu 22.04 / 24.04

Start the API

You can start without a license — the server prints your machine code on startup.

The API starts even if activation fails. Copy the machine code (FPMC1.…) from the log and send it to FacePlugin.

Docker logs: machine code printed, activation failed, Flask API still listening

Option A — Docker Hub (no Drive download)

sudo docker pull faceplugin/face-liveness:latest
sudo docker run -d --name faceplugin-face-liveness \
  --shm-size=1gb --privileged \
  -p 8084:8084 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/face-liveness:latest
sudo docker logs -f faceplugin-face-liveness
# Look for the machine code line: FPMC1.…

Several containers, one license

On Linux, add -v /etc/machine-id:/etc/machine-id:ro to the docker run above so the machine code stays on that host. Then start another container with a new name and host port — same image, same FP1.… key:

sudo docker run -d --name faceplugin-face-liveness-2 \
  -p 8085:8084 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/face-liveness:latest

Activate on each host port with the same key. On Docker Desktop (macOS/Windows) skip the machine-id volume; each container may need its own license.

Download runtime libraries (lib folder)

Skip this if you used Docker Hub (docker pull / docker run). Runtime is already inside the image.

./lib/cpu/ is empty on GitHub because binaries are too large.

If you clone this repo and run locally or with Compose, download the runtime separately.

Where to download

FaceLiveness-Linux-App runtime (Google Drive)

How to place files

  1. Clone the repo:
git clone https://github.com/Faceplugin-ltd/FaceLiveness-Linux-App.git
cd FaceLiveness-Linux-App
  1. Download all files from the Drive folder.
  2. Put every file directly into ./lib/cpu/ — not inside a nested subfolder.
FaceLiveness-Linux-App/
└── lib/
    └── cpu/
        ├── libFaceLivenessSDK.so
        ├── libfal-eng.so
        ├── fal.fpk
        └── …
  1. Quick check:
ls lib/cpu/libFaceLivenessSDK.so
ls lib/cpu/fal.fpk

Option B — Docker Compose

Requires ./lib/cpu/ filled from Drive.

cd FaceLiveness-Linux-App
# macOS/Windows Docker Desktop: remove the /etc/machine-id volume from docker-compose.yml first
sudo docker compose up --build -d
sudo docker compose logs -f

Detached Compose has no TTY — activate with curl (below).

Option C — Native Linux (no Docker)

Requires ./lib/cpu/ filled from Drive.

cd FaceLiveness-Linux-App
./run.sh

API: http://127.0.0.1:8084

SDK license

Licenses are offline and bound to a machine code.

  1. Start the server (above). A license is not required for the first start.
  2. Copy the machine code from the log (FPMC1.…).
  3. Send that code to FacePlugin (contact). We issue a license key for that code.
  4. Activate:
# Paste the FP1. key into ./license.txt, then:
curl -s -X POST http://127.0.0.1:8084/api/activate \
 -H 'Content-Type: text/plain' \
 --data-binary @license.txt

POST /api/activate with license.txt — success true

Or stop the process, save license.txt, and run ./run.sh / docker compose restart again.

Docker and local host codes are different. Use the machine code from the environment you will run in production.

Try it

Health

curl -s http://127.0.0.1:8084/api/health

Liveness

curl -s -X POST http://127.0.0.1:8084/api/liveness \
 -H 'Content-Type: application/json' \
 -d '{"image":"<base64-jpeg>"}'

Success data:

{ "score": 0.72, "result": "Real", "pass": true }

Docs: https://doc.faceplugin.com

Postman

Import [postman/FaceLiveness-API.postman_collection.json](postman/FaceLiveness-API.postman_collection.json). Base URL: http://127.0.0.1:8084

Demo UI (Gradio) — local only

The Docker image is API-only (no Gradio). With the API already running on port 8084:

pip3 install -r requirements-demo.txt
DEMO_PORT=9004 API_BASE=http://127.0.0.1:8084 python3 demo.py

Open http://127.0.0.1:9004. Samples: assets/examples/samples/.

Face Liveness Gradio demo — Spoof result with score and Pass

Each run shows Score, Result (Real or Spoof), and Pass.

About SDK

Python bindings: [sdk.py](sdk.py). Return code 0 means success.

import sdk

machine_code = sdk.get_machine_code() # FPMC1.…
sdk.activate("license.txt")
sdk.init_sdk()
result = sdk.liveness(base64_image)

result is JSON. data is { "score": <float>, "result": "Real" | "Spoof", "pass": <bool> }. All RGB engines are always run and combined.

List of our Products

Contact

faceplugin.com  faceplugin.com

About

Liveness detection SDK Linux - iBeta level 2 compliant 3D passive liveness detection (face anti spoofing) engine which can detect printed photos, video replay, 3D masks, and deepfake threats

faceplugin.com/face-liveness-detection/

Topics

anti-spoofingbiometric-authenticationbiometric-identificationdeepfake-detectionface-anti-spoofingface-anti-spoofing-sdkface-liveness-detectionface-liveness-detection-pythonface-liveness-detection-sdkface-recognitionface-recognition-sdkliveness-detectionliveness-detection-sdkpassive-liveness-detection

Resources

Readme
Activity
Custom properties

Stars

86 stars

Watchers

5 watching

Forks

59 forks
Report repository

Releases

Packages

Used by

Contributors

Languages