Before the first run

Four things, in this order. The first two are one-offs for the machine; the third is the one people miss.

1. Install the two local tools. Matching and resizing both happen here, with programs Recued does not ship. They must be on the PATH of the machine running your server, not your laptop — it is the server that runs them.

On macOS or Linux:

pipx install face_recognition
brew install vips            # or: apt install libvips-tools

On Windows — verified on Windows 11, including on ARM machines:

winget install libvips.libvips
winget install Python.Python.3.12
pip install dlib-bin
pip install --no-deps face_recognition face_recognition_models
pip install Click numpy Pillow "setuptools<81"

⛔ After installing libvips, put its real folder on your PATH — something like ...\WinGet\Packages\libvips.libvips_...\vips-dev-8.18\bin. The short vips that winget puts on your PATH for you cannot run: it sits by itself, away from the sixty-odd files it needs, and stops with a missing-file error before it does anything. Recued will report vips as installed, because there is something called vips on the PATH, and then every scan will fail with a number instead of a reason. Point the PATH at the real folder and it works.

⚠ dlib-bin is not a typo. The usual pip install face_recognition tries to BUILD its face library from source, which on Windows needs a C++ compiler and several gigabytes of build tools. dlib-bin is the same library already built — a few megabytes, no compiler.

⚠ On an ARM machine, install the x64 Python rather than the ARM one. Windows runs it under emulation and it works; the face library has no ARM build.

⚠ The setuptools<81 pin is not Windows-only — it matters anywhere you have a FRESH Python. Version 81 removed a helper that face_recognition_models still asks for, so on a new machine the scan stops with *"Please install face_recognition_models"* even though you just did. An older Python usually has the helper already, which is why this only bites on a clean install.

2. Install the pack. Installing Photo Attribution also installs the two packs it depends on, Face Recognition and Photo Derive. You do not install those yourself.

⛔ 3. Allow the four tool actions. Installing a pack does NOT let it run a program on your machine — that is a separate, deliberate yes, and until you give it every scan stops at the first step.

Each pack carries its own toggles, on Packs → that pack → Access. The four you need are not on Photo Attribution; they are on the two packs it installed for you:

4. Build the roster. One reference photo per person, one face per file, named <key> - <Name>.jpg — 001 - Maggie.jpg gives the key 001 and the name Maggie. The key is the identity and never changes; the name is what people see. Import a roster takes a CSV instead, in one approval, and its key column must match those file names without the extension.

⚠ A comma in either folder's name is refused, and that refusal is protecting you: the matching tool prints unquoted CSV, so Xmas, 2025 would split into the wrong columns and quietly attach every photo to one made-up person. Rename the folder.

Not needed to scan

Sending needs a mailbox connected and an address for each person, set on their card. Writing the lines needs a language model — the free pool, or your own key. You can scan, describe and review long before either is set up; nothing leaves the machine until you send.

What this does

Point it at one event's folder and a roster folder of reference photos, one face per file. Every picture is compared against the roster on this machine, and Recued records who appears in each one. Your photos are never copied, moved or altered.

Run it once per event folder, then Write the photo lines.

What it can read

JPEG and PNG only. HEIC — what an iPhone saves unless you have changed the setting — is skipped silently, so a folder straight off a phone can scan to nothing with no error.

The folder is not searched recursively. Photos in subfolders are ignored. Scan each subfolder as its own event.

⚠ A scan runs until it finishes, up to an hour, and stopping the run is how you cancel it.

Measured on a ten-core machine, a phone-sized photo holding seven faces costs about a tenth of a second, so an ordinary event finishes in seconds. Most of a small scan is startup: twelve photos take about as long as one. A modest two-core server is roughly five times slower, which still leaves thousands of photos inside the hour.

Match strictness

Lower is stricter. The tool's own default is 0.6; this pack ships 0.45, because on a seven-face group photo 0.6 matched four of those faces to one person.

Faces matching nobody is the dial. Climbing means people you know are being missed, so raise it. Falling to zero while the wrong names appear means lower it. Neither number is stored — only photos with at least one recognised person get a record.

