Skip to content

Add Image Matcher plugin - #819

Open
speckofthecosmos wants to merge 2 commits into
stashapp:mainfrom
speckofthecosmos:add-image-matcher
Open

speckofthecosmos wants to merge 2 commits into
stashapp:mainfrom
speckofthecosmos:add-image-matcher

Conversation

@speckofthecosmos

Copy link
Copy Markdown
Contributor

Got tired of seeing all the dupes in my library and not being able to catch them but very occasionally. Put together an interface and used it on my own library. Pulled ideas from several other image matching projects.

Claude Fable 5.2 (medium)

Adds plugins/image-matcher, a UI plugin (no Python, no dependencies) that finds images that look the same and lets you act on them. Related: stashapp/stash#1867 (image duplicate checker request) and the closed stashapp/stash#6675.

Behavior (what this adds for users)

  • A page at /image-matcher, opened from a top-bar button, with two tabs:
    • Folder sets: pairs of folders that share two or more look-alikes ("the same set in two places"), handled in one decision.
    • Images: individual look-alike groups, plus one button to act on every group on the page.
  • Every card ends in one of three actions:
    • Merge: the look-alikes become one image in Stash. Every file stays on disk and the better copy stays primary.
    • Delete: keep one copy and delete the others from disk, after moving their tags, rating and details to the kept copy. Confirmation required.
    • Not a match: remembered in the plugin settings.
  • Which copy is kept: folder rules first (an ordered list of folders that win), then colour over black and white, then resolution, then file size.
  • Every pair shows how close it is ("same hash" or "N bits off").
  • Pairs whose thumbnails differ strongly in one place (two drawings that differ in one detail) are flagged, marked on the picture and left out until put back. Pairs that differ everywhere are flagged as different pictures.
  • Any pair or image can be left out of an action. Folders can be left out of folder sets.
  • Accuracy levels Exact / High / Medium / Low are phash distance 0 / 4 / 8 / 10.
  • Images inside zip or cbz archives are left out.
  • Images without a phash are skipped and counted.
  • A guide on the page (How this works, open on a first visit) explains the tabs, buttons and labels. A folder pair that mostly does not match carries a caution, since two unrelated folders can share look-alikes by chance.

How merge works

Stash has no image-merge mutation. The plugin does not write to the database:

  1. fileSetFingerprints puts the same custom fingerprint (type imagematch) on the kept image's files and the other image's files.
  2. Metadata is copied to the kept image.
  3. imagesDestroy removes the other image record with delete_file: false.
  4. metadataScan on those files: the scanner attaches a file that has no image to the image sharing a fingerprint.
  5. The plugin checks that each file is on exactly the kept image.

Because the scanner matches on any fingerprint, the file's phash is set aside during the rescan and restored once the file has landed.

Implementation notes (open to revision)

  • Three files: imcore.js (pure logic), imops.js (GraphQL operations), imui.js (the React page via PluginApi).
  • The page route is outside /plugin/, because Stash serves plugin assets there and a refresh would 404.
  • Matching uses pigeonhole banding on the 64-bit phash and runs in the browser.
  • The folder name and manifest name are image-matcher; happy to rename to the repository's preferred style.
  • url: points at this folder; I can change it to a forum topic.

Testing

  • Unit tests (17), end-to-end tests against a throwaway Stash in Docker (12) and a scripted browser pass, all passing on Stash v0.31.1 and v0.32.0-12.
  • Used by the author on a real library.
  • validator/validate.js --ci passes.
  • The test files are not included, so they are not installed with the plugin; they can be added if preferred.

Limits

  • No undo: Stash has no image split. A delete cannot be reversed.
  • Crops, rotations and mirrors are mostly not found (phash).
  • A very small or faint difference between two pictures can pass the difference check.

LLM-assisted contribution

Written with Claude Code (an LLM) under the author's direction, per this repository's rule for LLM-assisted contributions. The author specified the behaviour, used it on a real library, and looked over the code. An LLM code review was also run over the whole plugin and its ten findings are fixed in this version. The author takes responsibility for the code.

🤖 Generated with Claude Code

speckofthecosmos and others added 2 commits November 15, 2026 11:24
A UI plugin that finds look-alike images by perceptual hash and lets the user
merge them into one image (every file kept), delete the lesser copies, or
handle a whole folder pair in one decision.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…screen

- Stash deletes a file by renaming it to <name>.delete first
  (stashapp/stash#3664), so a name over 248 bytes cannot be deleted and one
  such file failed the whole delete. Delete now leaves those copies alone,
  labels them beforehand, and points to merge.
- Delete works on an image that holds several files; its card lists every
  folder they are in, and warnings and results give the true file count.
- Results show in a bar fixed to the bottom of the screen, so they are seen
  wherever the button was.
- Choosing another copy to keep no longer leaves the old kept copy out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant