docs: create Stash-Management

2026-02-18 13:09:06 +00:00 · 2026-02-18 13:09:06 +00:00 · de786b5b48
commit de786b5b48
parent 4e5a4711dd
1 changed files with 453 additions and 0 deletions
--- a/Stash-Management.md
+++ 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)*