# Random Pair Generator

*Version 0.1.1 build 16 (2026-05-08)*

A Lightroom Classic plugin that pairs photos from your
catalog at random.  A sequencing aid for photo books,
portfolio curation, zine spreads, gallery walls, or any
moment when you want to be surprised by work you thought
you knew.

**Alpha.** macOS and Windows.

## What it does

You click a menu item.  A plugin dashboard opens in
Lightroom, and a browser window appears next to it showing
two of your photos side-by-side, pulled at random.  Hit
Space and you get two new ones.

- **Generate pair** for a new pair.
- **Back** to revisit the previous one.
- **Generate one side** to refresh just the left or right
  photo while keeping the other.
- **Swap** to flip left / right of the current pair.
- **Save** to store the pair as its own sub-collection inside
  a target Collection Set.

Filter the source by rating, flag, color label, or
orientation.  Pull from the current Library view, a single
collection, or two different collections (one per side).

I originally built a tool like this as a personal editing aid, a way
to break out of the "I've seen these photos a thousand
times" rut.  A version of this exists publicly:
[alibosworth.com/pairs](https://alibosworth.com/pairs/).

---

## How it works

A plugin dashboard opens in Lightroom, and a separate
browser window launches showing your photos.  The browser window
is used because Lightroom's plugin UI toolkit is too
limited to render this kind of interface cleanly.  A small
helper process bridges the web interface to the plugin.
Local-only, runs entirely on your own computer.

**Your photos and catalog content stay on your computer.**
No image data, file paths, metadata, ratings, or pair
selections are transmitted anywhere, and the helper
doesn't accept connections from outside your machine.

---

## Install

1. **Install Go.** [go.dev/install](https://go.dev/doc/install).
   Needed for step 5 (explained after the steps).
2. **Place `RandomPairGenerator.lrplugin`** anywhere you
   like. No special location required, but tidy spots
   people commonly use for Lightroom plugins:
   - macOS: `~/Documents/Lightroom Plugins/` or
     `~/Library/Application Support/Adobe/Lightroom/Modules/`.
   - Windows:
     `Documents\Lightroom Plugins\` or
     `%APPDATA%\Adobe\Lightroom\Modules\`.

   Avoid Downloads, Desktop, or anywhere you might clean up
   without thinking. Lightroom will silently disable the
   plugin on next launch if the folder moves or vanishes.
3. **Add to Lightroom.**
   *File → Plug-in Manager → Add*, then select
   `RandomPairGenerator.lrplugin`.
4. **Set up a starting pool.**  In the Library module,
   view a group of images: a collection, a folder, a
   smart collection, anything in your sidebar.  Whatever
   you have showing becomes the initial pool the plugin
   draws from.  You can configure something more specific
   later in Settings, but starting with a meaningful
   Library view gets you going immediately.
5. **Open from the menu.**
   *Library → Plug-in Extras → Start Random Pair Generator*.

On first launch the plugin has to compile a helper that runs 
the pair window (1–30s). This is why step 1 needs Go installed.

The plugin experience is smoothest with **Chrome, Edge, or
Brave** installed. The pair window opens borderless, like
a native app, with no address bar or tabs. Otherwise it
falls back to your default browser with the usual controls
around the photos.

---

## Using it

### Keyboard

| Action | Shortcut |
|---|---|
| Generate pair | `Space` / `→` / `Enter` / click the pair |
| Back (previous pair) | `←` |
| Swap sides | `X` |
| Generate one side | `[` left / `]` right (or Shift-click that side) |
| Reveal photo in Lightroom | `Cmd/Ctrl + [` or `Cmd/Ctrl + ]` |
| Save pair | `S` |
| Toggle fullscreen | `F` |
| Bring Lightroom to the front | `L` |
| Refresh Library snapshot | `R` (current Library view mode only) |
| Show shortcuts overlay | `?` |
| Close overlay | `Esc` or any key |

The keyboard-shortcut overlay auto-opens on the very first
launch so you don't have to find this table.

### Source modes

Settable via *Dashboard → Settings → Sources*.

- **Current Library view (snapshot).**  Default.  Captures
  whatever's visible in Lightroom's filmstrip the moment
  you start the session.  The snapshot is **frozen** so the
  pool doesn't shift mid-browse.  *Rebuild snapshot* on the
  Photo-source row refreshes it.  (It also auto-rebuilds
  every time the Dashboard opens.)
- **Single collection.**  Both photos drawn from one
  collection.
- **Two collections, one per side.**  Left from one,
  right from another.  Useful for pairing across
  distinct projects, or working alongside another
  photographer.

### Filters

*Dashboard → Settings → Filters.*  Independent of source
mode.

- Minimum star rating
- Required flag (pick / unflagged / reject)
- Required color label
- Orientation pool (any / landscape only / portrait only)
- Allow mixed orientations within a pair (or force same)

### Saving pairs

Each saved pair becomes a new sub-collection inside your
configured collection set, named `Saved Random Pair NNNN`
(zero-padded so they sort in save order in LR's sidebar).
Both photos are added in left → right order.

**To see the original L/R layout when you open a
saved pair, the collection's sort order must be set
to "Custom Order: Ascending."**

- **macOS**: LR defaults to Custom Order for new
  collections, so you'll see the correct layout out of
  the box.  No action needed unless you've changed the
  sort.
- **Windows**: LR defaults to **Capture Time** instead.
  Pairs where the right photo was taken before the
  left photo will appear flipped.  To fix: open the
  saved pair, change its sort to *Custom Order:
  Ascending* (the dropdown at the top of the
  filmstrip).  Stays sticky for that collection.

The plugin shows a one-time note on your first save
explaining this.

The target collection set has to exist in Lightroom first;
the plugin can't create it for you.  Create a collection set
like "Potential Pairs" and select it in 
*Settings → Sources → Save pairs to*.

---

## The Dashboard

A panel inside Lightroom alongside the browser window.
Five status rows, each green / amber / red:

| Row | Green | Amber | Red |
|---|---|---|---|
| **Go runtime** | Installed | — | Not installed (with go.dev install button) |
| **Helper** | Running | Starting / compiling | Not running (with Start button) |
| **Browser** | Chrome / Edge / Brave | Default browser | — |
| **Photo source** | ≥20 photos | <20 photos / cap reached | 0 photos / no collection chosen |
| **Save pairs to** | Collection set configured | Not configured (Save disabled) | — |

Rows that need user action feature an inline button: *Open Settings*, 
*Rebuild snapshot*, *Start*.  A **Troubleshooting** dialog (button 
in the action row) hosts secondary actions: rescan status, restart 
the background service, view log, clear thumbnail cache.

---

## Troubleshooting

### Logs

| File | Contents |
|---|---|
| `plugin.log` | Lua-side log: dashboard events, IPC traffic, action handlers |
| `helper.log` | Go helper: HTTP server, action proxy, errors |

Both live in the plugin's temp folder, which is the OS's
per-user temp directory. You can open this folder via
Dashboard → Troubleshooting. Open the files via *Dashboard
→ Troubleshooting → View log* / *View helper log*.

### Common failures

- **"Nothing happens on click"** → Check the Dashboard.
  The failing row tells you what's missing, usually Go.
- **"No pair available"** → Likely an empty Library view
  captured into the snapshot.  Navigate to a non-empty
  source and *Rebuild snapshot*. If more than one photo
  is selected (even if just 2) when the snapshot is made
  then only the selected images will be included 
  (lightroom quirk).
- **Browser shows "ERR_CONNECTION_REFUSED"** → Helper
  didn't was unable to connect to the web component. 
  Check the Helper row; if amber *Compiling*, wait. 
  If red, *View helper log* shows the reason (often 
  Go install path issue or port :9417 already in use).

### Reporting bugs

Email `ali@alibosworth.com` (also a button in the
Dashboard's contact block) with:

- What you did, what you expected, what happened.
- Build number from the bottom of the Dashboard.
- Attached logs from the temp folder.

---

## Requirements

- **Lightroom Classic** (any recent version).
- **macOS 11+** (Big Sur or later) **or Windows 10+**.
- **Go**, from [go.dev/install](https://go.dev/doc/install).
  The plugin spawns `go run` on launch.
- **Chrome, Edge, or Brave** preferred for the borderless
  `--app` window experience.  Default browser also works
  (you'll just see a normal URL bar).

---

## Known alpha-stage limitations

- **Go prerequisite.**  Shipping as source for alpha. Beta
  will ship pre-built signed binaries.
- **First-launch compile window** of a few seconds.

---

## Known quirks

These are persistent platform / host issues: Lightroom
SDK limitations or LR-side bugs the plugin routes around
but can't fix.

- **Dashboard stays on top of Lightroom (Windows
  Lightroom Classic 15.2 and 15.3).**  A bug in LR
  Classic for Windows introduced in 15.2 forces floating 
  dialogs to overlap all other windows. You can minimize
  the plugin dashboard to work around it for now.

- **Saved pairs may not display in the correct order.**
  When you open a saved-pair collection, the photos
  may appear in the wrong order until you change the
  collection's Sort Order to *Custom*.  macOS Lightroom
  appears to use Custom Order by default for new
  collections while Windows Lightroom appears to default
  to *Capture time*, so the same pair may show
  flipped. The plugin can't pre-set this for you. Switch
  the sort dropdown at the top of the filmstrip to
  *Custom Order: Ascending* on the saved collection.
  It sticks for that collection.

---

Alpha software.  Testing and personal use only; please
don't redistribute.
