From da28a20f091372375822f9dde4486ecade859e7e Mon Sep 17 00:00:00 2001
From: Ken D'Ambrosio <ken@jots.org>
Date: Mon, 8 Jun 2026 17:09:51 +0000
Subject: Add opt-in facial recognition: detection and embedding storage

- scripts/faces.py: Python helper using face_recognition (dlib/HOG) to
  detect faces and return 128-D encodings as JSON; called by update.rb
- scripts/update.rb: enrich_faces() stores face boxes and encodings in
  album.json per image (null = not yet processed, [] = processed/none found);
  skips files already processed; gated on faces.enabled in config.yml
- Reads CONFIG_PATH (same env var as app.rb) to check faces.enabled flag
- Feature is off by default; enabled in this install via config.yml
- README.md, DESIGN.md: document installation, opt-in config, data model,
  and planned clustering/people-management pipeline

People management UI and clustering script are the next milestone.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index adc19a6..8167c0b 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,11 @@ back end, plain HTML/CSS/JS front end.  Live at **https://albumen.jots.org**.
 - **Run Update** button scans for new/removed files and generates missing thumbnails;
   **Force rescan all** checkbox bypasses the sentinel and rescans every directory
 
+### Facial recognition (opt-in)
+- Detects faces in photos and stores 128-D embeddings alongside each image
+- Powered by [face_recognition](https://github.com/ageitgey/face_recognition) (dlib/HOG, CPU-only)
+- People management and browse-by-person UI in progress
+
 ### Media support
 
 | Category | Extensions |
@@ -169,6 +174,39 @@ The PBKDF2-SHA256 hash is stored in `/opt/albumen/config.yml` (readable only by
 
 ---
 
+## Facial recognition setup
+
+Face detection is opt-in. Install once, then enable in `config.yml`.
+
+### 1. Install Python dependencies (server, ~30 min first time)
+
+```bash
+apt install python3-pip python3-dev python3-venv cmake build-essential libopenblas-dev liblapack-dev
+python3 -m venv /opt/albumen/venv
+/opt/albumen/venv/bin/pip install face_recognition
+```
+
+### 2. Enable in config.yml
+
+Add to `/opt/albumen/config.yml`:
+
+```yaml
+faces:
+  enabled: true
+```
+
+### 3. Run the update script
+
+```bash
+ruby /opt/albumen/scripts/update.rb
+```
+
+The update script will now detect faces in images and store bounding boxes and
+embeddings in each album's `album.json`. This is a one-time cost per image;
+subsequent runs skip already-processed photos.
+
+---
+
 ## Service management
 
 ```bash
-- 
cgit v1.2.3