traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: create Stash-Management

Browse source
This commit is contained in:
Administrator 2026-02-18 13:09:06 +00:00 • committed by John Smith
parent 4e5a4711dd
commit de786b5b48
1 changed files with 453 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

453
Stash-Management.md Normal file
View file

@ -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)*