Skip to content

Dev Plugin README

Jump to bottom
github-actions[bot] edited this page Aug 22, 2026 · 8 revisions

Plugin README

Auto-generated from plugin/README.md. Do not edit this page manually.

LrGeniusAI Lightroom Plugin

AI-powered metadata, semantic search, and face workflows for Adobe Lightroom Classic.

What It Does

LrGeniusAI adds a backend-powered AI layer to Lightroom Classic. It helps you:

  • Generate metadata (title, caption, keywords, alt_text)
  • Run semantic search on your catalog
  • Detect, cluster, and browse people/faces
  • Run image culling on selections or the current view and create result collections for fast review
  • Generate and apply Develop edits, optionally trained on your own edits
  • Deduplicate and declutter the keywords already in your catalog
  • Re-import generated metadata back into Lightroom

The plugin is designed to work with local and cloud providers, while keeping Lightroom as your main workspace.

Core Features

Analyze and Index

  • Batch-process selected, visible, all, or missing photos
  • Generate embeddings for semantic retrieval
  • Generate metadata
  • Optional face detection and clustering
  • Optional species identification (BioCLIP 2, on-device)

Advanced Search

  • Semantic search using image/text embeddings
  • Metadata field search (keywords, caption, title, alt_text)
  • Scope search to current selection/view/catalog

People Workflows

  • Cluster faces into persons
  • Rename persons
  • Jump from a person directly to a Lightroom collection
  • The People interface opens in your web browser (served by the backend at /v1/ui/people); Lightroom keeps a progress bar running while it is open, which is what turns a selection there into a collection here

AI Develop Edits

  • Generate a Develop recipe per photo and apply it non-destructively, either to the photo itself or to a virtual copy
  • No LLM involved: the backend matches the photo against the edits you saved yourself and interpolates theirs
  • Recipes are constrained to what the frame can take: the backend measures the image and caps contrast, clarity, shadow lift and whites accordingly, and reports why

Style Training

  • Save your own Develop settings as labeled training examples
  • The sole input to AI Develop Edits, which needs at least five of them

Keyword Dedup & Declutter

  • Cluster near-duplicate keywords in the catalog and merge them under a chosen primary term

Metadata Sync

  • Import existing Lightroom metadata to backend
  • Retrieve generated metadata from backend
  • Apply validated values back to catalog

Image Culling

  • Cull similar photos from selected photos or the current view
  • Group near-duplicates and bursts using backend similarity signals
  • Rank photos into:
    • Picks
    • Alternates
    • Reject Candidates
    • optional Duplicates / Near Duplicates
  • Detect exposure brackets, focus stacks and panoramas and route them to a Brackets / Stacks / Panoramas (keep all) collection with ranking switched off — every frame of such a set is part of one picture
  • Create a dedicated Lightroom collection set for each culling run and switch you directly to the picks collection for review

Requirements

  • Adobe Lightroom Classic (supported by plugin SDK settings)
  • LrGeniusAI backend server reachable from Lightroom. Released for Apple silicon macOS and 64-bit Windows — there is no Intel Mac or Linux build.
  • Optional API keys depending on provider:
    • Gemini
    • OpenAI / ChatGPT
    • Vertex AI (project + location) — removed, the plugin no longer offers Vertex AI

Installation

  1. Build or download the plugin package.
  2. In Lightroom Classic, open File -> Plug-in Manager.
  3. Click Add and select the LrGeniusAI.lrdevplugin folder.
  4. Configure server URL and provider settings in plugin preferences.

Breaking Change: ID Migration

The plugin/backend use file-based photo_id values instead of Lightroom catalog UUIDs as primary IDs. The stable ID algorithm was updated again to avoid ID changes when metadata is written into files (for example DNG metadata updates).

There is no migration. The one the plugin used to offer posted to POST /db/migrate-photo-ids, an endpoint the Rust backend does not serve and never has, so it could only ever fail. It has been removed rather than left in place as a button that does nothing.

If you have an indexed backend database from a UUID-era version, run Analyze & Index Photos over the catalog again. Photos that are already indexed under the current IDs are skipped, so this costs nothing beyond the photos that genuinely need re-indexing.

Breaking Change: Cross-Catalog Backend (Soft State, No Deletion)

When using a shared remote backend with multiple Lightroom catalogs, the backend no longer deletes photo data when a photo is removed from one catalog. Instead it only marks that catalog as no longer “having” that photo (catalog_ids). Other catalogs that still have the photo keep seeing it.