Two people, or one face twice?

A photo lists everyone recognised in it, but nothing records which face each name came from. Two names may be two people, or one face that resembled two people on your roster.

So read the names against the picture on the review screen. That is the only place a wrong attribution can be caught, and it is why the review step exists.

Running it again is safe

Photos already recorded for this event are skipped. Adding forty pictures to a folder scanned last week costs forty comparisons, not four hundred.

⚠ Changing the strictness does not re-judge photos already scanned. Every row records the setting that produced it, so a number you change today never quietly rewrites a decision made yesterday. To re-judge, delete those rows and scan again.

The counts that matter

Lines that were not data should be zero. Two things land here: warnings the scanner prints on the same channel as its results — a roster photo holding two faces, or none — and lines that name nobody. Both are dropped rather than mistaken for a photo. A number above zero usually means a roster file needs a look.

Could not be linked, could not be recorded and **people that could not be added** should all be zero. Each counts work that was refused, and a refused write does not stop the run.

Before the first run

Two local tools have to be installed, or the scan stops with "cli tool ... was not found":

• pipx install face_recognition — the matcher. Installs in seconds from a prebuilt

wheel on common platforms.

• libvips — brew install vips, or apt install libvips-tools. Used to make the

small copy shown to the model when you write the lines.

Neither sends anything anywhere. Both run on this machine.

A comma in the folder name is refused

Xmas, 2025 will not scan, and that refusal is deliberate. The matcher prints its results as comma-separated text without quoting, so a comma in the path splits into an extra column: the photo's path is cut short, part of it is read as a person's name, and the real match is lost. Worse, every photo in the folder would collapse onto one record, because the path is what identifies a photo.

Rename the folder — Xmas 2025 — and scan again.

Building the roster folder

There is nothing to upload. The roster is a plain folder you keep, and Recued reads it in place — no picture is ever copied into Recued, and there is no photo on a person's record.

The file name is the identity. There are two ways to write it:

• Maggie Chen.jpg — the whole name is both the identity and what messages say.

Simple, and fine if you never intend to rename anyone.

• 001 - Maggie Chen.jpg — the part before the first - is the identity, and the

rest is what messages say. The separator is a space, a hyphen and a space, so ordinary hyphenated names like Mary-Jane are safe.

The second form is worth the trouble for one reason: **you can rename the name half whenever you like.** 001 - Maggie Chen.jpg → 001 - Maggie Thompson.jpg is still person 001, with their address and their history intact.

One file per person. The same face saved twice — maggie.jpg and Maggie Chen.jpg — is two different people to Recued, and both will match the same photo, so that person appears twice and could be sent the same picture twice. Two files sharing one key (001 - Maggie.jpg and 001 - Mags.jpg) is one person.

One face per file. A reference photo holding two faces uses only the first and prints a warning; one holding none is ignored entirely. Both show up in **Lines that were not data**.

A file starting with the separator — - orphan.jpg — has no identity at all and is skipped rather than added as a nameless person.

People are added automatically the first time they are recognised, named after their file and with no email address. Import the roster (CSV) adds everyone at once from a spreadsheet, and Set a person's contact fixes one person — either is where an address comes from.

⚠ Renaming the IDENTITY does not rename the person

It makes a second person.

Renaming the name half of 001 - Maggie.jpg is safe — the identity is still 001. Changing the identity is not: maggie.jpg renamed to margaret.jpg, or 001 - … renamed to 002 - …, is something Recued has never seen, so a new person is added with no email address and no history. The original stays exactly where it was, still holding every photo ever attributed to it, and it will never be matched again because the file it was named after is gone.

Retire a person takes the leftover off the roster — it stops being matched, stops counting, and its photos are released, while everything it already holds is kept. Set a person's contact changes an address and a display name only. Deleting a record outright is still the Data screen; retiring is almost always what you want instead, because it keeps the history.

So pick each file name once and leave it alone. If you want a different name in messages — Maggie instead of maggie, or Mum instead of Margaret Thompson — change it in Set a person's contact. That name is what the lines and the greeting use, and it is free to differ from the file.