traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Netgrimoire/Stash-Management.md
Administrator de786b5b48 docs: create Stash-Management
2026-02-18 13:09:06 +00:00

14 KiB
Raw Blame History

title description published date tags editor dateCreated
Stashapp Workflow true 2026-02-18T13:08:53.604Z markdown 2026-02-18T13:08:53.604Z

StashApp: Automated Library Management with Community Scrapers

Goal: Automatically identify, tag, rename, and organize your media library with minimal manual intervention using StashDB, ThePornDB, and the CommunityScrapers repository.

Table of Contents

  1. Prerequisites
  2. Installing CommunityScrapers
  3. Configuring Metadata Providers
  4. Configuring Your Library
  5. Automated File Naming & Moving
  6. The Core Workflow
  7. Handling ABMEA & Amateur Content
  8. Automation with Scheduled Tasks
  9. Tips & Troubleshooting

1. Prerequisites

Before starting, make sure you have:

  • StashApp installed and running — see the official install docs
  • Git installed on your system (needed to clone the scrapers repo)
  • A ThePornDB account — free tier available at metadataapi.net
  • A StashDB account — requires a community invite; request one on the Discord
  • Your Stash config directory noted — default locations:
OS Default Path
Windows %APPDATA%\stash
macOS ~/.stash
Linux ~/.stash
Docker /root/.stash

2. Installing CommunityScrapers

The CommunityScrapers repository contains scrapers for hundreds of sites maintained by the Stash community. This is the primary source for site-specific scrapers including ABMEA.

Step 1 — Navigate to your Stash config directory

cd ~/.stash

Step 2 — Create a scrapers directory if it doesn't exist

mkdir -p scrapers
cd scrapers

Step 3 — Clone the CommunityScrapers repository

git clone https://github.com/stashapp/CommunityScrapers.git

This creates ~/.stash/scrapers/CommunityScrapers/ containing all available scrapers.

