9.8 KiB
KVideo
A modern, elegant video streaming platform with intelligent source aggregation
Table of Contents
About The Project
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-2xlandrounded-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