### Stash Plugin Installation Guide (Bash)

Source: https://context7.com/stashapp/communityscripts/llms.txt

Standard procedure for installing Stash plugins, covering Python dependency installation using pip and the correct directory structure for placing plugin folders within the Stash plugins directory.

```bash
# 1. Install Python dependencies (for Python plugins)
pip install stashapp-tools --upgrade
pip install requests
pip install Send2Trash  # For file deletion plugins

# Or use requirements.txt if provided
pip install -r requirements.txt

# 2. Create plugin folder in Stash plugins directory
# Windows: C:\Users\{username}\.stash\plugins\{PluginName}
# Linux: ~/.stash/plugins/{PluginName}
```

--------------------------------

### Running FileMonitor as Standalone Script (Bash)

Source: https://context7.com/stashapp/communityscripts/llms.txt

This section provides command-line examples for running the FileMonitor script. It covers starting monitoring with a Stash URL, using an API key for authentication, stopping the monitoring process, restarting it as a Stash task, and configuring Docker support with a docker-compose file.

```bash
# Running FileMonitor as standalone script
# Start monitoring with Stash URL
python filemonitor.py --url http://localhost:9999

# With API key for password-protected Stash
python filemonitor.py --url http://localhost:9999 --apikey "your_api_key_here"

# Stop monitoring
python filemonitor.py --stop

# Restart monitoring as Stash task
python filemonitor.py --restart

# Docker support - pass docker-compose file for path mapping
python filemonitor.py --url http://localhost:9999 \
    --docker "/path/to/docker-compose.yml" \
    --apikey "your_api_key_here"

```

--------------------------------

### Install Python Dependencies

Source: https://github.com/stashapp/communityscripts/blob/main/scripts/stash-watcher/README.md

Installs project dependencies listed in the 'requirements.txt' file using pip. Ensure you have a virtual environment activated before running this command.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Dependencies using pip

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/FileMonitor/README.md

Lists the commands to install necessary Python packages for the Stash App community scripts. 'schedule' is required for the scheduler feature.

```bash
pip install -r requirements.txt

# Or manually:
pip install stashapp-tools --upgrade
pip install requests
pip install watchdog
pip install schedule
pip install pyyaml
```

--------------------------------

### Define Game Start JSON Structure

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/chooseYourAdventurePlayer/README.md

This JSON structure defines the properties for a '0.json' file, which serves as the starting point for games in StashApp. It includes fields for game identification, display titles, optional map details, navigation pointers, and user choices.

```json
{
  "id": "0",
  "type": null,
  "title": "Game Start",
  "map": {
    "title": "Demo",
    "description": "Your are viewing a demo of the Choose Your Adventure Player"
  },
  "mapItem": [
    {
      "choice_id": "TBD",
      "title": "TBD",
      "picture": null
    }
  ],
  "skipto": "2",
  "choices": [
    {
      "description": "Good Choice",
      "id": "1a",
      "type": "",
      "photo": null
    },
    {
      "description": "Bad Choice",
      "id": "1b",
      "type": "",
      "photo": null
    }
  ],
  "resource": {
    "resolved_content": "Scene0.mp4"
  }
}
```

--------------------------------

### Basic Path-Based Configuration

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/defaultDataForPath/README.md

This example shows a simple configuration object that applies a specific studio and tag to files located in defined paths. The 'name' field is optional and used for organization. If 'paths' is omitted, no files are matched unless 'children' are used.

```javascript
var jsonData = [
    {
        "name": "OPTIONAL NAME - NOT USED IN SCRIPT",
        "paths": [
            "C:\\Users\\UserName\\Desktop\\NOTPORN\\Brazzers",
            "D:\\SecretStorage\\Porn\\Brazzers"
        ],
        "studio": "Brazzers",
        "tags": [
            "Default_Data_For_Path_Tagged"
        ]
    }
];
```

--------------------------------

### Theme Manifest Example (Theme-Pulsar.yml)

Source: https://context7.com/stashapp/communityscripts/llms.txt

Example of a theme manifest file for Stash, defining theme name, version, and associated CSS files. This file acts as a descriptor for custom themes.

```yaml
name: Theme - Pulsar
description: Plex Theme for Stash by Fonzie 2020-21
version: 1.8.1
url: https://discourse.stashapp.cc/t/pulsar/1429
ui:
  css:
    - Theme-Pulsar.css
```

--------------------------------

### nfoSceneParser.json Regex Configuration Example

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/nfoSceneParser/README.md

