Workflows

Most videre commands read work that an earlier command produced. Nothing warns you loudly when a step is missing: videre search with no embeddings finds nothing, and videre classify with no embeddings reports success having done nothing at all.

This page is the map.

Every command’s own page has its flags and caveats; Commands is the index.

The pipeline

videre scan                         <- everything starts here
  │
  ├── videre gallery                browse files, duplicates and dates
  ├── videre dedupe --html          find duplicates and review via static HTML file
  │     │
  │     └── videre dedupe --remove  move the duplicate copies to the trash
  │           │
  │           └── videre prune      synchronize the database after cleanup
  │
  ├── videre fix-dates              correct file dates
  │     │
  │     └── videre prune            synchronize the database after fixing dates
  │
  ├── videre status                 see videre pipeline status and next actions
  ├── videre stats                  what's in the library
  ├── videre locations              group by place
  ├── videre mark                   rate, like, label, pick your media files
  ├── videre tag                    add word or phrase to your media files
  ├── videre embed                  prepare search  (slow, one-time)
  │     │
  │     ├── videre search "..."     by description
  │     ├── videre search --image   by example
  │     ├── videre gallery          in-page similarity
  │     └── videre classify         tag screenshots/documents/memes
  │           │
  │           ├── videre mark --category
  │           ├── videre tag --category
  │           └── videre search --category
  │
  ├── videre faces                  detect and group faces  (slow, one-time)
  │     │
  │     └── videre gallery          show face clusters and name people (manual step)
  │           │
  │           ├── videre mark --person
  │           ├── videre tag --person
  │           └── videre search --person
  │
  └── videre pipeline               Run: scan -> faces -> embed -> classify -> locations

• When migrating from another photo tool, videre import comes before videre scan.
• videre watch can run instead of a one-off videre scan for continuous operation.
• videre export can run once a file has metadata to export:
  • Ratings and labels require mark
  • Keywords require tag
  • Named face regions require faces, then naming in gallery
  • Categories require embed, then classify
  • Resolved place names require locations

What each command needs first

To run	You need
Anything at all	scan
search (text or --image)	embed
search --category	embed, then classify
search --person	faces, then naming in gallery
search --location	GPS in your photos (from scan)
classify	embed
the similarity button in gallery	embed
gallery	faces
names shown in gallery	faces and naming done
dedupe --similar	embed
locations	GPS in your photos (from scan)

The manual naming step is easy to overlook. videre faces groups faces but gives them no names, so search --person and the names in videre gallery stay empty until you have opened videre gallery and assigned some.

What to run afterwards

After you	Run
Delete files (dedupe --remove)	prune
Move or reorganise folders	scan, then prune
Add new photos	scan, then embed / faces / classify again
Finish chunked faces --limit runs	faces --recluster
Change classify --margin	classify --reprocess

prune is the one people forget. Until it runs, deleted files are still counted in stats, and their embeddings and cached thumbnails still occupy disk.

Recipes

Set up a library from scratch

videre --library ~/Photos scan           # minutes; reads every byte
videre embed                   # hours; downloads ~1.5 GB first
videre faces                   # hours; downloads ~180 MB first
videre classify                # minutes; reuses embed's work
videre locations               # seconds to minutes
videre gallery          # name the people you care about

Only the first is required. Stop wherever you like; each later step adds one capability. embed and faces are both resumable, so Ctrl-C is safe.

Come from another photo tool

videre import ~/Takeout --dry-run   # see what it found
videre import ~/Takeout             # fix the dates the exporter mangled
videre --library ~/Takeout scan               # now record them
videre dedupe --remove              # collapse the copies albums created
videre prune

Import comes before scan, since dates must be corrected before scan records them. Works the same for an Apple Photos library or a Lightroom catalog: point it at the library and it works out the rest. See Leaving Google Photos.

Clean up duplicates safely

videre --library ~/Photos scan
videre dedupe --html                  # review groups with KEEP/REMOVE badges
videre dedupe --remove                # move the copies to the trash, once you agree
videre prune                          # reclaim database rows and derived data

Add --similar to dedupe if you also want near-duplicates (it needs videre embed), which are reported for review only and never included in the delete list.

Turn on search later

If you scanned a while ago and now want semantic search:

videre --library ~/Photos scan   # incremental: picks up anything new, fast
videre embed
videre search "sunset over water"

Name people

videre --library ~/Photos watch --heic   # optional: makes the next step ~70x faster on HEIC
videre faces
videre gallery          # drag clusters onto people
videre search --person "Alice"

On a large library, do detection in sittings:

videre faces --limit 2000      # repeat as often as you like
videre faces --recluster       # once, at the end

Fix wrong dates

videre --library ~/Photos scan
videre fix-dates --dry-run     # check first; this writes to your files
videre fix-dates

fix-dates changes only the files whose time differs from their EXIF date, the count videre status suggests, and records each new time in the database itself, so nothing needs re-syncing afterwards. Running it again reports every file as already correct.

Keep everything current

videre --library ~/Photos watch

That covers scanning, faces, HEIC caching and place names on a loop. It does not cover embed or classify, so run those by hand after importing a batch of photos.

Do not run a manual embed or faces while watch is running its faces or HEIC stages. See the caveats.

Reclaim disk space

videre prune                              # orphaned embeddings and thumbnails
du -sh ~/.cache/videre/thumbnails/        # the cache is often the bulk of it
videre stats                              # what each model is using

The thumbnail cache can be deleted outright; everything in it regenerates.

After moving files around

videre --library ~/Photos scan     # records the new paths
videre prune             # removes the old ones

Faces and embeddings survive, because they are keyed by content rather than path. Only the paths change.

Ask a compound question

videre search --category document --date 2025-05 \
  --location "Altunizade, Istanbul" --radius 5

Filters AND together, so each one narrows further. See compositional searches.

Try a different search model

videre embed --model google/siglip2-base-patch16-384
videre search "kids playing in snow" --scores
videre search "kids playing in snow" --scores --model google/siglip2-base-patch16-384
videre config set model google/siglip2-base-patch16-384    # if you prefer it

The old vectors stay intact and queryable throughout. See search models.

Rough costs

Worth knowing before starting something long. Figures are from a real 70,000 file library.

Step	Order of magnitude
scan --force	~10 minutes, reads every byte
scan (incremental, default)	~1 second when nothing changed
embed	Hours, plus a ~1.5 GB download
faces	Hours, plus a ~180 MB download
classify	Minutes; reuses embed
locations	~8 minutes, mostly database writes
dedupe, stats	Seconds; pure database reads

embed, faces and classify are all resumable and only ever process what is missing, so the second run over an unchanged library is fast.