 |
Summary | Find duplicate performers via evidence-graded grouping, pick a target per group, merge in bulk through the native performerMerge mutation. Also ships a short-name alias cleanup module and an alias-repair module for squashed single-line entries. Pure UI plugin (JS + CSS only, no Python). |
 |
Repository | https://github.com/k6cc/stash-jav-tools/tree/main/performerMerge |
 |
Source URL | https://k6cc.github.io/stash-plugins/plugins/main/index.yml |
 |
Install | How to install a plugin? |
Hi stashers,
Every multi-source library ends up with duplicate performers: the same actress scraped from StashDB as “Iroha Suzumura” and created from a local filename as “涼村いろは”, plus single-word short aliases that overlap between two completely different people. Merging them one by one through the native dialog is fine for three performers, not for three hundred. This plugin scans your whole performer library, groups probable duplicates with a deliberately conservative evidence-graded engine, pre-selects a sensible target per group, and merges per group or in bulk. Bonus modules: one-click cleanup of shared short-name aliases, and repair of alias entries that got squashed into a single line.
No Python, no API key, works fully offline. Needs Stash v0.31.0+ (the native performerMerge mutation).
Works great paired with JavStashLinker (links JAVStash stash_ids onto your performers, which this plugin then uses as hard grouping evidence) and Studio Tools (the studio-side twin: merge duplicate studios with a per-field diff dialog).
What it does
Duplicate detection (deliberately conservative)
| Step | Rule |
|---|---|
| Normalization | NFC → lowercase → fullwidth→halfwidth → strip all whitespace → katakana folded to hiragana (なな = ナナ). |
| Evidence ① stash_id | Same endpoint + same stash_id = same external entity → grouped unconditionally. |
| Evidence ② shared URL | The same normalized URL held by exactly 2 performers. |
| Evidence ③ name keys | Names and aliases both count as keys; main-name match > full-name match > single-word short name. |
| Common-name suppression | Any name key shared by ≥3 performers library-wide is excluded from grouping. |
| Conflict blocking | Conflicting name/URL edges are refused and sent to the Force merge tab for manual review. |
| Default target | Most scenes → most stash_ids → earliest created. |
Group review
- One card per group; pick the target per group (default pre-selected).
- Inline badges show scene/gallery/image counts, alias and URL counts, stash_id endpoints, favorite and rating.
- Ignore collapses a false-positive group (restorable, persists across re-scans).
- “Merge All” skips ignored groups and groups flagged with ID/URL conflicts.
Merge behavior (native mutation, append-only safety)
Calls Stash’s native performerMerge mutation:
- Name / image — always the target’s own; never inherited from the source.
- Aliases — the source’s name + aliases are appended verbatim: no normalization, exact-string dedup only; entries identical to the target’s name are skipped.
- Other fields (aligned with the official dialog defaults) — empty single-value fields take the first non-empty source value.
- Write safety — only actually-changed fields are submitted; list fields are submitted only when they grow.
- After the mutation — the backend transfers the source’s scenes/galleries/images/tags to the target and deletes the source performer.
Short-name cleanup
Scrapers love writing romaji or kana short names into aliases. Those names are shared by many different performers — noise on detail pages and the #1 source of false-positive duplicate groups. The tab (populated by the same scan) lists every alias that is:
- shared (after normalization) by ≥2 performers — names and aliases both count, and
- a word short name: single word, no kanji, no symbols — only romaji/digits/kana.
Alias repair
Some operations squash several aliases into one entry. Stash stores alias_list as an array, so a corrupted entry is invisible on the performer page. The tab lists them per performer with the original string and a split preview.
Force merge
Name-matched pairs blocked by ID/URL conflicts — the databases say these are different people. Verify a pair really is the same person, then merge it here.
Notes
- Merging is irreversible (the source performer is deleted) — back up first (Settings → Tasks → Backup).
- Needs Stash v0.31.0+ (native
performerMergemutation); lower versions get a warning and disabled merge buttons. - No Python, no API key, works fully offline in any modern browser.
- Name matching is exact-normalized only, never fuzzy.
- Case-only duplicate aliases survive a merge fine, but Stash’s own alias editor will reject that performer later — clean them with the short-name module or by hand.
- A scan is a snapshot; if the library changes underneath a merge, that group is flagged failed — re-scan.
- Mobile-friendly: panel usable down to 480px.
Screenshots
Install
Option 1: Download Release
- Go to Releases and download the latest
performerMerge-vX.Y.Z.zip - Unzip into your Stash plugins directory (files go directly in the
performerMergefolder):- Windows:
%USERPROFILE%\.stash\plugins\performerMerge\ - Linux/macOS:
~/.stash/plugins/performerMerge/
- Windows:
- Stash → Settings → Plugins → Reload plugins
Option 2: Add plugin source
In Stash → Settings → Plugins → Available Plugins → Add Source, add:
Recommended (GitHub Pages):
https://k6cc.github.io/stash-plugins/plugins/main/index.yml
Fallback (raw URL, no Pages required):
https://raw.githubusercontent.com/k6cc/stash-plugins/main/plugins/main/index.yml
Then install Performer Merge from the list. Same unified source that carries JavStashLinker, Tag Merge, Studio Tools, sceneGallerySync, Scene Translate, and Binge (cn) — one source, install any.
Companion plugins
| Plugin | Synergy with Performer Merge |
|---|---|
| JavStashLinker | Links JAVStash stash_ids onto your performers; this plugin then groups same-endpoint-same-id duplicates unconditionally. Together they catch romaji-vs-kanji duplicates that name matching alone never would. |
| Studio Tools | Studio-side twin: merge duplicate studios with a per-field diff dialog, plus one-click metadata refresh from StashDB / ThePornDB / JAVStash. |
| Tag Merge | Tag-side cleanup of the same family: merge tag spelling variants into canonical tags. |
| Binge (fork) | One clean performer record everywhere: Feed scene cards, performer profiles, Reel badges. |
| nfoSceneParser (fork) | Parser writes performer names onto scenes → with duplicates merged, incoming parsed data lands on the single correct performer record. |
License: MIT. Feedback and bug reports welcome — if you hit a false-positive group (two different performers proposed for merging), tell me the names, aliases and stash_ids involved; the suppression and conflict-blocking thresholds are tunable, and real-world misses are exactly the data I need.
AI Development Statement
From project setup, fault debugging and architecture refactoring to the writing and polishing of all Markdown‑formatted documents, artificial intelligence runs through the entire development workflow of this project, and the whole project is developed with the help of AI.