This JSON configuration file defines a regular expression pattern for parsing media file names or paths. It includes optional 'splitter' and 'scope' attributes to refine how the regex is applied and how matched data is processed.

```json
{
  "regex": "^(?<title>.+?)\\s*\\(\\d{4}\\)",
  "splitter": ",",
  "scope": "filename"
}
```

--------------------------------

### Hot Cards Configuration Examples (Stash UI)

Source: https://context7.com/stashapp/communityscripts/llms.txt

Examples of configuring 'Hot Cards' in the Stash UI for visual highlighting. These configurations use tag or rating criteria combined with styling and gradient options.

```yaml
# Hot Cards configuration format in Stash UI
# Format: [criterion]_[value]_[style]_[gradient-opts]_[hover-opts]_[card-opts]

# Simple tag-based gold styling
t_123_gold

# Rating-based with custom threshold
r_4_hot

# Fixed color with hover effect
r_4_white__#5ff1a1_false

# Multi-tag with different styles
t_111,116,78,87/105_pink,red,white/orange,white_/,70deg,4s alternate infinite

# Rating tiers with style presets
r_5/4.2/3.7_gold/hot/default___//,50

# Animated gradient
_67_pink,red,yellow,green,blue_,30deg,5s ease infinite_red,1s ease-in-out infinite_,100
```

--------------------------------

### DupFileManager Configuration Example (Python)

Source: https://context7.com/stashapp/communityscripts/llms.txt

This Python dictionary defines the configuration settings for the DupFileManager script. It includes preferences for tagging duplicates, path handling, comparison criteria, codec ranking, and deletion behavior. These settings control how the script identifies and manages duplicate files.

```python
config = {
    # Tag used to mark duplicates for deletion
    "DupFileTag": "DuplicateMarkForDeletion",

    # Path preferences for duplicate resolution
    # Files in whitelist paths are never deleted
    # Files in blacklist paths are preferred deletion candidates
    "listSeparator": ",",

    # Comparison preferences
    "favorLongerFileName": True,
    "favorLargerFileSize": True,
    "favorHighBitRate": True,
    "favorHigherFrameRate": True,
    "favorCodecRanking": True,

    # Codec ranking by efficiency (first = best)
    "codecRankingSet1": [
        "h266", "vvc", "av1", "h265", "hevc",
        "vp9", "h264", "avc", "vp8", "mpeg4"
    ],

    # Processing options
    "permanentlyDelete": False,  # Move to trash instead
    "cleanAfterDel": True,       # Run cleanup after deletion
    "skipIfTagged": False,       # Process already-tagged scenes

    # Threshold for significant duration difference
    "significantTimeDiff": 0.90,  # 90% threshold
}

```

--------------------------------

### Scene Metadata from Scene NFO Example

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/nfoSceneParser/README.md

This XML snippet illustrates the structure of an NFO file for an individual scene, utilizing the `<set>` tag to associate it with a larger movie or collection. It includes tags for scene title, plot, cover art, studio, and set information.

```xml
<movie>
  <title>BestSceneEver</title>
  <plot>Scene of the century</plot>
  <thumb aspect="landscape">https://scene_cover.jpg</thumb>
  <studio>Best studio ever</studio>
  <set>
    <name>My Movie Title</name>
    <index>2</index>
  </set>
  </movie>
```

--------------------------------

### Custom Icon Definition Example (JavaScript)

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/externalLinksEnhanced/README.md

An example of how to define a custom icon for an external link within the plugin's configuration. This JSON structure specifies the site name, the icon file to use, and the addresses associated with the site for link detection.

```javascript
{
    name: "sitename",
    icon: "myicon.png",
    addresses: ["mysitename.com"]
}
```

--------------------------------

### JavaScript Example: Specific Studio Folders with Scenes

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/pathParser/README.md

This JavaScript example demonstrates a Path Parser rule for matching specific studio folders and extracting the filename as the scene title. It uses an array pattern to match multiple studio names and a null pattern for the filename. The '#0' and '#1' syntax references captured groups from the patterns.

```javascript
{
  name: 'Studio/Scene',
  pattern: [
    ['Specific Studio', 'Another Studio'], // A specific studio name
    null // Any filename
  ],
  fields: {
    title: '#1', // 1 refers to the second pattern (filename)
    studio: '#0' // 0 refers to the first pattern (folder)
  }
}
```

--------------------------------

### Movie Metadata from folder.nfo Example

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/nfoSceneParser/README.md

