 |
Summary | Automatically creates galleries for scenes on scan, syncs metadata (title / studio / performers / tags / date / rating / urls), imports poster + fanart, and auto-shares one gallery across multipart discs (CD1/CD2, -a/-B). |
 |
Repository | https://github.com/k6cc/stash-jav-tools/tree/main/sceneGallerySync |
 |
Source URL | https://k6cc.github.io/stash-plugins/plugins/main/index.yml |
 |
Install | How to install a plugin? |
Hi stashers,
If you organize your scenes with extrafanart/ folders (Kodi-style library layout) and wish Stash would automatically turn those extrafanart sets into proper Galleries linked to their scene — this plugin does exactly that, hands-off on every scan.
Works great in combination with Binge (fork) (gallery thumbnails show up on scene cards in the Feed + performer profile backdrops) and nfoSceneParser (fork) (waits for NFO metadata before attaching title/studio/performers/tags/urls/date/rating to the gallery).
What it does
-
Automatic gallery creation on scan — Hooks into
Scene.Update.Post. After a scene is scanned and nfoSceneParser writes the NFO, a lightweight one-shot background process fires up, waits for the scene metadata to settle (progressive backoff 3s→15s, max 12 attempts), then creates or updates the matching gallery. -
Full metadata sync — Gallery inherits the scene’s
title,code,details,date,rating100,urls,studio,performers,tags. If you edit scene metadata later, the gallery’s existing images remain intact and only new images are appended (no destructive re-creation). -
Poster + fanart auto-import — Searches
{filename}-poster.jpg/folder.jpgfor the gallery cover (sets it viasetGalleryCovermutation) and{filename}-fanart.jpg/landscape.jpgas additional gallery images. Configurable filename patterns inconfig.py. -
Multipart / multi-disc → one shared gallery — Filenames ending in
-cd1/-cd2,-disc1,-part1,-pt1, or single-letter-a/-B/-Call get stripped layer by layer (e.g.ABP-998-C-cd1→ABP-998-C→ABP-998). All discs land in the same gallery. Four-tier gallery search (exact title match → base filename match → first-word INCLUDES → title first-word INCLUDES) ensures consistency even with translation differences. -
Manual creation button — A “Create Gallery” button is injected next to the Galleries tab on every scene edit page. Bypasses the nfoSceneParser dependency; works at any time. Useful when you re-scanned a folder out of order or added extrafanart after the initial scan.
-
Early extrafanart guard (v1.6.0) — Before spawning the background process, the hook does a fast
gql_findScene+ filesystem check for theextrafanart/folder. Scenes without the folder (e.g./social/x/scraped content in Binge, plain scene directories) skip instantly — no idle Python process, no 2-minute metadata timeout. -
Non-blocking hook (v1.6.0) — Background subprocess redirects
stdin/stdouttoDEVNULLandstderrto a per-scene log file under.sgs_pending/. This fixes the infamous “edit spinner hangs for minutes /operation cancelledin log” issue that happens when a child process inherits the stash stdout pipe and keeps it open. -
Low-power Docker friendly — Progressive backoff on all poll loops (3s→5s→7s… max 15s), GraphQL auto-retry with exponential backoff (connection errors + timeouts, up to 3 attempts), no resident daemon — each hook spawns a process that exits after completion, stale task/log files older than 1 hour are auto-pruned.
Directory layout it expects
extrafanart/ folder is the hard prerequisite — no folder = no gallery (this is checked before any background work starts):
SceneDirectory/
├─ ABC-123.avi
├─ ABC-123-poster.jpg ← optional (gallery cover, priority 1)
├─ folder.jpg ← optional (gallery cover, priority 2)
├─ ABC-123-fanart.jpg ← optional
├─ landscape.jpg ← optional
└─ extrafanart/ ← REQUIRED, must contain images
├─ backdrop01.jpg
├─ backdrop02.jpg
└─ ...
Supported image extensions: .jpg, .jpeg, .png, .gif, .webp (configurable). .gif files are correctly resolved even though Stash stores them internally as VideoFile visual assets.
Screenshots
Install
Option 1: Download Release
- Go to Releases
- Download the latest
sceneGallerySync-vX.Y.Z.zip - Unzip into your Stash plugins directory (files go directly in the
sceneGallerySyncfolder):- Windows:
%USERPROFILE%\.stash\plugins\sceneGallerySync\ - Linux/macOS:
~/.stash/plugins/sceneGallerySync/
- 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 sceneGallerySync from the list. This is the same unified source that carries Binge (cn), sceneTranslate, and studioTools — one source, install any.
Required runtime
| Dependency | Required | Notes |
|---|---|---|
| nfoSceneParser (fork) | Yes (auto mode only) | Auto-trigger waits for NFO title before syncing metadata. Manual button works without it. |
Python 3.x + requests |
Yes | Stash official Docker image ships both out of the box. Windows: winget install Python.Python.3.12 → pip install requests. |
Companion plugins (mutually beneficial)
| Plugin | Synergy with sceneGallerySync |
|---|---|
| Binge (fork) | Galleries created by this plugin show up as gallery thumbnail previews on Binge scene cards + performer profile backdrops. Recommended to install together. |
| nfoSceneParser (fork) | The reason this plugin waits for a title before attaching metadata. Auto-mode depends on its enabled status. |
| sceneTranslate | Translate scene title/details before gallery sync. Gallery inherits the translated text. |
| studioTools | Merge studios / pull from StashDB → changes cascade into galleries via scene → studio foreign key. |
Tech stack
Pure Python plugin (standard library + requests). Scene.Update.Post hook → one-shot subprocess with start_new_session=True/DETACHED_PROCESS + stdio redirected to prevent pipe inheritance. All data access through Stash GraphQL with built-in retry. Config stored in config.py (no reload needed). Companion 12-line UI inject (jQuery) adds the manual button to the scene edit page. License: MIT.
All 4 plugins (Binge / sceneGallerySync / sceneTranslate / studioTools) share one plugin source — install whichever combination you need.
Feedback, bug reports, and PRs welcome. If you had the v1.5.0 “edit spinner hangs 3 minutes” issue, v1.6.0 should resolve it — give it a whirl and let me know if anything still stalls.
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.
