Local Face Photos

A private, local-first photo and video library for finding memories by the people, albums, tags, and dates in them.

Local Face Photos scans folders on your own computer, detects faces with InsightFace, lets you tag people, and searches your library without uploading private photos to a cloud service.

This is an early open-source beta for technical users who are comfortable trying unsigned desktop builds or running a local Python app.

Download

The current public build is available from the GitHub release page:

• Download the latest tested macOS Apple Silicon beta
• Current release: v1.1.0-beta.4
• Current Apple Silicon DMG SHA-256: 2a81d9c02dd4e4084e5eeb9fe69de2f2e3e8d631259feb3ad1befeaed5608d45
• Experimental Intel Mac x64 builds can be generated from GitHub Actions, but they are community-test candidates until validated on real Intel hardware.

Important beta notes:

• The Apple Silicon DMG is the currently tested desktop build.
• The app is unsigned and not notarized yet. On macOS, you may need to right-click the app and choose Open the first time.
• First launch can take a minute while the local face engine starts.
• Large video scans can be slow, especially on CPU fallback.

Why This Exists

Google Photos and similar services are convenient, but they often push users toward paid cloud storage. Local Face Photos is an experiment in keeping the useful parts of photo search while keeping the actual media, face embeddings, tags, and index on your own machine.

Google Takeout can get your photos back onto your computer. The bigger question is: now what?

This project is one answer to that question.

Quick Start

Option A: Try With Demo Media

If you do not want to scan personal photos right away, download the provided synthetic demo media pack.

1. Download and unzip the demo media pack.
2. Launch Local Face Photos.
3. Click Choose Folder and select the demo media folder.
4. Set Scan to Both.
5. Enter an album name such as Demo Album.
6. Click Scan Path.
7. Tag a few detected faces with names like Aman, Preeti, Sahil, and Sofia.
8. Try searches like Aman, Aman, Preeti, Demo Album, birthday, or photos from 2022.

The demo media is synthetic and does not contain private family photos.

Option B: Scan Your Own Library

1. Download the DMG from the latest release.
2. Open the DMG and drag Local Face Photos to Applications.
3. Launch the app. If macOS blocks it because it is unsigned, right-click the app and choose Open.
4. Click Choose Folder and select a folder with photos or videos.
5. Choose whether to scan Photos, Videos, or Both.
6. Optionally enter an album name before scanning.
7. Tag a few detected faces, then search by name, album, date, or photo tag.

What It Can Do

• Scan local folders recursively for supported photos and videos.
• Detect faces locally with InsightFace buffalo_l.
• Tag people from cropped face thumbnails.
• Auto-propagate tags to matching untagged faces.
• Cluster repeated faces in videos so one person is not shown dozens of times.
• Search by one person, multiple people, albums, or descriptive photo tags.
• Filter by media type, year, month, date, and sort direction.
• Add albums during scan, or later per photo/video.
• Hide videos with no visible/taggable faces by default.
• Ignore/remove noisy face boxes so they stay hidden on future scans.
• Store the index locally in SQLite.

Privacy Model

Local Face Photos does not upload photos, videos, embeddings, tags, or metadata to a cloud service. The desktop app starts a local backend on your computer, reads the folders you choose, runs face detection locally, and stores the generated index locally.

Packaged desktop builds store generated app data outside the source folder:

• macOS: ~/Library/Application Support/Local Face Photos
• Windows: %APPDATA%\Local Face Photos
• Linux: ${XDG_DATA_HOME:-~/.local/share}/local-face-photos

Please do not attach private photos, face crops, databases, or full personal file paths to public GitHub issues. Use synthetic examples or redact sensitive details.

Search Examples

Alex
Alex, Jordan
Mary Smith
Ironman Malaysia
Aman's first birthday
Alex, Ironman Malaysia
photos from 2022
December 2022

Search terms can match people, albums, or descriptive photo tags. Multiple terms use comma-separated AND matching, so Alex, Ironman Malaysia returns files where both match.

The planned OpenAI layer will make this more natural, so users can ask for memories in plain English instead of manually combining filters.

Use of Codex and GPT-5.6

Codex was used as a development collaborator throughout the project: planning the architecture, refactoring the backend, designing the SQLite schema, adding video support, creating tests, packaging the app with Tauri, preparing GitHub releases, and polishing documentation.

GPT-5.6 is planned as the natural language layer for search. Instead of requiring users to manually combine filters, the app can interpret queries like:

• “Show me photos of Aman from 2022”
• “Find Ironman Malaysia photos with Preeti”
• “Show videos from December 2022”

The goal is to keep the private photo library local while using OpenAI to translate human search intent into structured local database queries.

Documentation

• Installation and local development
• Configuration
• Architecture and local data
• Video scanning
• Desktop packaging
• API testing with Postman
• Roadmap

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT. See LICENSE.