From de786b5b48ecea2b37124713e973a99557803f6d Mon Sep 17 00:00:00 2001 From: Administrator Date: Wed, 18 Feb 2026 13:09:06 +0000 Subject: [PATCH] docs: create Stash-Management --- Stash-Management.md | 453 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 453 insertions(+) create mode 100644 Stash-Management.md diff --git a/Stash-Management.md b/Stash-Management.md new file mode 100644 index 0000000..5f96b30 --- /dev/null +++ b/Stash-Management.md @@ -0,0 +1,453 @@ +--- +title: Stashapp Workflow +description: +published: true +date: 2026-02-18T13:08:53.604Z +tags: +editor: markdown +dateCreated: 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](#1-prerequisites) +2. [Installing CommunityScrapers](#2-installing-community-scrapers) +3. [Configuring Metadata Providers](#3-configuring-metadata-providers) + - [StashDB](#31-stashdb) + - [ThePornDB (TPDB)](#32-theporndbtpdb) +4. [Configuring Your Library](#4-configuring-your-library) +5. [Automated File Naming & Moving](#5-automated-file-naming--moving) +6. [The Core Workflow](#6-the-core-workflow) +7. [Handling ABMEA & Amateur Content](#7-handling-abmea--amateur-content) +8. [Automation with Scheduled Tasks](#8-automation-with-scheduled-tasks) +9. [Tips & Troubleshooting](#9-tips--troubleshooting) + +--- + +## 1. Prerequisites + +Before starting, make sure you have: + +- **StashApp installed and running** — see the [official install docs](https://github.com/stashapp/stash/wiki/Installation) +- **Git installed** on your system (needed to clone the scrapers repo) +- **A ThePornDB account** — free tier available at [metadataapi.net](https://metadataapi.net) +- **A StashDB account** — requires a community invite; request one on [the Discord](https://discord.gg/2TsNFKt) +- 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](https://github.com/stashapp/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 + +```bash +cd ~/.stash +``` + +### Step 2 — Create a scrapers directory if it doesn't exist + +```bash +mkdir -p scrapers +cd scrapers +``` + +### Step 3 — Clone the CommunityScrapers repository + +```bash +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: + +```bash +cd ~/.stash/scrapers/CommunityScrapers +git pull +``` + +> 💡 **Tip:** You can automate this with a cron job or scheduled task. See [Section 8](#8-automation-with-scheduled-tasks). + +### Installing Python Dependencies (if prompted) + +Some scrapers require Python packages. If you see scraper errors mentioning missing modules: + +```bash +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](https://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`): + +```bash +# 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: + +```powershell +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](https://discord.gg/2TsNFKt) | [GitHub](https://github.com/stashapp/stash) | [Wiki](https://github.com/stashapp/stash/wiki)*