This XML snippet demonstrates the structure of a folder.nfo file, used to define metadata for all scene files within the same directory. It includes tags for movie title, plot, cover art, studio, and director.

```xml
<movie>
  <title>My Movie Title</title>
  <plot>You have to see it to believe it...</plot>
  <thumb aspect="poster">https://front_cover.jpg</thumb>
  <thumb aspect="poster">https://back_cover.jpg</thumb>
  <studio>Best studio ever</studio>
  <director>Georges Lucas</director>
</movie>
```

--------------------------------

### nfoSceneParser.json Configuration Example

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/nfoSceneParser/README.md

This JSON configuration defines the regular expression and settings for parsing movie file paths and names. It uses capturing groups to extract specific metadata like movie, studio, performers, and title from file paths.

```json
{
  "regex": "^.*[/\\](?P<movie>.*?)[/\](?P<studio>.*?) - (?P<performers>.*?) - (?P<title>.*?)[-]+.*\\.mp4$",
  "splitter": ", ",
  "scope": "path"
}
```

--------------------------------

### Build and Run Stash Watcher with Docker Compose

Source: https://github.com/stashapp/communityscripts/blob/main/scripts/stash-watcher/README.md

Builds the Docker image for Stash Watcher and starts the service in detached mode using Docker Compose. This command assumes a 'docker-compose.yml' file is present in the current directory.

```bash
docker compose up -d --build
```

--------------------------------

### Hierarchical Configuration with Inheritance

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/defaultDataForPath/README.md

This example demonstrates a hierarchical configuration structure where parent objects define settings (like studio or tags) that are inherited by their children. This allows for more organized and efficient configuration by avoiding repetition. If a parent object also has a 'paths' value, those settings apply directly to files in that path, overriding child inheritance for that specific path.

```javascript
var jsonData = [
	{
		"name": "Default Tag - Matches all scanned files",
		"paths": [
			""
		],
		"tags": [
			"ORGANIZED - Unorganized"
		]
	},
    	{
		"name": "Instagram Root",
        	"studio": "Instagram",
		"children": [
			{
				"name": "Celebrities",
				"tags": [
					"PERFORMER - Celebrity"
				],
				"children": [
					{
						"name": "Kim Kardashian",
						"paths": [
							"C:\\Users\\UserName\\Desktop\\Instagram\\kimkardashian"
						],
						"performers": [
							"Kim Kardashian"
						],
						"tags": [
							"PERFORMER - Armenian",
							"PERFORMER - Big Ass"
						]
					},
					{
						"name": "Katy Perry",
						"paths": [
							"C:\\Users\\UserName\\Desktop\\Instagram\\katyperry"
						],
						"performers": [
							"Katy Perry"
						],
						"tags": [
							"PERFORMER - Caucasian,
							"PERFORMER - Big Tits"
						]
					}
				]
			},
			{
				"name": "Pornstars",
				"tags": [
					"PERFORMER - Pornstar
				],
				"children": [
					{
						"name": "Alexis Fawx",
						"paths": [
							"C:\\Users\\UserName\\Desktop\\Instagram\\alexisfawx"
						],
						"performers": [
							"Alexis Fawx"
						],
						"tags": [
							"PERFORMER - Caucasian",
							"PERFORMER - Fake Tits"
						]
					}
				]
			}
		]
	}
```

--------------------------------

### Install Python Requirements for Stash Plugin

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/PlexSync/README.md

Installs necessary Python packages for the Stash plugin. It can install requirements from a local file or globally. Ensure you have Python 3 and pip installed.

```bash
python3 -m pip install -r requirements.txt -t .
python3 -m pip install stashapi unidecode requests
```

--------------------------------

### Ensure Python Package Import with Version Constraint

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/PythonDepManager/README.md

Ensures a Python package is installed and available for import, with support for specific version constraints. This function handles checking for existing installations and installing new packages if necessary. It can be used for basic imports or with custom import names.

```python
from PythonDepManager import ensure_import

# Install and import a package with specific version
ensure_import("requests==2.26.0")

# Afterwards imports will use only the requested versions
import requests
```

```python
from PythonDepManager import ensure_import

# Define a minimum version to use. This will either use any cached version
# which matches or install the latest
ensure_import("requests>=2.26.0")
```

```python
from PythonDepManager import ensure_import

# Install beautifulsoup4 but import as bs4
ensure_import("bs4:beautifulsoup4==4.9.3")
```

```python
from PythonDepManager import ensure_import

# Install stashapp-tools but import as stashapi
ensure_import("stashapi:stashapp-tools==0.2.58")
```

