mystuff_frontend/README.md

# 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:
```bash
git clone <repository-url>
cd frontend
```

2. Install dependencies:
```bash
npm install
```

3. Configure environment variables:
```bash
cp .env.example .env
```

Edit `.env` and configure your settings (see [Configuration](#configuration) below).

4. Start the development server:
```bash
npm run dev
```

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

## Configuration

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

```env
# 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](https://github.com/JosefNemec/PlayniteExtensions) 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](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

## 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 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](api.md).

## License

SPDX-License-Identifier: Apache-2.0

## Support

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