Visual search in Phoaly lets you find a photo by describing what is in the frame. The text encoder and the photo vectors run on the Mac, the index is built once, and the sentence you type never leaves the machine.
This page explains how the feature works and where it stops. For query tips, see the visual search guide.
What it does
Type a short description and get matching photos:
- “city lights”
- “sunset by the sea”
- “a kid on the grass”
- “birthday cake”
The match is based on the picture, not the file name. Chinese and English descriptions both work. No tags, albums, or naming conventions are required first.
How it works
The feature has two halves that meet in the same vector space:
- Photo vectors. During indexing, each photo gets a vector that represents what is in the picture.
- Text encoding. When you search, the sentence is encoded into a vector in that same space.
The search compares the sentence vector with the photo vectors and ranks the closest matches. The photo vectors are computed once; each query encodes only the sentence.
If the file name search finds nothing, Phoaly switches to the picture for that term, once. That fallback prevents a dead end without turning every query into a visual search.
File name search and visual search
The two searches answer different questions and use different indexes:
| File name search | Visual search | |
|---|---|---|
| Index | FTS5 trigram | Photo vectors |
| Best for | Known names, Chinese substrings, fragments | What the picture looks like |
| Example | IMG_4821, 京都 | city lights |
| Requires tags | No | No |
| Runs locally | Yes | Yes |
The trigram index is why Chinese substrings and fragments from the middle of English names match. The vector index is why a description can match a photo that was never named.
Privacy model
Everything stays on the Mac:
- Photo vectors are stored locally.
- The sentence is encoded locally.
- Photos and thumbnails are not uploaded.
- There is no account and no cloud sync.
Activation sends the license key, a random device ID, and the app version. Visual search does not send the query anywhere.
Performance model
Two details keep the feature usable on a large library:
- Indexing happens once per photo, not once per search.
- The text model loads on demand and is released after five idle minutes.
The browser is built for large libraries: virtual lists, cursor pagination, and thumbnails that decode only in the viewport. The documented benchmark is a 100,000-item library.
Limits
Visual search is not a general image-understanding system:
- It does not read text inside photos. Use a text-recognition tool for signs, receipts, and documents.
- It does not know a person's name unless face grouping has assigned one.
- It does not know the story, the client, or the delivery status.
- It does not develop RAW files or replace an editor.
For those questions, use file names, folders, the map, the capture date, or another tool.
Where it fits
Visual search is most useful when you remember the picture but not the file:
- Finding a shot from a trip without knowing the folder.
- Locating a specific scene in a large family archive.
- Pulling a set of images by mood for a quick review.
- Crossing a description with a date range or a person.
It is a search tool inside the organizer, not a separate library.
Frequently asked questions
Does it upload photos or queries?
No. Both the photo vectors and the text encoding are local.
Does it need tags or albums?
No. The index is built from the pictures themselves.
Can it search in Chinese?
Yes. Chinese and English descriptions both work.
Why does a search miss a photo?
Visual search matches appearance, not the story or the file name. Try a different noun or setting. If the file is in a format the index cannot read, rebuild the index and try again.