```python
from PythonDepManager import ensure_import

# Install from a Git repository
ensure_import("stashapi@git+https://github.com/user/repo.git")

# Install specific branch/tag
ensure_import("stashapi@git+https://github.com/user/repo.git@main")

# Install specific commit
ensure_import("stashapi@git+https://github.com/user/repo.git@ad483dc")
```

```python
from PythonDepManager import ensure_import

ensure_import(
  "requests",
  "bs4:beautifulsoup4==4.9.3",
  "stashapi:stashapp-tools==0.2.58",
  "someothermodule>=0.1",
)
```

--------------------------------

### Install DupFileManager Plugin for Stash

Source: https://context7.com/stashapp/communityscripts/llms.txt

This script installs the DupFileManager plugin by creating a directory and copying plugin files into the Stash plugins folder. It assumes the plugin files are located in the 'plugins/DupFileManager/' directory.

```bash
mkdir -p ~/.stash/plugins/DupFileManager
cp -r plugins/DupFileManager/* ~/.stash/plugins/DupFileManager/
```

--------------------------------

### Install Python Libraries for Star Identifier

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/starIdentifier/README.md

Installs the necessary Python libraries for the Star Identifier script, including numpy, dlib, and face_recognition. These libraries are essential for the facial recognition functionality.

```bash
pip install numpy dlib face_recognition
```

--------------------------------

### Configure Multiple Stash Docker Instances in filemonitor_config.py

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/FileMonitor/README.md

This Python code snippet demonstrates how to configure the 'dockers' field in the filemonitor_config.py file to manage multiple Stash Docker instances. It includes examples for basic configuration, multiple bind mounts, and instances requiring an API key. Each entry requires GQL URL, apiKey, and bindMounts.

```python
    # Docker notification from host machine
    "dockers": [
        # A simple basic example with only one bind mount path.
        {"GQL":"http://localhost:9995", "apiKey":"", "bindMounts":[{r"C:\\Video":"/mnt/Video"}]},

        # Example having 8 bind mount paths.
        {"GQL":"http://localhost:9997", "apiKey":"", "bindMounts":[
                {r"C:\\Users\\admin3\\AppData\\Local\\Docker\\wsl\\ManyMnt\\data":"/data"},
                {r"C:\\Users\\admin3\\Videos":"/external"},
                {r"C:\\Users\\admin3\\Pictures":"/external2"},
                {r"C:\\Users\\admin3\\Downloads":"/external3"},
                {r"E:\\Downloads":"/external4"},
                {r"E:\\Celeb":"/external5"},
                {r"F:\\Hentai":"/external6"},
                {r"Z:\\Temp":"/external7"},
            ]
        },

        # Example using the apiKey for a password configured Stash installation.
        {"GQL":"http://localhost:9994", "apiKey":"eyJhb3676zgdUzI1NiIsInR5cCI6IwfXVCJ9.ewJ1aWQiOiJheHRlweIsInN1YiI6IkFQSUtleSIsImlhdewrweczNDU0MDk3N30.4nZVLk3xikjJZfZ0JTPA_Fic8JvFx3DZe5U21Zasdag", "bindMounts":[
                {r"C:\\Users\\admin3\\AppData\\Local\\Docker\\wsl\\MyStashContainer\\data":"/data"},
                {r"C:\\Vid":"/mnt/Vid"},
                {r"C:\\Users\\admin3\\Downloads":"/mnt/Downloads"},
            ]
        },
    ],
```

--------------------------------

### Path Parser Configuration Examples (JavaScript)

Source: https://context7.com/stashapp/communityscripts/llms.txt

Defines rules for parsing file paths to extract scene metadata. Supports simple string matching, regex patterns, and custom JavaScript functions for complex parsing logic. Outputs are mapped to fields like title, studio, and performers.

