Kyoo - Media Discovery Platform

A modern web application for browsing, managing, and discovering media across multiple categories. Kyoo 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

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.

License

SPDX-License-Identifier: Apache-2.0

Support

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