KVideo/README_NEW.md

KVideo - Video Aggregation Platform

A Next.js-based video streaming platform that aggregates content from multiple third-party APIs with intelligent source switching and advanced ad filtering.

✨ Features

• 🔍 Multi-Source Search: Search across multiple video APIs simultaneously
• ⚡ Intelligent Source Switching: Automatic speed testing and source recommendation
• 🎯 Advanced Ad Filtering: M3U8 playlist ad segment removal
• 💾 Progress Tracking: Auto-save and resume from last watched position
• 📱 Episode Management: Smart episode navigation with progress tracking
• 🔄 Error Recovery: Automatic retry and fallback mechanisms
• 📊 Viewing History: Track last 50 watched videos
• ⚙️ Custom Sources: Add your own video API endpoints

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Modern browser with LocalStorage support

Installation

# Install dependencies
npm install

# Or run setup script
chmod +x setup.sh
./setup.sh

Configuration

Edit lib/api/video-sources.ts with your video API endpoints:

export const DEFAULT_SOURCES: VideoSource[] = [
  {
    id: 'source_1',
    name: 'Primary Video API',
    baseUrl: 'https://your-api.com',
    searchPath: '/api.php/provide/vod',
    detailPath: '/api.php/provide/vod',
    enabled: true,
  },
];

Development

npm run dev

Visit http://localhost:3000

Production

npm run build
npm start

📚 Documentation

• SETUP.md - Detailed setup instructions and examples
• IMPLEMENTATION.md - Architecture and API documentation
• SUMMARY.md - Implementation overview

🏗️ Architecture

KVideo Platform
├── API Layer (Multi-source aggregation)
├── State Management (Zustand stores)
├── Utility Layer (Search, Progress, Episodes)
├── Error Handling (Recovery strategies)
└── M3U8 Ad Filtering (Custom HLS loader)

Core Components

API Layer

• video-sources.ts: Source configuration and health checks
• client.ts: HTTP client with retry logic and timeouts
• search/route.ts: Search API endpoint
• detail/route.ts: Video detail API endpoint

State Management

• player-store.ts: Video playback state (Zustand)
• history-store.ts: Viewing history (Zustand)

Utilities

• progress-tracker.ts: LocalStorage-based progress management
• error-handler.ts: Comprehensive error recovery
• search.ts: Search optimization and debouncing
• episode-manager.ts: Episode navigation logic
• source-switcher.ts: Speed testing and source comparison
• m3u8-filter.ts: Ad filtering for HLS streams

🎯 Key Features Explained

Multi-Source Aggregation

Search across multiple video APIs simultaneously with parallel requests, automatic deduplication, and response time tracking.

Intelligent Source Switching

• Tests all available sources in parallel
• Measures API response time + video URL accessibility
• Provides visual speed indicators (Fast/Medium/Slow)
• Recommends faster alternatives
• Caches results for 5 minutes

Advanced Ad Filtering

Custom HLS loader that:

• Intercepts M3U8 playlist requests
• Filters segments containing ad patterns
• Removes discontinuity tags
• Preserves valid video segments
• Supports custom ad pattern rules

Progress Tracking

• Auto-saves progress every 5 seconds (throttled)
• Resumes from last position on reload
• Clears progress when video finishes
• Per-episode progress tracking
• Auto-cleanup of old entries

🔧 Configuration

Timeouts & Limits

// lib/api/client.ts
const REQUEST_TIMEOUT = 15000;  // 15 seconds
const MAX_RETRIES = 3;          // 3 attempts

// lib/utils/progress-tracker.ts
const PROGRESS_SAVE_THRESHOLD = 10;   // Skip if < 10s
const RESUME_MIN_POSITION = 10;       // Resume if > 10s

Custom Ad Patterns

import { addCustomAdPattern } from '@/lib/utils/m3u8-filter';
addCustomAdPattern('/your-ad-path/');

📖 API Usage

Search Videos

POST /api/search
{
  "query": "movie name",
  "sources": ["source_1", "source_2"],
  "page": 1
}

Get Video Detail

GET /api/detail?id=123&source=source_1

🛠️ Tech Stack

• Next.js 16 - React framework
• TypeScript - Type safety
• Zustand - State management
• HLS.js - Video streaming
• Artplayer - Video player UI

📦 Dependencies

{
  "zustand": "^5.0.2",
  "hls.js": "^1.5.15",
  "artplayer": "^5.1.7"
}

🎨 UI Components Needed

To complete the platform, create these components:

• SearchBar with debouncing
• VideoGrid for search results
• VideoPlayer with HLS.js integration
• EpisodeList with navigation
• SourceSwitcher with speed indicators
• HistoryList with progress bars

📄 License

MIT License

📞 Support

For detailed documentation:

• Check IMPLEMENTATION.md for architecture
• Review SETUP.md for setup instructions
• See SUMMARY.md for overview

---

Status: Core logic implementation complete ✅
Next Steps: Build UI components and integrate with logic layers

Built with ❤️ using Next.js and TypeScript