FaceX

Full face pipeline — detect, mesh, recognize, anti-spoof — in pure WebAssembly. Trained from scratch. No cloud, no Python, no server.

License: Apache 2.0 LFW Latency Browser Encryption Deps

Full face stack that runs entirely in the browser. Detection, 98-point landmarks, dense 3D mesh, recognition, and passive anti-spoof — all WebAssembly, zero server, ~17 MB of encrypted weights.

🎬 Live Demo → — open in a Chromium browser, press Start camera, try all modes. 📚 Docs in Wiki → — Browser quickstart, training recipes, nn2 architecture, encrypted weights, comparison vs alternatives.

FaceX pipeline

Weights ship as AES-256-GCM ciphertext and are decrypted in the browser via WebCrypto. This is not DRM — a determined attacker can dump the decrypted bytes from the WASM heap. What it does buy you: friction against casual scraping, per-customer key revocation for SaaS deployments, and an audit trail at the key-issuing endpoint. See the wiki for the threat model and Express / FastAPI integration recipes.

FaceX is one piece of a larger pure-C stack we built for IP-camera workloads. Every component is hand-written, zero-dependency, flashable to firmware:

Pipeline numbers (one Intel i5 CPU):

• Decode 30 RTSP streams + run YOLO detection on each: 0.56 ms/frame average → 70 IP cameras on one CPU core with motion-gating + Kalman tracking.
• Tiered storage: 70 cams ×ばつ 90 days = 49 TB → 3.3 TB (×ばつ savings) with NXV + selective bitstream-only archiving.

Why it matters:

• Flashable — entire NVR stack fits in <2 MB of binary, ARM/x86/RISC-V, no shared libraries
• No FFmpeg — no GPL contamination, no surface for codec CVEs, no 28 MB of libav .so files
• Embedded-ready — runs on 30ドル SoCs (Allwinner, Rockchip, NXP i.MX), 25 cameras on 27% CPU
• Standalone — every piece can be used alone or combined: decoder → motion gate → detector → tracker → recognizer → archive

We're not just "x86 only". The same code targets multiple device classes:

Decoder + encoder are pure C99 with x86 SIMD today; ARM/NEON backports for NexusDecode are next.

// Native C: 3 ms per face
#include "facex.h"
FaceX* fx = facex_init("facex_xs.bin", NULL);
float emb[512];
facex_embed(fx, face_112x112, emb);
float sim = facex_similarity(emb_a, emb_b); // >0.3 = same person

# Or run the live browser demo locally
git clone https://github.com/facex-engine/facex
cd facex/wasm && python -m http.server 8000
# open http://127.0.0.1:8000/demo_mesh.html

• Identity verification (KYC) — "is this the same person?" from selfie + ID photo, no cloud round-trip
• Face login — unlock apps by face, works offline, no data leaves the device
• Access control — doors, gates, turnstiles on edge hardware without GPU
• Proctoring — verify exam takers are who they claim to be
• Smart cameras — recognize known faces at 300+ faces/sec on a single CPU core
• Banking / fintech onboarding — passive liveness + face match in the browser, GDPR-friendly by construction
• In-store kiosks — VIP/loyalty recognition at the till, runs on a 30ドル SoC

You're typically choosing between AWS Rekognition / Azure Face / Google Vision / Paravision / FaceTec ZoOm. Cost comparison for a 100 K-user app doing one face-match per session per day:

The savings are nice. The bigger story is compliance: when frames never leave the device, you're outside GDPR Art. 9 (biometric) / HIPAA / Russia's 152-ФЗ / KZ's data localization rules by construction. No DPIA, no DPA renegotiations, no "where are the photos stored" audit questions.

We've shipped this stack into IP-camera NVRs, retail kiosks, and KYC flows for fintech clients. If you're evaluating it for production, the live demo is the fastest way to see what it can do — then open an issue or email me with your use case and I'll help you scope.

Full pipeline, every step trained or written by us:

