KVideo is a sophisticated video streaming platform that intelligently aggregates content from multiple video sources, providing users with a seamless, unified viewing experience. Built with modern web technologies and designed with the "Liquid Glass" design philosophy, KVideo offers an elegant, intuitive interface that adapts beautifully to both light and dark modes.

The platform features intelligent source checking, automatic failover, playback history tracking, and a fully responsive design that works flawlessly across all devices.

Built With

KVideo is built using cutting-edge web technologies:

Next.js 16 - React framework with App Router
React 19 - UI library with modern hooks
TypeScript - Type-safe development
Tailwind CSS 4 - Utility-first styling
Artplayer - Advanced HTML5 video player
HLS.js - HLS streaming support
Zustand - Lightweight state management

Key Features

🎯 Intelligent Multi-Source Aggregation

Automatically searches across multiple video sources
Smart source validation and availability checking
Real-time source health monitoring
Automatic failover to working sources

🎨 Modern "Liquid Glass" UI

Beautiful glassmorphism design system
Smooth animations and transitions
Comprehensive component library
Dark/Light theme support with system detection

🎬 Advanced Video Player

HLS streaming support
Episode management and auto-play
Playback progress tracking
Customizable playback controls
Picture-in-Picture support

📚 Smart History Management

Automatic playback position saving
Intelligent show deduplication
Cross-device history sync
Episode progress tracking

🔍 Enhanced Search Experience

Real-time search results
Search result caching (10-minute duration)
Loading animations with progress indicators
Source availability badges
🏷️ Auto-collected type badges with filtering (NEW!)
- Automatically collects category badges from search results
- Interactive filtering by video type/category
- Real-time badge count updates
- Smart badge removal when videos are deleted
- Beautiful Liquid Glass design integration

📱 Fully Responsive

Mobile-first design approach
Optimized for all screen sizes
Touch-friendly interface
Progressive Web App ready

Getting Started

Follow these steps to get KVideo running on your local machine.

Prerequisites

Ensure you have the following installed:

Node.js (v18.0.0 or higher)
npm (v9.0.0 or higher) or yarn (v1.22.0 or higher)

# Check your Node.js version
node --version

# Check your npm version
npm --version

Installation

Clone the repository

git clone https://github.com/KuekHaoYang/Video.git
cd kvideo

Install dependencies

npm install

Set up environment variables (optional)

Create a .env.local file in the root directory if you need to configure custom settings:

# Add any environment-specific configuration here
NEXT_PUBLIC_API_URL=your_api_url

Run the development server

npm run dev

Open your browser

Navigate to http://localhost:3000 to see the application running.

Usage

Development Server

Start the development server with hot-reload:

npm run dev

The application will be available at http://localhost:3000.

Production Build

Build the application for production:

npm run build

Start the production server:

npm start

Linting

Run ESLint to check code quality:

npm run lint

Architecture

Project Structure

kvideo/
├── app/                      # Next.js App Router
│   ├── api/                  # API routes
│   │   ├── detail/          # Video detail endpoint
│   │   ├── search/          # Search endpoint
│   │   └── search-stream/   # Streaming search endpoint
│   ├── player/              # Video player page
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Home page
│   └── globals.css          # Global styles
├── components/              # React components
│   ├── ui/                  # UI component library
│   │   ├── Badge.tsx
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Icon.tsx
│   │   └── Input.tsx
│   ├── SearchLoadingAnimation.tsx
│   ├── ThemeProvider.tsx
│   └── ThemeSwitcher.tsx
├── lib/                     # Core utilities
│   ├── api/                 # API client
│   │   ├── client.ts
│   │   └── video-sources.ts
│   ├── store/               # State management
│   │   ├── history-store.ts
│   │   └── player-store.ts
│   ├── types/               # TypeScript definitions
│   │   └── index.ts
│   └── utils/               # Utility functions
│       ├── episode-manager.ts
│       ├── error-handler.ts
│       ├── m3u8-filter.ts
│       ├── progress-tracker.ts
│       ├── search.ts
│       ├── source-checker.ts
│       ├── source-switcher.ts
│       └── url-validator.ts
├── public/                  # Static assets
├── next.config.ts           # Next.js configuration
├── tailwind.config.ts       # Tailwind configuration
├── tsconfig.json           # TypeScript configuration
└── package.json            # Project dependencies

Core Components

Search System

Multi-source Search: Parallel queries across multiple video APIs
Result Caching: 10-minute cache to reduce API calls
Progress Tracking: Real-time feedback on search and validation progress

Video Player

Episode Management: Sequential episode navigation with auto-play
Progress Tracking: Automatic position saving and restoration
Source Switching: Seamless failover between video sources
HLS Support: Adaptive bitrate streaming

State Management

Player Store: Manages playback state, episodes, and settings
History Store: Tracks viewing history with smart deduplication

API Layer

Client Abstraction: Unified interface for multiple video sources
Error Handling: Graceful degradation and retry logic
Source Validation: Health checks and availability monitoring

Design System

KVideo implements the "Liquid Glass" design system, featuring:

Visual Principles

Glass Effect: Sophisticated backdrop-filter with frosted translucency
Universal Softness: Consistent rounded corners (rounded-2xl and rounded-full)
Fluid Animations: Physics-based transitions with cubic-bezier curves
Depth & Layering: Clear z-axis hierarchy with natural shadows
Adaptive Controls: Dynamic elements that respond to user interaction

Component Library

The UI component library includes:

Avatar & Badge
Buttons (primary, secondary, disabled states)
Cards with glass morphism
Form inputs with validation
Modals & Drawers
Tabs & Navigation
Progress indicators
Theme switcher with system detection

Typography & Accessibility

Font: San Francisco (SF) system font stack
Contrast: WCAG 2.2 compliant (minimum 4.5:1 ratio)
Semantic HTML: Proper HTML5 structure
ARIA Support: Comprehensive ARIA attributes
Keyboard Navigation: Full keyboard operability

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

How to Contribute

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

Development Guidelines

Follow the existing code style and conventions
Write meaningful commit messages
Add tests for new features
Update documentation as needed
Ensure all tests pass before submitting

License

This project is private and not currently licensed for public use.

Contact

Hao Yang Kuek - @KuekHaoYang

Project Link: https://github.com/KuekHaoYang/Video

_{Built with ❤️ using Next.js and the Liquid Glass design system}

README.md

KVideo

Table of Contents

About The Project