Using fineshyt

Find your keepers.

A walkthrough from "I just installed it" to "I have a folder of my best work, ready to publish."

fineshyt has three jobs and they happen in this order: import your photos, rate the ones you have an opinion about, and let the recommendation model surface the rest. This page walks you through each one with no jargon.

You should be at http://localhost:4000 before continuing — that's the fineshyt UI. If it isn't loading, jump back to the install guide and make sure all three containers are running.

1 Import your photos

Importing means "tell fineshyt where your photos live and let it look through them." It doesn't move or modify your originals — it makes small JPEG copies for its own use and stores some notes about each photo in a database.

1a. Type the folder path

On the home page you'll see a big Directory field. Type the path to a folder of photos you want to cull. If you set up a single drive, the path looks like /photos/your-subfolder; if you set up multiple drives, type the real drive path like /Volumes/PhotoDrive/Wedding-2024.

Several quick-pick buttons appear underneath — click one and the field fills in for you. Click "Browse" if you'd rather pick the folder visually (works on macOS, Windows, and Linux with zenity).

1b. Pick a sample size

Below that, the Sample Size field controls how many photos fineshyt processes from that folder. Random sample. Default is 50. Fewer = faster (good for trying things out), more = takes longer but covers your archive.

First time? Start with 50. See the workflow end-to-end before you commit to a 14,000-photo overnight ingest. You can re-run the ingest with a larger sample later — fineshyt skips photos it has already processed.

1c. Hit Ingest

Click Ingest →. The activity log appears below the form. Each photo flows through three stages — convert (resize the original to a JPEG fineshyt can show you), curate (the AI looks at it and writes a few sentences about what it sees), and embed (a numerical fingerprint used by the recommendation model later). Each photo takes 10–30 seconds on a modern laptop; the activity log shows progress live.

If you have a lot of photos to import, you don't need to sit and watch — fineshyt keeps working in the background. Come back in an hour and the gallery will be full.

Want to stop early? Click the red Stop button next to the progress counter. The pipeline halts cleanly and any in-flight photos finish without leaving the queue messy.

2 Rate the photos you have opinions about

This is the part that makes fineshyt different from generic culling tools. The AI's job is to describe what it sees in objective terms; your job is to be the taste oracle. The more you rate, the better its recommendations get.

2a. Open the gallery

Click Gallery → in the top-right of any page (or visit http://localhost:4000/gallery directly). You'll see all the photos you imported, most-recent first. Each one has the AI's notes underneath plus filter chips at the top.

2b. Click stars to rate

Each photo has a row of five stars below it. Click 1 for "ugh," click 5 for "this is exactly what I want more of." Anything in between is fine — the model uses the full 1–5 range as gradient, not buckets.

Don't overthink it. Ratings aren't permanent — you can change them anytime. A 30-second gut reaction is more useful to the model than a 5-minute deliberation. You're teaching it your taste, not curating a museum.

2c. Skip the boring ones

You don't have to rate every photo. Most photos can sit unrated — the model only learns from the ones you have an opinion about. If a photo is fine but unremarkable, just scroll past.

3 Watch the MATCH badge appear

After you've rated about 30 photos, fineshyt has enough signal to start ranking the unrated ones. Photos that fit your taste pattern get a MATCH badge in the gallery; the badge means "based on what you liked, this one probably belongs in your keepers."

Use the filter chips at the top of the gallery to focus:

All — everything (default)
Match — only the photos the model thinks you'd like
No match — the rest, useful for spot-checking the model
Unrated — photos you haven't given a star yet

The model gets sharper around 150 ratings. Below 30 ratings the recommendations are noisy — the model is undertrained. Between 30 and 150 it's roughly useful. Past 150 it starts reflecting your taste in genuinely surprising ways. There's no upper limit; rate as many as you feel like.

3a. Override the model with Chef's Pick

Sometimes the model is wrong. A photo you love doesn't get the MATCH badge, or one you'd never publish does. Click ★ Chef's Pick on a photo to mark it as "this is a keeper regardless of what the model thinks." Chef's Picks always count as matches, no matter the numerical score.

4 Burst detection — kill the dupes

Photographers fire bursts. fineshyt notices when ten frames were taken within a few seconds of each other and look visually similar, and groups them as a "burst." In the gallery, bursts appear as one representative photo with a small badge showing the group size.

Click the burst to expand it. Inside you'll see all frames in the group with the sharpest one highlighted. Two buttons:

Keep best — keeps the sharpest frame, rejects the rest in one click
Keep all — leaves them all visible if you actually want every shot

Rejected photos don't get deleted from your hard drive — fineshyt only marks them so they don't clutter your gallery view. You can still find them under the "No match" or "Unrated" filters if you change your mind.

5 Group into projects, then export

Once you have a critical mass of MATCH-badged photos, you'll probably notice clusters — a wedding, a hike, a series. fineshyt lets you assign a project name to a photo (or many photos at once) via the gallery. The project name is just a label; you make it up.

5a. Assign a project

In the gallery, each photo has a Project field next to its metadata. Type a name — anything memorable like 2024-spring-roll-01 or amelia-and-josh-wedding — and hit Save. Photos with the same name are grouped under that project.

5b. Export approved photos

When you're ready to publish a project, fineshyt exports the approved photos plus a photos.json manifest your blog or portfolio site can read. From PowerShell or Terminal, in the fineshyt folder:

docker compose exec orchestrator /app/bin/orchestrator eval "Mix.Tasks.Fineshyt.Export.run([\"--target\", \"/photos/exports/wedding\"])"

That writes the JPEGs and the manifest into the folder you point at. "Approved" means a photo is rated and one of: rated 4 or more stars, Chef's Picked, or above the MATCH threshold. Unrated photos never export — the whole point is that you had an opinion about them first.

Export is additive. Running it again won't overwrite or duplicate; existing files are skipped. Safe to re-run after rating more photos and want to refresh the export folder.

Where to go from here

That's the whole loop. Import → Rate → Match → Group → Export. After your first session of 30+ ratings the model starts feeling responsive; after a few hundred it starts feeling like it gets you.

Stuck? Open an issue on GitHub with what you saw and what you expected. The error log at /logs shows everything that went wrong recently — useful to paste into the issue.