1. Detect — own FCOS-style face detector (100K params, trained from scratch on WIDER FACE; 401 KB ONNX).
2. Align — 98-point WFLW landmark ConvNet (1.15M params; 1.1 MB ONNX).
3. 3D mesh — 576-point face mesh (5.6 MB ONNX), distilled from MediaPipe FaceMesh with our 98 WFLW anchors driving the warp.
4. Recognize — MobileFaceNet + ArcFace, four size variants (nano 0.8 MB · tiny 1.8 MB · standard 3.9 MB · xs 8.4 MB), LFW 95.6 → 99.07%.
5. Anti-spoof — MiniFASNet ensemble (V2 @ 2.7 + V1SE @ 4.0), MinivisionAI Apache 2.0. Also ported to our nn2 engine — ×ばつ faster than ONNX Runtime on the same CPU.

Two modes:

• Browser: onnxruntime-web + AES-256-GCM encrypted weights, full pipeline in ~25 ms/frame, no server.
• Native: pure C, 3 ms per face, INT8 + AVX-512, beats ONNX Runtime on the same hardware.

Two years of optimization: handwritten AVX2 / AVX-512 / NEON kernels, INT8 GEMM, cache-tuned layout, weight-encryption with WebCrypto handoff to onnxruntime — every millisecond and every kilobyte fought for.

Measured on Intel i5-11500 (6 cores, AVX-512 + VNNI):

Speed comparison

Same model, ported to our nn2 C engine (Apache 2.0, source in nn2/):

Byte-identical predictions to PyTorch / ONNX on the same input.

All numbers are the mean accuracy across 10-fold cross-validation (InsightFace-style: tune the threshold on 9 training folds, evaluate on the 1 held-out fold, repeat 10 times). The ± column is the standard deviation across folds. Input must be ×ばつ112 ArcFace-aligned via a 5-point similarity transform — running on un-aligned crops drops accuracy by ~25 points. The eval script is training/scripts/lfw_eval.py.

Our YuNet-style FCOS detector, 100 K params, trained from scratch:

Footprint comparison

#include "facex.h"
int main() {
 // Load engine (one-time, ~100ms)
 FaceX* fx = facex_init("facex_xs.bin", NULL);
 // Compute embedding (3ms per call)
 float face[112 * 112 * 3]; // RGB, HWC, [-1, 1]
 float embedding[512];
 facex_embed(fx, face, embedding);
 // Compare two faces
 float sim = facex_similarity(emb_a, emb_b);
 // sim > 0.3 → same person
 facex_free(fx);
}

gcc -O3 -march=native -Iinclude -o myapp myapp.c -L. -lfacex -lm -lpthread

import "github.com/facex-engine/facex/go/facex"
ff, _ := facex.New(facex.Config{
 Exe: "./facex-cli",
 Weights: "./facex_xs.bin",
})
defer ff.Close()
embedding, _ := ff.Embed(rgbImage)
sim := facex.CosSim(embA, embB)

# Pipe mode: reads 112x112x3 float32 HWC, writes 512 float32
./facex-cli weights.bin --server < faces.raw > embeddings.raw

<script src="https://cdn.jsdelivr.net/npm/onnxruntime-web@1.21.0/dist/ort.min.js"></script>
<script>
 // Fetch encrypted weights, decrypt in WebCrypto, hand bytes to ORT.
 const buf = new Uint8Array(await (await fetch('facex_xs.enc')).arrayBuffer());
 const iv = buf.subarray(0, 12), data = buf.subarray(12);
 const key = await crypto.subtle.importKey('raw', KEY_BYTES,
 {name:'AES-GCM'}, false, ['decrypt']);
 const onnx = new Uint8Array(await crypto.subtle.decrypt({name:'AES-GCM', iv}, key, data));
 const sess = await ort.InferenceSession.create(onnx, { executionProviders: ['wasm'] });
 // Inference is 100% client-side. Frames never leave the device.
</script>

Full browser pipeline (detect + 576pt mesh + recognize + anti-spoof) is live at https://facex-engine.github.io/facex/demo/ — open it, press Start camera, try the picker.

