Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (75 loc) · 2.99 KB

CONTRIBUTING.md

File metadata and controls

101 lines (75 loc) · 2.99 KB
Raw

Development Guide

This guide provides instructions for setting up a local development environment for VPX Manager for ES-DE.

🛠 Prerequisites

  • Python 3.11 or 3.12 (Python 3.13+ may have compatibility issues with some dependencies like rumps).
  • Git
  • Homebrew (for macOS dependencies) or apt/dnf (for Linux).

🚀 Setting Up the Environment

  1. Clone the Repository

    git clone https://github.com/macsobel/VPX-Manager-for-ES-DE
cd VPX-Manager-for-ES-DE

  2. Create a Virtual Environment

    python3 -m venv .venv
source .venv/bin/activate

  3. Install Dependencies

    pip install -r requirements.txt

  4. Install System Dependencies (macOS)

    # Required for Backglass Companion and Video Processing
brew install sdl2 sdl2_image sdl2_mixer sdl2_ttf ffmpeg

🔑 ScreenScraper API Credentials

To use the scraping features during development, you need your own ScreenScraper Developer Credentials. Without these, the app will fall back to public access, which has lower rate limits and may fail for certain media types.

1. Obtain Credentials

Register for a developer account at ScreenScraper.fr to obtain:

  • devid
  • devpassword

2. Configure Your Environment

You can provide these credentials to the app in two ways:

Option A: Environment Variables (Recommended)

Add the following to your shell profile (.zshrc or .bashrc) or a local .env file:

export SS_DEV_ID="your_dev_id"
export SS_DEVPASS="your_dev_password"

Option B: config.dat File

Create a config.dat file in the project root. This file is ignored by git to prevent accidental commits of your credentials.

{
  "screenscraper_devid": "your_dev_id",
  "screenscraper_devpassword": "your_dev_password"
}

Important

Never commit your config.dat file or your personal credentials to a public repository.

🖥 Running Locally

Launch the application in development mode:

python3 main.py
  • Web UI: Access at http://localhost:8746
  • Logs: View real-time logs in the terminal. The vpx_manager.log file (in the Application Support directory) is only generated when running in development mode.

📦 Building the Application

To package the application into a standalone .app bundle (macOS) or binary (Linux), use the provided build script:

./scripts/build/build_app.sh

This script handles:

  1. Bundling the FastAPI backend.
  2. Compiling the SDL2-based Backglass Companion.
  3. Obfuscating baked-in credentials (if present in config.dat).
  4. Creating the final DMG or distribution folder.

🤝 Contributing

  1. Create a Branch: git checkout -b feature/your-feature-name
  2. Commit Changes: Use descriptive commit messages.
  3. Push & PR: Push your branch and open a Pull Request against the main branch.

Please ensure your code follows the existing style and includes comments for complex logic.