Library Scanning & Task Queue

Library Scanning & Task Queue

Freak-Flix utilizes a high-performance, recursive scanning engine to index your media and populate your library with rich metadata. This process is handled asynchronously via a task queue system to ensure that the user interface remains responsive even during large library imports.

How Scanning Works

When you add a folder to Freak-Flix, the system initiates a background task that performs the following:

1. Directory Traversal: The scanner recursively crawls the provided path (Local or Cloud).
2. File Identification: It identifies video files and determines their type (Movie, TV Show, Anime, or Adult) based on folder structure or file naming conventions.
3. Metadata Fetching: The scanner queries external APIs (TMDB, AniList, or StashDB) to retrieve posters, backdrops, cast information, and plot summaries.
4. Database Indexing: Metadata and file paths are saved to the backend database, making them immediately available for search and playback across all your devices.

Triggering a Library Scan

Scans are triggered via the backend API. While the Flutter frontend handles this through the Settings > Library menu, developers can manually trigger a scan using the /library/scan endpoint.

API Endpoint: POST /library/scan

Starts a recursive scan for a specific folder.

Authentication: Required (Bearer Token)

Request Body:

| Field | Type | Description | | :--- | :--- | :--- | | path | string | The human-readable path or name of the folder. | | provider | string | The storage provider (e.g., onedrive, local). | | folderId | string | The unique identifier from the provider (e.g., OneDrive DriveItem ID). | | accessToken| string | A valid OAuth2 token for the provider (required for cloud providers). |

Example Request:

{
  "path": "/Videos/Movies",
  "provider": "onedrive",
  "folderId": "01C2XXXXXXXXXXXX",
  "accessToken": "EwBkA..."
}

Response: Returns a 200 OK status immediately after the task is queued.

Task Queue & Asynchronous Processing

Freak-Flix uses a "Fire-and-Forget" background processing model. This means when a scan is requested, the server validates the request, initiates the process, and immediately returns a response to the client.

• waitUntil Execution: On Cloudflare-based backends, the scanner uses the executionCtx.waitUntil() method. This allows the scanning logic to continue running in the background after the HTTP response has been sent to the app.
• Recursive Processing: The scanRecursive function handles deep folder structures without hitting typical request timeout limits, as it processes I/O operations asynchronously.
• Progress Feedback: The app UI periodically syncs with the database to show newly discovered items as they are processed in real-time.

Provider-Specific Behavior

• OneDrive: The scanner uses the folderId to fetch children via the Microsoft Graph API. It leverages the accessToken provided in the request to authenticate these calls.
• Local Storage: For desktop installations, the scanner utilizes native file system APIs to index content.
• StashDB Integration: If "Adult Content" is enabled in settings, the scanner uses the StashDB API key to perform specialized metadata lookups, including studio info and performer profiles.

Best Practices for Library Organization

To ensure the highest accuracy during the scanning process, follow these naming conventions:

• Movies: Movie Name (Year).mp4
• TV Shows: Series Name/Season 01/S01E01 - Episode Name.mkv
• Anime: Ensure the folder name matches the title found on AniList for better matching.