Filename Parsing Logic

Overview

Freak-Flix employs an automated parsing engine designed to transform unstructured filenames into clean, searchable metadata. This process is essential for matching your local or cloud-based files with external providers like TMDB, AniList, and StashDB.

The logic operates in three primary stages: Cleaning (Sanitization), Tokenization, and Pattern Matching.

Metadata Extraction logic

1. Movie Parsing

For standalone films, the parser looks for a title followed by a four-digit year.

• Format Requirement: Title (Year).extension or Title Year.extension
• Logic: The engine extracts the string preceding the year as the "Search Title" and uses the year to filter TMDB results for higher accuracy.

Example:

• Input: The.Batman.2022.2160p.MA.WEB-DL.DDP5.1.Atmos.DV.HEVC-CMRG.mkv
• Parsed Output:
  • Title: The Batman
  • Year: 2022
  • Search Query: The Batman

2. TV Show & Anime Parsing

For episodic content, the parser prioritizes Season and Episode (SxxExx) notation or absolute episode numbering.

• Standard TV: Searches for S[0-9]E[0-9] patterns.
• Anime: Searches for absolute numbering (e.g., [01], - 01) and bracketed release group information.

Example (TV):

• Input: Stranger.Things.S04E01.1080p.NF.WEB-DL.x264.mkv
• Parsed Output:
  • Title: Stranger Things
  • Season: 4
  • Episode: 1

Example (Anime):

• Input: [SubsPlease] Chainsaw Man - 01 (1080p) [827493].mkv
• Parsed Output:
  • Title: Chainsaw Man
  • Episode: 1
  • Provider: AniList

3. Adult Content (StashDB)

When the "Adult Content" toggle is enabled, the parser adapts to identify studio tags and performer names, which are prioritized for StashDB API lookups.

• Logic: Often looks for Studio - Title or Date - Performer - Title formats.
• Tagging: Filename tokens that match known genres are automatically converted into UI tags.

Noise Removal (Sanitization)

To ensure high match rates, the parser automatically identifies and strips "noise" tokens that do not contribute to the title. These include:

| Category | Examples of Stripped Tokens | | :--- | :--- | | Resolution | 720p, 1080p, 2160p, 4k | | Source | WEB-DL, BluRay, HDRip, DVDRip | | Codecs | x264, x265, HEVC, H.264 | | Audio | DDP5.1, Atmos, AAC2.0, Dual-Audio | | Groups | [ReleaseGroup], -GroupTag |

Usage in Library Scans

When you trigger a scan via the Library settings or the /library/scan backend endpoint, the following logic is applied to every detected file:

// Conceptual internal flow for a library scan
const fileInfo = {
  rawName: "Interstellar.2014.1080p.mkv",
  path: "/movies/Interstellar.2014.1080p.mkv"
};

// 1. Strip file extension
// 2. Replace dots/underscores with spaces
// 3. Identify Year or SxxExx markers
// 4. Extract Title
// 5. Query Metadata Provider (TMDB/AniList/StashDB)

Best Practices for Users

To achieve a 100% match rate, it is recommended to follow the Plex/Jellyfin naming standard:

• Movies: Movies/Movie Title (Year)/Movie Title (Year).mkv
• Shows: TV Shows/Show Title/Season 01/Show Title S01E01.mkv

Handling Mismatches

If a filename is too obscured for the parser to identify, Freak-Flix will display the raw filename in the UI. You can manually correct these by selecting "Fix Match" on the media details page, which allows you to manually input a TMDB or AniList ID.