Step 4 — Verify Stash detects the scrapers

  1. Open Stash in your browser (default: http://localhost:9999)
  2. Go to Settings → Metadata Providers → Scrapers
  3. Click Reload Scrapers
  4. You should now see a long list of scrapers including entries for ABMEA, ManyVids, Clips4Sale, etc.

Step 5 — Keep scrapers updated

Since community scrapers are actively maintained, set up a periodic update:

cd ~/.stash/scrapers/CommunityScrapers
git pull

💡 Tip: You can automate this with a cron job or scheduled task. See Section 8.

Installing Python Dependencies (if prompted)

Some scrapers require Python packages. If you see scraper errors mentioning missing modules:

pip install requests cloudscraper py-cord lxml

3. Configuring Metadata Providers

Stash uses metadata providers to automatically match scenes by fingerprint (phash/oshash). This is what enables true automation — no filename matching required.

3.1 StashDB

StashDB is the official community-run fingerprint and metadata database. It is the most reliable source for mainstream and studio content.

  1. Go to Settings → Metadata Providers
  2. Under Stash-Box Endpoints, click Add
  3. Fill in:
    • Name: StashDB
    • Endpoint: https://stashdb.org/graphql
    • API Key: (generate this from your StashDB account → API Keys)
  4. Click Confirm

3.2 ThePornDB (TPDB)

TPDB aggregates metadata from a large number of sites and is especially useful for amateur, clip site, and ABMEA content that may not be on StashDB.

  1. Log in at metadataapi.net and go to your API Settings to get your key
  2. In Stash, go to Settings → Metadata Providers
  3. Under Stash-Box Endpoints, click Add
  4. Fill in:
    • Name: ThePornDB
    • Endpoint: https://theporndb.net/graphql
    • API Key: (your TPDB API key)
  5. Click Confirm

Provider Priority Order

Set your identify task to query providers in this order for best results:

  1. StashDB — highest quality, community-verified
  2. ThePornDB — broad coverage including amateur/clip sites
  3. CommunityScrapers (site-specific) — for anything not matched above

4. Configuring Your Library

Adding Library Paths

  1. Go to Settings → Library
  2. Under Directories, click Add and point to your media folders
  3. You can add multiple directories (e.g., separate drives or folders)

⚠️ Do not set your organized output folder as a source directory. Keep source and destination separate until you are confident in your setup.

Recommended Directory Structure

/media/
├── stash-incoming/       ← Source: where new files land
└── stash-library/        ← Destination: where Stash moves organized files
    ├── Studios/
    │   └── ABMEA/
    └── Amateur/

5. Automated File Naming & Moving

This is the section that does the heavy lifting. Stash will rename and move files only when a scene is marked as Organized, which gives you a review gate before anything is touched.

Enable File Moving

  1. Go to Settings → Library
  2. Enable "Move files to organized folder on organize"
  3. Set your Organized folder path (e.g., /media/stash-library)

Configure the File Naming Template

Still in Settings → Library, set your Filename template. These use Go template syntax with Stash variables.

Recommended template for mixed studio/amateur libraries:

{studio}/{date} {title}

For performer-centric amateur libraries:

{performers}/{studio}/{date} {title}

Full example with fallbacks:

{{if .Studio}}{{.Studio.Name}}{{else}}Unknown{{end}}/{{if .Date}}{{.Date}}{{else}}0000-00-00{{end}} {{.Title}}

Available Template Variables

Variable Example Output
{title} Scene Title Here
{date} 2024-03-15
{studio} ABMEA
{performers} Jane Doe
{resolution} 1080p
{duration} 00-32-15
{rating} 5

💡 If a field is empty (e.g., no studio), Stash skips that path segment. Test with a few scenes before running on your whole library.

6. The Core Workflow

Follow these steps in order every time you add new content. This is the automated pipeline.

New Files → Scan → Generate Fingerprints → Identify → Review → Organize (Move + Rename)

Step 1 — Scan

Tasks → Scan

  • Discovers new files and adds them to the database
  • Does not move or rename anything yet
  • Options to enable: Generate covers on scan

Step 2 — Generate Fingerprints

Tasks → Generate

Select these options:

Option Purpose
✅ Phashes Used for fingerprint matching against StashDB/TPDB
✅ Checksums (MD5/SHA256) Used for duplicate detection
✅ Previews Thumbnail previews in the UI
✅ Sprites Timeline scrubber images

⏳ This step is CPU/GPU intensive. Let it complete before proceeding. On a large library, this may take hours.

Step 3 — Identify (Auto-Scrape by Fingerprint)

Tasks → Identify

This is the magic step. Stash sends your file fingerprints to StashDB and TPDB and pulls back metadata automatically.

Configure the task:

  1. Click Add Source and add StashDB first
  2. Click Add Source again and add ThePornDB
  3. Under Options, enable:
    • ✅ Set cover image
    • ✅ Set performers
    • ✅ Set studio
    • ✅ Set tags
    • ✅ Set date
  4. Click Identify

Stash will now automatically match and populate metadata for any scene it recognizes by fingerprint.

Step 4 — Auto Tag (Filename-Based Fallback)

For scenes that didn't match by fingerprint (common with amateur content), use Auto Tag to extract metadata from filenames.

Tasks → Auto Tag

  • Matches Performers, Studios, and Tags from filenames against your existing database entries
  • Works best when filenames contain names (e.g., JaneDoe_SceneTitle_1080p.mp4)

Step 5 — Review Unmatched Scenes

Filter to find scenes that still need attention:

  1. Go to Scenes
  2. Filter by: Organized = false and Studio = none (or Performers = none)
  3. Use the Tagger view (icon in top right of Scenes) for rapid URL-based scraping

In Tagger view:

  • Paste the original source URL into the scrape field
  • Click Scrape — Stash fills in all metadata from that URL
  • Review and click Save

Step 6 — Organize (Move & Rename)

Once you're satisfied with a scene's metadata:

  1. Open the scene
  2. Click the Organize button (checkmark icon), OR
  3. Use bulk organize: select multiple scenes → Edit → Mark as Organized

When a scene is marked Organized, Stash will:

  • ✅ Rename the file according to your template
  • ✅ Move it to your organized folder
  • ✅ Update the database path

⚠️ This action cannot be easily undone at scale. Always verify metadata on a small batch first.

7. Handling ABMEA & Amateur Content

ABMEA and amateur clips often lack fingerprint matches. Use these additional strategies:

ABMEA-Specific Scraper

The CommunityScrapers repo includes an ABMEA scraper. To use it manually:

  1. Open a scene in Stash
  2. Click Edit → Scrape with → ABMEA
  3. If the scene URL is known, enter it; otherwise the scraper will search by title

Batch URL Scraping Workflow for ABMEA

If you have many files sourced from ABMEA:

  1. Before ingesting files, rename them to include the ABMEA scene ID in the filename if possible (e.g., ABMEA-0123_title.mp4)
  2. After scanning, go to Tagger View
  3. Filter to unmatched scenes and paste ABMEA URLs one by one

Amateur Content Without a Source Site

For truly anonymous amateur clips:

  1. Create a Studio entry called Amateur (or more specific names like Amateur - Reddit)
  2. Create Performer entries for recurring people you can identify
  3. Use Auto Tag to match these once entries exist
  4. Use tags liberally to compensate for missing structured metadata: amateur, homemade, POV, etc.

Tag Hierarchy Recommendation

Set up tag parents in Settings → Tags to create a browsable hierarchy:

Content Type
├── Amateur
├── Professional
└── Compilation

Source
├── ABMEA
├── Clip Site
└── Unknown

Quality
├── 4K
├── 1080p
└── SD

8. Automation with Scheduled Tasks

Minimize manual steps by scheduling recurring tasks.

Setting Up Scheduled Tasks in Stash

Go to Settings → Tasks → Scheduled Tasks and create:

Task Schedule Purpose
Scan Every 6 hours Pick up new files automatically
Generate (Phashes only) Every 6 hours Fingerprint new files
Identify Daily at 2am Match new fingerprinted files
Auto Tag Daily at 3am Filename-based fallback tagging
Clean Weekly Remove missing files from database

Auto-Update CommunityScrapers (Linux/macOS)

Add to your crontab (crontab -e):

# Update CommunityScrapers every Sunday at midnight
0 0 * * 0 cd ~/.stash/scrapers/CommunityScrapers && git pull

Auto-Update CommunityScrapers (Windows)

Create a scheduled task in Task Scheduler running:

cd C:\Users\YourUser\.stash\scrapers\CommunityScrapers; git pull

9. Tips & Troubleshooting

Scraper not appearing in Stash

  • Go to Settings → Metadata Providers → Scrapers and click Reload Scrapers
  • Check that the .yml scraper file is in a subdirectory of your scrapers folder
  • Check Stash logs (Settings → Logs) for scraper loading errors

Identify finds no matches

  • Confirm phashes were generated (check scene details — phash should be populated)
  • Confirm your StashDB/TPDB API keys are correctly entered and not expired
  • The file may simply not be in either database — proceed to manual URL scraping

Files not moving after marking as Organized

  • Confirm "Move files to organized folder" is enabled in Settings → Library
  • Confirm the organized folder path is set and the folder exists
  • Check that Stash has write permissions to both source and destination

Duplicate files

Run Tasks → Clean → Find Duplicates before organizing to avoid moving duplicates into your library. Stash uses phash to find visual duplicates even if filenames differ.

Metadata keeps getting overwritten

In Settings → Scraping, set the Scrape behavior to If not set instead of Always to prevent already-populated fields from being overwritten during re-scrapes.

Useful Stash Plugins

Install via Settings → Plugins → Browse Available Plugins:

Plugin Purpose
Performer Image Cleanup Remove duplicate performer images
Tag Graph Visualize tag relationships
Duplicate Finder Advanced duplicate management
Stats Library analytics dashboard

Quick Reference Checklist

Use this checklist every time you add new content:

[ ] Drop files into stash-incoming directory
[ ] Tasks → Scan
[ ] Tasks → Generate → Phashes + Checksums
[ ] Tasks → Identify (StashDB → TPDB)
[ ] Tasks → Auto Tag
[ ] Review unmatched scenes in Tagger View
[ ] Manually scrape remaining unmatched scenes by URL
[ ] Spot-check metadata on a sample of scenes
[ ] Bulk select reviewed scenes → Mark as Organized
[ ] Verify a few files moved and renamed correctly
[ ] Done ✓

Last updated: February 2026 | Stash version compatibility: 0.25+ Community resources: Stash Discord | GitHub | Wiki