Netgrimoire/Stash-Management.md

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