StashDB & Adult Metadata

StashDB Integration & Adult Metadata

Freak-Flix provides specialized support for adult content libraries by integrating with StashDB. This integration transforms raw video files into a rich, searchable database with professional-grade metadata, performer biographies, and automated categorization.

⚙️ Configuration

To enable adult metadata fetching, you must configure your StashDB credentials within the application settings.

1. Enable Adult Content: Navigate to Settings > Advanced and toggle Enable Adult Content. This unlocks the adult-specific UI components and metadata providers.
2. Set Endpoint: By default, the app points to https://stashdb.org/graphql. If you use a custom instance or a local proxy, update the StashDB Endpoint field.
3. API Key: Obtain your API key from your StashDB account settings and enter it into the StashDB API Key field.

🛡️ Privacy & Segregation

Freak-Flix is designed with privacy in mind. When adult content is enabled:

• Hidden UI Toggles: Use the master toggle in settings to instantly hide or show adult libraries across the entire application.
• Isolated Databases: Metadata retrieved from StashDB is stored with specific flags to ensure it does not mix with "General" (TMDB/AniList) content in "Continue Watching" or "Recently Added" lists unless explicitly toggled on.

✨ Features

Performer Profiles

When a video is matched via StashDB, Freak-Flix automatically generates detailed performer profiles.

• Biographies: Fetches age, measurements, and career history.
• Known For: Automatically compiles a "Known For" list based on your local library, allowing you to discover other scenes featuring the same performer.
• Actor Images: Downloads high-quality headshots for the library's actor gallery.

Smart Tagging & Genres

StashDB uses a robust tagging system. Freak-Flix maps these tags into its internal Genre system.

• Automated Organization: Tags like "POV," "Outdoor," or "4K" are imported as genres, allowing you to filter your library using the standard Netflix-style category rows.
• Studio Metadata: Detailed studio information, including parent companies and logos, is fetched to help organize content by production house.

🛠️ Technical Reference: Stash Proxy

For Web and Cloud deployments, Freak-Flix utilizes a Netlify function (or Hono backend proxy) to handle GraphQL requests. This bypasses Cross-Origin Resource Sharing (CORS) restrictions and secures your API key.

Proxy Request Structure

If you are developing a custom frontend or modifying the network layer, the proxy expects the following:

Endpoint: /.netlify/functions/stash_proxy
Method: POST

Headers: | Key | Value | Description | | :--- | :--- | :--- | | Content-Type | application/json | Required for GraphQL payloads. | | ApiKey | YOUR_STASHDB_KEY | Your personal StashDB API key. |

Example Request:

const response = await fetch('/.netlify/functions/stash_proxy', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'ApiKey': '12345678-abcd-efgh-ijkl-1234567890ab'
  },
  body: JSON.stringify({
    query: `query FindScene($id: ID!) { findScene(id: $id) { title details date } }`,
    variables: { id: "scene-uuid-here" }
  })
});

const data = await response.json();

Internal Scraper Logic

The internal library scanner performs the following steps during an adult content scan:

1. Hash/Filename Match: Queries StashDB using the file's fingerprint or cleaned filename.
2. Metadata Mapping: Maps Scene objects to the local Video schema.
3. Performer Sync: For every performer ID found in the scene, the app executes a secondary query to fetch full bio data and images.
4. Tag Injection: Iterates through StashDB tags and injects them into the local SQLite database as searchable genre entities.