```javascript
// pathParser_config.js - Rule configuration examples
const rules = [
  // Simple studio/scene pattern
  {
    name: 'Studio/Scene',
    pattern: [
      ['Specific Studio', 'Another Studio'],  // Match specific studios
      null  // Any filename
    ],
    fields: {
      title: '#1',   // Use filename (index 1)
      studio: '#0'   // Use folder name (index 0)
    }
  },

  // Regex pattern for movie with year
  {
    name: 'Studio/Movie (YEAR)/Scene - Episode #',
    pattern: [
      null,                        // Any studio folder
      /(.+) \(\d{4}\)/,           // Movie Title (2022)
      /(.+) - Episode (\d+)/      // Scene - Episode 1
    ],
    fields: {
      title: '#2',        // Scene title from filename
      studio: '#0',       // Studio from first folder
      movie_title: '#1',  // Movie title from regex group
      scene_index: '#3'   // Episode number from regex group
    }
  },

  // Function-based pattern for complex parsing
  {
    name: 'Studio/Scene.Performers.S##E##',
    pattern: [
      null,
      function (path) {
        var parts = path.split('.');
        var performers = parts[1].split('&')
          .map(p => p.trim())
          .join(',');
        var series = /S(\d{2})E(\d{2})/ .exec(parts[2]);
        return [parts[0], performers, parseInt(series[1]), parseInt(series[2])];
      }
    ],
    fields: {
      title: '#1',
      studio: '#0',
      performers: '#2',
      movie_title: '#1 - Season #3',
      scene_index: '#4'
    }
  }
];

// Example input: X:\Prime\The Boys.Karl Urban & Jack Quaid.S06E09.mp4
// Output:
//   title: "The Boys"
//   studio: "Prime"
//   performers: "Karl Urban,Jack Quaid"
//   movie_title: "The Boys - Season 6"
//   scene_index: "9"

```

--------------------------------

### Implement Multi-Scene Choices with Fragments

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/chooseYourAdventurePlayer/README.md

This JSON structure demonstrates how to implement multi-scene choices using the 'fragments' property, which replaces the single 'resource' property. Each fragment can contain multiple actions, allowing for more complex user interactions and repeatable scene elements.

```json
{
  "id": "2",
  "type": null,
  "title": "Action choice",
  "fragments": [
    {
      "id": "frag-a",
      "photo": {
        "id": "frag-a_photo",
        "content": "frag-a.jpg"
      },
      "video": {
        "id": "frag-a_video",
        "resolved_content": "Scene2A.mp4"
      },
      "actions": [
        {
          "id": "frag-a-action-a",
          "photo": {
            "id": "frag-a-action-a_photo",
            "content": "frag-a-action-a.jpg"
          },
          "video": {
            "id": "frag-a-action-a_video",
            "resolved_content": "Scene2A-1.mp4"
          },
          "title": "TBD"
        },
        {
          "id": "frag-a-action-b",
          "photo": {
            "id": "frag-a-action-b_photo",
            "content": "frag-a-action-b.jpg"
          },
          "video": {
            "id": "frag-a-action-b_video",
            "resolved_content": "Scene2A-1.mp4"
          },
          "title": "TBD"
        }
      ],
      "title": "TBD"
    },
    {
      "id": "frag-b",
      "photo": {
        "id": "frag-b_photo",
        "content": "frag-b.jpg"
      },
      "video": {
        "id": "frag-b_video",
        "resolved_content": "Scene2B.mp4"
      },
      "actions": null,
      "title": "TBA",
      "subtitles": "Scene3-08"
    }
  ],
  "skipto": null,
  "choices": [
    {
      "description": null,
      "id": "2-e",
      "type": "end",
      "photo": "TBD"
    }
  ],
  "resource": {
    "id": "empty",
    "resolved_content": null
  }
}
```

--------------------------------

### JavaScript Example: Studio with Movie Sub-folder and Scenes

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/pathParser/README.md

This JavaScript example shows a Path Parser rule for complex file paths including studio, movie sub-folder (with year), and scene information. It utilizes regular expressions to capture movie titles and scene details, referencing captured groups using '#index' in the fields to update scene metadata.

```javascript
{
  name: 'Studio/Movie (YEAR)/Scene - Scene #',
  pattern: [
    null, // Any studio name
    /(.+) \(\d{4}\)/, // A sub-folder with 'Movie Title (2022)'
    /(.+) - \w+ ({d})/,
  ],
  fields: {
    title: '#2',
    studio: '#0',
    movie_title: '#1',
    scene_index: '#3'
  }
}
```

--------------------------------

### Configure Local VLM Endpoint (Python)

Source: https://github.com/stashapp/communityscripts/blob/main/plugins/AHavenVLMConnector/README.md

Example configuration for a local VLM endpoint using LM Studio. This Python dictionary specifies the base URL, API key (if required), a name for the endpoint, its processing weight, and whether it serves as a fallback. It's crucial for setting up communication with local VLM services.

```python
{
    "base_url": "http://localhost:1234/v1",  # LM Studio default
    "api_key": "",                          # API key not required
    "name": "lm-studio-local",
    "weight": 5,
    "is_fallback": False
}
```