What the plugin does

  • Sends a stable catalog_id with all index and read requests so the backend can scope data per catalog.
  • Sync cleanup: When you run “Remove missing photos from index” (or the equivalent), the plugin calls the backend to disassociate this catalog from photos that are no longer in the current catalog. It does not ask the backend to delete those photos.
  • Claim photos: So that existing indexed photos are visible to this catalog under the new behavior, the plugin runs an automatic one-time “claim” on first use: it tells the backend to add this catalog’s catalog_id to all photos that are currently in the catalog. This runs in the background once per catalog; no dialog.

Manual “Claim photos for this catalog”

In Plug-in Manager -> LrGeniusAI -> Backend Server you can click Claim photos for this catalog to:

  • Re-run the claim (e.g. after restoring a backup or re-adding many photos).
  • Manually fix visibility if automatic claim did not run or failed.

This adds the current catalog’s id to the listed photos on the backend; it does not delete any data.

Identity Scope Note

The current photo_id / hash / derived canonicalId strategy is more stable than Lightroom catalog UUIDs, but it is still not guaranteed to be 100% cross-catalog safe in every workflow.

Treat backend identity as best-effort and primarily catalog-scoped for now, especially when:

  • the same files exist in multiple Lightroom catalogs
  • files were duplicated, re-exported, or rewritten outside Lightroom
  • the plugin had to fall back to partial file hashes because stable metadata IDs were unavailable

If strict cross-catalog identity is important for your workflow, plan for re-indexing or migration checks when moving photos between catalogs or restoring older databases.

Configuration (Plugin Manager)

In the plugin settings dialog you can configure:

  • Backend server URL
  • Ollama and LM Studio base URLs
  • API keys (the Vertex AI project/location fields were removed)
  • Local AI Model (no external app) — browse, download and select vision models the backend runs itself, plus the advanced knobs (context size, photos in parallel, layers on the GPU). Which engine backs this section is decided per platform: MLX on macOS, llama.cpp with GGUF models on Windows. The section reports why it is unavailable when the host cannot use it — a source build without the llamacpp feature, or a missing MLX helper.
  • Export size and quality used for AI processing
  • Prompt presets
  • Optional CLIP model download for advanced search

Google Vertex AI Login (gcloud) — REMOVED

⚠️ Vertex AI was removed from the plugin in August 2026. The project ID / location fields, the Create Vertex AI embeddings option in Analyze & Index, and the Semantic (Vertex AI) search option are gone from the Lightroom UI. The section below is kept for reference only and no longer describes a working setup path.

If you want to use Vertex AI from LrGeniusAI, run the login on the machine where the backend server runs.

macOS

  1. Install Google Cloud CLI (if not installed):
  2. Open Terminal and run:
gcloud init
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
  1. Optional verification:
gcloud auth application-default print-access-token

Windows (PowerShell)

  1. Install Google Cloud CLI (if not installed):
  2. Open Google Cloud SDK Shell (or PowerShell with gcloud in PATH) and run:
gcloud init
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
  1. Optional verification:
gcloud auth application-default print-access-token

Notes

  • gcloud auth application-default login creates local Application Default Credentials (ADC) used by the backend.
  • In plugin settings, set Vertex AI Project ID and Vertex AI Location (for example us-central1).
  • For headless/server deployments, prefer a service account with GOOGLE_APPLICATION_CREDENTIALS.

Typical Workflow

  1. Run Analyze and Index Photos
  2. Optionally validate generated metadata
  3. Use Advanced Search to find related images
  4. Use People and Find Similar Faces for portrait-heavy catalogs
  5. Run Cull Similar Photos on a selection or the current view to create Picks / Alternates / Reject Candidates collections
  6. Re-run Import Metadata from Catalog if needed for sync

Migration Notes

If you migrated from legacy UUID-based IDs to photo_id:

  • The plugin can trigger backend migration from the Plugin Manager UI.
  • Migration uses a progress scope and batch requests.
  • Existing collections (main embeddings, legacy vertex embeddings, faces) are migrated through backend migration endpoints.

Troubleshooting

  • Verify backend connectivity in plugin settings (backendServerUrl).
  • Check log files from Plugin Manager (Show logfile / copy logs to desktop).
  • If search returns no results, confirm photos were indexed with embeddings.
  • If faces are missing, ensure face processing was enabled during indexing.

⚖️ License

The LrGeniusAI plugin is released under the GNU Affero General Public License v3 (AGPL-3.0).

Documentation

Clone this wiki locally