go-liveness

weights, ONNX Runtime binaries, or biometric samples. go-liveness runs the Vision Transformer passive-liveness model documented by Adedev-W/LivenessModels-ONNX from Go. Image processing is pure Go, and ONNX Runtime is loaded dynamically through onnxruntime-purego, so application builds do not require CGO or OpenCV.

The library classifies a caller-supplied face crop. It deliberately does not detect or align faces, download assets at runtime, or bundle the 327.5 MB model.

Install

go get github.com/lib-x/go-liveness

Download an ONNX Runtime 1.23.x shared library from the official releases and the model linked by the reference repository.

Use

package main

import (
	"context"
	"image/jpeg"
	"log"
	"os"

	liveness "github.com/lib-x/go-liveness"
)

func main() {
	file, err := os.Open("face.jpg")
	if err != nil {
		log.Fatal(err)
	}
	defer file.Close()
	face, err := jpeg.Decode(file)
	if err != nil {
		log.Fatal(err)
	}

	engine, err := liveness.New(liveness.Config{
		RuntimeLibrary: "/opt/onnxruntime/lib/libonnxruntime.so.1.23.2",
		Model:          "/opt/models/liveness_vit_with_meta.onnx",
	})
	if err != nil {
		log.Fatal(err)
	}
	defer engine.Close()

	result, err := engine.Evaluate(context.Background(), face)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("class=%s raw_scores=%v raw_confidence=%f", result.Class, result.Scores, result.Confidence)
}

Evaluate resizes to 224x224, reads RGB, rescales by 1/255, normalizes with mean/std 0.5, and sends NCHW [1,3,224,224] float32 data to the model. It uses the upstream decision rule: class 0 (real) wins when its raw score is greater than or equal to class 1 (spoof). Result.Confidence is the winning raw model output, not a probability or a calibrated security score.

Engine.Evaluate is safe for concurrent use. Close is idempotent and waits for in-flight calls before releasing the native runtime.

Verification

go test ./...
go test -race ./...
go vet ./...
CGO_ENABLED=0 go build ./...

Real-model validation keeps large and potentially sensitive assets external:

ORT_LIBRARY=/path/to/libonnxruntime.so.1.23.2 \
LIVENESS_MODEL=/path/to/liveness_vit_with_meta.onnx \
LIVENESS_IMAGE=/path/to/cropped-face.jpg \
LIVENESS_EXPECTED_CLASS=real \
go test -tags=integration ./...

Set LIVENESS_EXPECTED_REAL_SCORE, LIVENESS_EXPECTED_SPOOF_SCORE, and optionally LIVENESS_SCORE_TOLERANCE to compare against recorded reference outputs as well as the expected class.

Security and licensing

Passive liveness is one signal, not proof of identity. Validate error rates, presentation-attack coverage, crops, and decision policy against the cameras and attacks in the actual deployment. Do not interpret raw logits as probabilities.

This repository's code is MIT licensed. The reference repository also carries an MIT license, but its model is hosted separately on Google Drive and does not state separate model provenance or commercial-use terms. Verify the model's rights before redistribution or production use. This module contains no model weights, ONNX Runtime binaries, or biometric samples.