VIBEX — Lightweight Media Server 🎬📦

VIBEX is a high-performance, stateless, and ultra-lightweight home media server built with Python and Flask. Designed as a minimalist alternative to resource-heavy platforms like Plex or Jellyfin, VIBEX scans your local directories (G:/film, G:/shows), parses unstructured torrent-style file naming conventions using regex engines, and cross-references metadata directly via the TMDB API.

---

⚡ Technical Highlights & Architecture

• Stateless Database Connections: Operates on a synchronous, on-demand SQLite lifecycle. Connections are established and disposed of per API request, completely eliminating cross-thread concurrency locks common in multi-threaded Flask environments.
• Deterministic ID Generation: Implements a custom cryptographic token hashing routine (SHA-1) to compute predictable, immutable primary keys for media assets. This completely bypasses identity collision vectors without requiring structural DB dependencies.
• Robust Regex Engine: Normalizes and cleans raw multi-format metadata sequences (stripping tags like 1080p, x265, bluray, FRENCH) into explicit title lookups.
• Local Asset Caching: Pulls and mirrors remote poster endpoints locally to reduce third-party API throttling and deliver instantaneous UI rendering.
• Delta Watch-History Processing: Updates playback progress via optimized database triggers using a native ON CONFLICT(media_id, media_type) DO UPDATE UPSERT query routine.

---

🌐 How to Get Your TMDB API Token

VIBEX relies on The Movie Database (TMDB) to pull movie posters, backdrops, and descriptions. To get your free API Token, follow these steps:

1. Go to The Movie Database website and register a free account.
2. Verify your email address and log in to your account.
3. Click on your profile icon in the top right corner and navigate to Settings.
4. On the left sidebar, click on the API section.
5. Click on Create to request a new API key (choose the "Developer" option).
6. Fill out the application form with your project details (you can just state it is for a personal home media server application).
7. Once approved instantly, you will see two fields: API Key and API Read Access Token (v4 auth).
8. Copy the long API Read Access Token (the JWT string) and use it for your VIBEX_TMDB_TOKEN environment variable.

---

🧰 Project Directory Structure

Ensure your repository follows this blueprint:

VIBEX/
│
├── posters/               # Automatically created. Storage for cached artwork (Ignored by Git)
├── templates/             # UI Templates directory
│   ├── login.html         # Secure administrative portal
│   ├── index.html         # Main dashboard view
│   ├── details.html       # Movie/Show layout & episode list
│   └── player.html        # Video streaming core interface
│
├── .gitignore             # Git exclusion architecture
├── library.db             # Local relational SQLite engine (Ignored by Git)
├── README.md              # Technical documentation
└── vibex.py               # Application core backend script

---

🛠️ Security & Environment Configuration

VIBEX enforces industry-standard DevSecOps practices by fully isolating cryptographic keys, tokens, and credentials from the version-controlled codebase.

1. Hardening your Repository (.gitignore)

To prevent data leaks, local databases, dynamically downloaded media assets, and startup scripts are blocked from being pushed online. Create a .gitignore file at the root level:

# Databases
library.db

# Dynamic Asset Store
posters/

# Python caching
__pycache__/
*.pyc

# Local Environment & Secrets
.env
*.bat
*.sh

2. Setting Up Variables

The runtime script automatically hooks into your local Operating System environment variables using os.environ.get(). If no environment values are detected, it falls back to development defaults.

Environment Variable	Description	Default Fallback
VIBEX_ADMIN_USER	Custom username for portal access	admin
VIBEX_ADMIN_PASS	Hardened password for session security	admin
VIBEX_TMDB_TOKEN	Bearer Token obtained via TMDB API developer portal	(Empty String)
VIBEX_SECRET_KEY	Cryptographic key used to sign client cookies	temporary_dev_key

---

🚀 Installation & Local Deployment

Step 1: Install Dependencies

Ensure you have Python 3.8+ installed on your host system. Install the required network and web routing abstractions:

pip install Flask requests

Step 2: Configure System Environment

🔹 For Windows Host Environments

Create a fast deployment script named run.bat alongside vibex.py:

@echo off
:: Define secure local runtime environment variables
set VIBEX_ADMIN_USER=YourCustomUser
set VIBEX_ADMIN_PASS=YourComplexPassword
set VIBEX_TMDB_TOKEN=your_real_jwt_tmdb_bearer_token_here
set VIBEX_SECRET_KEY=highly_cryptographic_and_long_string_token

:: Run the microserver
python vibex.py
pause

🔹 For Linux / macOS Host Environments

Create a deployment shell script named run.sh:

#!/bin/bash
# Define secure local runtime environment variables
export VIBEX_ADMIN_USER="YourCustomUser"
export VIBEX_ADMIN_PASS="YourComplexPassword"
export VIBEX_TMDB_TOKEN="your_real_jwt_tmdb_bearer_token_here"
export VIBEX_SECRET_KEY="highly_cryptographic_and_long_string_token"

# Run the microserver
python3 vibex.py

Make it executable: chmod +x run.sh

Step 3: Launching the App

Execute your script (run.bat or ./run.sh). Open your preferred web browser and point your URL bar to:

http://localhost:5000

Log in using your customized environmental credentials to securely initiate your library scan.

---

📄 License

This software architecture is distributed open-source under the terms of the MIT License. Check the main repository files for comprehensive legal details.