Omnyx - Media Discovery Platform

A modern web application for browsing, managing, and discovering media across multiple categories. Omnyx provides a unified interface for your media library with support for importing from external sources like Playnite, StashAPP, and XBVR.

Features

• Multi-Category Media Management: Browse and organize Anime, Movies, TV Series, Music, Books, Consoles, Games, and Adult content
• Detailed Media Views: Rich information display including descriptions, genres, studios, cast, and ratings
• Cast & Staff Directory: Explore actors, directors, and other staff across your media library
• Search & Filter: Quickly find media by title, year, genre, or studio
• Custom Media: Add your own media entries manually
• External Importers: Import libraries from popular media managers:
  • Playnite: Import your game library with playtime, achievements, and metadata
  • StashAPP: Import adult content with scene and performer details
  • XBVR: Import VR content with scene information
• Category Toggles: Enable/disable categories to customize your view
• Responsive Design: Beautiful UI built with Tailwind CSS and shadcn/ui components

Tech Stack

• Frontend Framework: React 19 with TypeScript
• Build Tool: Vite 6
• Styling: Tailwind CSS 4
• UI Components: shadcn/ui, Base UI
• Icons: Lucide React
• Animations: Motion (Framer Motion)
• Fonts: Geist Variable Font

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Backend API server (configured via environment variables)

Installation

1. Clone the repository:

git clone <repository-url>
cd frontend

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

Edit .env and configure your settings (see Configuration below).

4. Start the development server:

npm run dev

The app will be available at http://localhost:3000

Configuration

Create a .env file based on .env.example:

# App URL (auto-injected by AI Studio in production)
APP_URL="http://localhost:3000"

# XBVR Importer
VITE_XBVR_URL="http://localhost:9999"

# StashAPP Importer
VITE_STASHAPP_URL="http://localhost:9999"
VITE_STASHAPP_API_KEY="your-api-key"

# Playnite Importer
VITE_PLAYNITE_IP="localhost"
VITE_PLAYNITE_PORT="19821"
VITE_PLAYNITE_API_TOKEN="your-api-token"

Importer Configuration

Playnite

1. Install the Playnite Bridge extension in Playnite
2. Enable the HTTP API server in Playnite settings
3. Generate an API token in the Playnite Bridge settings
4. Configure the IP, port, and token in your .env file
5. See playnite_skill.md for detailed API documentation

StashAPP

1. Ensure StashAPP is running and accessible
2. Generate an API key in StashAPP settings
3. Configure the URL and API key in your .env file

XBVR

1. Ensure XBVR is running and accessible
2. Configure the URL in your .env file

Desktop App (Tauri) — Vollständig offline nutzbar

Omnyx ist eine einzige Desktop-App — der Nutzer installiert sie und bekommt ein Fenster mit der Benutzeroberfläche. Backend und Frontend sind in einer Anwendung vereint, kein externer Server nötig.

⚠️ Wichtig: Es entstehen zwei verschiedene .exe-Dateien (Tauri-Shell + Backend-Sidecar), aber der Nutzer startet nur die Omnyx-App. Das Backend läuft automatisch unsichtbar im Hintergrund.

Architektur (Entwickler-Perspektive)

┌───────────────────────────────────────────┐
│           Omnyx Desktop App               │
│                                           │
│  ┌─────────────────────┐                  │
│  │ Tauri-WebView       │  ← Nutzer sieht │
│  │ (React-Frontend)    │    DAS           │
│  │                     │                  │
│  │ API → localhost:3001│                  │
│  └────────┬────────────┘                  │
│           │ (unsichtbar)                  │
│  ┌────────▼────────────┐                  │
│  │ Bun-Sidecar         │  ← läuft im     │
│  │ (Backend, Port 3001)│    Hintergrund   │
│  │                     │                  │
│  │ SQLite-Datenbank    │                  │
│  │ data/omnyx.db       │                  │
│  └─────────────────────┘                  │
└───────────────────────────────────────────┘

Für den Endnutzer sieht es so aus: Doppelklick auf "Omnyx" → ein Fenster öffnet sich → fertig.

Voraussetzungen (zum Bauen)

• Bun ≥ 1.3 (Backend-Kompilierung)
• Rust ≥ 1.77 (Tauri-Build)
• Node.js ≥ 18

One-Click-Build

cd frontend
npm run desktop:build

Macht alles automatisch: Backend kompilieren → Binary kopieren → Tauri-App bauen → Installer erzeugen.

Schritt für Schritt

1. Backend-Binary kompilieren

cd backend
bun install
bun run compile:tauri

Erzeugt backend/dist-exe/omnyx-backend.exe (~50 MB Single-File) und kopiert es automatisch in frontend/src-tauri/binaries/.

Der Dateiname muss dem Tauri-Target-Triple entsprechen:

• Windows: omnyx-backend-x86_64-pc-windows-msvc.exe
• Linux: omnyx-backend-x86_64-unknown-linux-gnu

2. Desktop-App bauen (Produktion)

cd frontend
npm install
npm run tauri build

Erzeugt Installer in src-tauri/target/release/bundle/:

• nsis\Omnyx_0.1.0_x64-setup.exe — Windows-Installer
• msi\Omnyx_0.1.0_x64_en-US.msi — MSI-Paket

3. Desktop-App testen (Dev-Modus)

cd frontend
npm install
npm run tauri dev

Startet ein natives Fenster, Vite-Dev-Server (Port 3000) und Backend-Sidecar (Port 3001) — mit Hot-Reload.

Konfiguration

Für Tauri wird automatisch die Datei .env.tauri verwendet (via --mode tauri):

# Lokaler Backend-Port
VITE_API_URL=http://localhost:3001
# Externe Importer (optional — nur bei Netzwerk-Zugriff)
VITE_XBVR_URL=http://localhost:4080
VITE_STASHAPP_URL=http://localhost:10001

Alle Datenbanken und Konfigurationen liegen lokal — kein Internet oder Server erforderlich.

Usage

Browsing Media

• Navigate between categories using the header navigation
• Toggle categories on/off using the category buttons
• Search for media using the search bar
• Click on any media item to view detailed information

Managing Media

• Add Media: Click the "+" button to add custom media entries
• Import: Use the import feature to bring in libraries from Playnite, StashAPP, or XBVR
• View Cast: Browse the cast directory to see all staff across your library

Importing from External Sources

1. Click the import button in the header
2. Select the importer you want to use
3. Follow the on-screen instructions to configure and run the import
4. Progress will be displayed in real-time

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run tauri - Run Tauri desktop app
• npm run lint - Run TypeScript type checking
• npm run clean - Remove build artifacts

Project Structure

src/
├── components/          # React components
│   ├── ui/             # shadcn/ui components
│   ├── AddMediaView.tsx
│   ├── BrowseView.tsx
│   ├── CastDetailView.tsx
│   ├── CastView.tsx
│   ├── DetailView.tsx
│   └── ImporterView.tsx
├── lib/                # Utility functions
│   ├── playniteImporter.ts
│   ├── stashappImporter.ts
│   └── utils.ts
├── App.tsx             # Main application component
├── api.ts              # API client functions
├── data.ts             # Mock data
└── types.ts            # TypeScript type definitions

API Documentation

For detailed API documentation, see api.md.

License

SPDX-License-Identifier: Apache-2.0

Support

For issues, questions, or contributions, please refer to the project repository.