REAL-TIME FACE RECOGNITION · v1.3.0

FaceHub

Get Started API Reference

0dim embeddings

0real-time pipeline

0cross-platform

0open source

FaceHub is a real-time face recognition Python library. It provides a clean, GUI-free package for detection, embedding extraction, recognition, tracking, camera capture — and grouping whole photo collections by face.

Features

◎

Detection

insightface RetinaFace with GPU auto-detection (CUDA / DirectML) and CPU fallback.

⬡

Embedding

ArcFace 512-dim L2-normalized features, ready for cosine-similarity matching.

⇄

Recognition

1:N matching with a versioned encoding cache — rebuilt only when the gallery changes.

⋈

Tracking

IoU multi-face tracker with majority-vote identity smoothing.

▦

Photo Classification

Group photo collections by face — gallery matching or automatic clustering, with per-person folder export.

⌘

Extensible

DetectorProtocol lets you plug in your own detector (YOLO, MediaPipe, …).

60-Second Quick Start

zsh — pip

pip install face-hub

from face_hub import classify_photos, export_to_folders

# Group a folder of photos by the people in them
result = classify_photos(["party1.jpg", "party2.jpg", "party3.jpg"])

for label, group in result.groups.items():
    print(label, "→", group.photo_ids)
# person_001 → ['party1.jpg', 'party3.jpg']
# person_002 → ['party2.jpg']

# Export into per-person folders
export_to_folders(result, "sorted/")

Platform Support

Platform	Inference Backend	Notes
Windows	DirectML / CUDA / CPU	Auto-detect, prefers GPU
Linux	CUDA / CPU	Auto-detect, prefers GPU
macOS	CPU	CPU only; CoreML planned

Next Steps

Installation Quick Start Photo Classifier API Reference