Stash

Stash is a self‑hosted media organizer written in Go that turns any local collection of adult videos and images into a feature‑rich, web‑based library. From a developer’s perspective it behaves like a lightweight content management system (CMS) with a focus on performance, extensibility and security. The core engine scans directories for media files, extracts or scrapes metadata, stores it in a relational database, and serves the content via an HTTP API that powers both the UI and third‑party integrations.

Technical Stack

• Language & Runtime: Go 1.20+; the entire server is a single statically‑linked binary, making distribution and dependency management trivial.
• Web Framework: Built on the standard net/http package with minimal routing, exposing a RESTful API and a GraphQL endpoint for advanced queries.
• Database: PostgreSQL is the default backend; a lightweight SQLite option exists for single‑user setups. The schema includes tables for scenes, performers, tags, studios and many‑to‑many relationships.
• Media Handling: Uses FFmpeg under the hood for format detection, thumbnail generation and adaptive streaming. The UI streams directly to browsers via HLS/DASH when needed.
• Plugin Architecture: A Go plugin system allows community‑built scrapers and data enrichers to be loaded at runtime. Plugins register callbacks for metadata extraction, tag suggestions and custom API routes.

Core Capabilities

• Metadata Scraping: The plugin ecosystem includes scrapers for major adult sites (e.g., XVideos, Pornhub) that fetch titles, tags, performers and thumbnails.
• Tagging & Filtering: Full‑text search on titles, tags, performers and studios; advanced filter syntax is available via the GraphQL API.
• Markers & Galleries: Users can bookmark scene segments and create image galleries from ZIPs; these are persisted as separate entities linked to scenes.
• Analytics: Built‑in dashboards expose statistics per performer, tag or studio (view counts, rating averages). The data is exposed through REST endpoints for custom reporting tools.
• Security: Operates behind HTTP Basic Auth or JWT; the API supports role‑based access controls for read/write permissions.

Deployment & Infrastructure

Stash is intentionally lightweight: a single binary plus a Docker image (stashapp/stash) runs on any platform that supports Go binaries (Linux, macOS, Windows). Docker images are available for all common architectures and can be orchestrated with docker-compose or Kubernetes. For high‑availability, a multi‑node setup can be achieved by sharing the same PostgreSQL cluster and mounting a shared NFS/SMB volume for media storage. The stateless nature of the API makes horizontal scaling straightforward.

Integration & Extensibility

• Webhooks: External services can subscribe to events (e.g., scene added, tag updated) via configurable webhooks.
• SDKs & Clients: While no official SDK exists, the open GraphQL schema and REST API allow developers to build custom clients in any language.
• Custom Plugins: Go plugins can expose new API routes, modify metadata extraction pipelines or integrate with external services (e.g., Plex, Emby).
• UI Customization: The front‑end is a Vue.js SPA; developers can fork the repository, adjust components or replace the theme without touching the back‑end.

Developer Experience

The project follows a clean GitHub workflow with continuous integration, automated linting and a generous issue tracker. Documentation is hosted on docs.stashapp.cc, covering API usage, plugin development and deployment guides. The community is active on Discord and GitHub Discussions, providing rapid support for integration questions.

Use Cases

• Personal Media Server: Hobbyists who want a private, self‑hosted “PornHub” for their collection.
• Enterprise Archiving: Companies needing a secure, searchable archive of internal media assets.
• Research & Analytics: Data scientists can pull metadata via GraphQL for trend analysis or ML projects.
• Custom Front‑Ends: Developers can build mobile apps, smart TV widgets or integration with existing media centers (Plex, Jellyfin) by consuming Stash’s API.

Advantages

• Performance: Go’s concurrency model delivers fast metadata extraction and low‑latency streaming.
• Simplicity: A single binary, optional Docker image and minimal configuration lower the barrier to entry.
• Extensibility: The plugin system and open APIs let developers tailor the application to niche workflows.
• Licensing: GPL‑licensed, allowing free use and modification for both personal and commercial projects.
• Community: Active contributors and a growing plugin ecosystem mean new features appear regularly without waiting for core releases.

In summary, Stash offers a developer‑friendly platform that combines the ease of deployment with powerful media management features, all backed by an open, extensible architecture.