make # builds libfacex.a + facex-cli
make example # builds and runs example
make encrypt # builds weight encryption tool

Requirements: GCC with AVX2 support. Nothing else.

gcc -O3 -march=x86-64-v3 -mavx2 -mfma -static \
 -DFACEX_LIB -o libfacex.a src/*.c -lm -lpthread

// Initialize engine. Returns NULL on error.
// license_key: NULL for plain weights, or key string for AES-256 encrypted.
FaceX* facex_init(const char* weights_path, const char* license_key);
// Compute 512-dim face embedding from 112x112 RGB image.
// rgb_hwc: float32 array [112][112][3], values in [-1, 1].
// embedding: output buffer, 512 floats (L2-normalized).
int facex_embed(FaceX* fx, const float* rgb_hwc, float embedding[512]);
// Cosine similarity between two embeddings. Range [-1, 1].
float facex_similarity(const float emb1[512], const float emb2[512]);
// Free engine resources.
void facex_free(FaceX* fx);
// Version string.
const char* facex_version(void);

Input: ×ばつ112 RGB float32 in [-1, 1]
 ↓
 Stem: Conv ×ばつ3 s=2 → 64 ch, PReLU
 ↓
 DW Stem: DW ×ばつ3 s=1 → 64 ch, PReLU
 ↓
 Stage 1: ×ばつ Inverted-Residual (t=2, c=64, first s=2)
 ↓
 Stage 2: ×ばつ Inverted-Residual (t=4, c=128, s=2)
 ↓
 Stage 3: ×ばつ Inverted-Residual (t=2, c=128, s=1)
 ↓
 Stage 4: ×ばつ Inverted-Residual (t=4, c=128, s=2)
 ↓
 Stage 5: ×ばつ Inverted-Residual (t=2, c=128, s=1)
 ↓
 Conv ×ばつ1 → 512 ch, PReLU
 ↓
 GDConv DW ×ばつ7 s=1 (linear-GDC) → ×ばつ1
 ↓
 ×ばつ1 conv → 512-d embedding, BN, L2-norm
 ↓
Output: 512-dim unit embedding

Engine internals:

• Pure C99 + SIMD intrinsics (AVX2, FMA, AVX-512, VNNI)
• INT8 quantized GEMM with vpmaddubsw (AVX2) / vpdpbusd (VNNI)
• FP32 packed column-panel MatMul (NR = 8 AVX2, NR = 16 AVX-512)
• Custom thread pool with work-stealing (WaitOnAddress / futex)
• Pre-packed weights at load time for cache-optimal access
• BN folded into preceding Conv at export time
• AES-256-GCM weight encryption with WebCrypto handoff in the browser, AES-256-CTR with hardware binding for native deployments
• Fully shared op library between recognition, anti-spoof (MiniFASNet), and YOLOv8 detection (nn2)

For commercial deployment with IP protection:

# Encrypt weights (binds to target machine hardware)
./facex-encrypt encrypt weights.bin weights.enc "LICENSE-KEY"
# Load encrypted weights
FaceX* fx = facex_init("weights.enc", "LICENSE-KEY");

Wrong key or different machine → load fails. Original weights never touch disk in plaintext on the target machine.

• Native build — currently x86-64 (AVX2 / AVX-512 / VNNI). ARM NEON paths exist in nn2/src/gemm_neon.h; full ARM build script is on the roadmap, ESP32 / RISC-V PIE 128 next.
• Browser pipeline — uses onnxruntime-web with WebCrypto-decrypted ONNX. WebGPU backend is supported by ORT but not yet wired into the demo; would drop inference by another ×ばつ.
• Anti-spoof is the only non-our component (MiniFASNet, Apache 2.0, MinivisionAI). Training a fully-own anti-spoof needs a commercial attack dataset, which we don't have.

Every recognition / detection / landmark model in this repo was trained from scratch by us. Anti-spoof is the only third-party piece.

Standard MobileFaceNet (Chen et al. 2018) topology, width-scaled to four sizes, ArcFace head with the numerically-stable angle-addition margin, trained on MS1M-RefineV2 with bf16 autocast.

YuNet-inspired, but FCOS-style anchor-free. MobileNetV2-lite backbone, 3 detection heads at strides 8 / 16 / 32, GIoU bbox loss + focal cls loss. 100 K params, 401 KB ONNX. Trained on WIDER FACE.

MobileFaceNet-style backbone + dense head, 1.15 M params. Final NME on WFLW val: 4.85% (test) / 5.95% (large-pose subset).

Same architecture as the 98-point model, but with Linear(256, 478*3) head — distilled from MediaPipe FaceMesh pseudo-labels with TPS-rendered supervision over our WFLW frontalised crops. Error: xy 0.54 px, z 0.51 (normalized) on held-out val. With 98 WFLW anchors driving the non-rigid warp, the rendered mesh has 576 visible points total.

We don't train this — there's no commercial-friendly attack dataset publicly available. We port their two-model ensemble (V2 @ 2.7 + V1SE @ 4.0) into our nn2 inference engine and ship byte-identical predictions at ×ばつ speed vs ONNX Runtime.

include/ — public C API (facex.h, facex_mfn.h, ...)
src/ — recognition engine + AES weight crypto
nn2/ — pure-C YOLO + MiniFASNet inference engine
 (×ばつ ONNX, Apache 2.0)
 src/ — gemm, conv, ops, antispoof_ops, minifasnet
 include/ — public API headers
 tools/ — PyTorch → .bin converters
wasm/ — browser demo (demo_mesh.html, encrypt tool)
 tools/encrypt_models.py — AES-256-GCM encrypt all .onnx
docs/demo/ — GitHub Pages live demo + encrypted weights
training/ — all training pipelines, datasets, exporters
 scripts/ — MobileFaceNet recognition (nano/tiny/standard/xs)
 landmark/ — 98-point WFLW
 landmark3d/ — 576-point MediaPipe distillation
 face_detect/ — own FCOS face detector trained on WIDER FACE
 antispoof/ — MiniFASNet integration
go/facex/ — Go binding (subprocess protocol)
python/facex/ — Python binding (ctypes)

Q: Is it really faster than ONNX Runtime? A: Yes. Measured on the same CPU, same model, same input. FaceX median 3.0 ms vs ONNX Runtime median 3.9 ms. The gap comes from handwritten SIMD kernels that avoid framework overhead.

Q: What accuracy vs ArcFace-R100? A: Our xs (2 M params) is 99.07% LFW vs ArcFace-R100's 99.80%. 0.7% of recall for ×ばつ smaller model and ×ばつ faster inference.

Q: Can I use this commercially? A: Engine code is Apache 2.0. Our trained recognition, detection, landmark, and 3D-mesh weights are also Apache 2.0 — we own them. Only the anti-spoof component (MiniFASNet) is upstream Apache 2.0.

Q: Does it do face detection? A: Yes. We trained an own FCOS-style detector on WIDER FACE; it replaces YuNet in the browser demo and runs in <1 ms.

Q: Why ONNX in the browser instead of native WASM? A: We went both ways. nn2 ships a native C engine that is ×ばつ faster than ORT. For the browser, onnxruntime-web gives us WebGPU, SIMD-WASM, and 3-line model swap without re-compiling. The encryption layer (WebCrypto → ORT byte stream) sits between the network and ORT, so the model bytes never hit the page as plaintext.

@software{facex2026,
 author = {Atinov, Baurzhan},
 title = {FaceX: Fast CPU Face Embedding Library},
 year = {2026},
 url = {https://github.com/facex-engine/facex}
}

Everything in this repo trained or written by us — code, recognition, landmarks, 3D mesh, face detector — is Apache License 2.0. Free for commercial use, attribution appreciated.

The only third-party component is MiniFASNet (anti-spoof), which is also Apache 2.0 from MinivisionAI Silent-Face-Anti-Spoofing.

For commercial licensing: bauratynov@gmail.com

Created by Baurzhan Atinov (Kazakhstan)
GitHub