Threshold Tuning
Set the SnapByFace similarity threshold between 0.30 and 0.80: what 0.45 means, when to raise or lower it, and why a change never re-analyzes your media.
Every match SnapByFace reports is a cosine similarity between two 512-D face embeddings: the embedding of your reference photo and the embedding of a face found in your media. The threshold decides where the cut-off sits.
Defaults and range
| Setting | Value |
|---|---|
| Default threshold | 0.45 |
| Adjustable range | 0.30 – 0.80 |
| Applies to | photos and sampled video frames alike |
| Stored in | ~/.snapbyface/config.json |
Which way to move it
- Raise it (0.55–0.65) when you see false positives — different people reported as the same person. Fewer, safer matches.
- Lower it (0.35–0.40) when known appearances are missing because they scored below the cut-off. More matches, more noise.
- 0.80 is close to a near-identity match: very few hits, mostly near-duplicate photos.
- 0.30 is very permissive: a long tail of low-confidence hits to review by hand.
:::note Similarity is not a probability and not a human “certainty percentage”. Two photos of the same person taken years apart can legitimately score lower than two different people photographed in similar lighting and pose. :::
A practical procedure
- Keep the default 0.45 for the first run and inspect the top matches.
- If the top hits are all correct but you suspect misses, lower to 0.40 and re-check.
- If clearly wrong faces sit above the cut-off, raise in steps of 0.05 until the noise disappears.
- Always double-check a few borderline hits in the preview before trusting a setting.
- Stop tuning once your known-good hits are in and the obvious wrong ones are out.
What a threshold change does — and does not do
Changing the threshold re-matches existing embeddings only. Your photos and videos are not re-read, no frame is re-decoded, and no face is re-detected, so the change is fast even on a very large library.
:::caution Changing the video sampling interval is the opposite case: it changes which frames exist at all, so the affected videos must be analyzed again. See Searching Videos. :::
If tuning is not enough
A threshold cannot fix a bad reference photo. If one person consistently scores low:
- Replace their photo with a frontal, evenly lit, unobstructed shot.
- Make sure the reference contains exactly one face.
- Avoid heavy filters, sunglasses, and extreme angles.
- For video, check whether the sampling interval lands on frames where the face is visible.
Sanity checks
- Nothing changed after lowering the threshold? The faces probably were not detected at all — check frame quality or interval rather than the threshold.
- Everything matches everyone? You are likely near 0.30. Move back up toward 0.50.
- One person dominates the results? Their embedding may be too generic (a low-quality or heavily compressed reference photo). Replace it.