KVideo/SETUP.md

KVideo Platform - Setup Guide

Quick Start

1. Install Dependencies

npm install

This will install:

• zustand (v5.0.2): State management
• hls.js (v1.5.15): HLS video streaming
• artplayer (v5.1.7): Video player UI

2. Configure Video Sources

Edit lib/api/video-sources.ts and update the DEFAULT_SOURCES array with your video API endpoints:

export const DEFAULT_SOURCES: VideoSource[] = [
  {
    id: 'source_1',
    name: 'Primary Video API',
    baseUrl: 'https://your-api-domain.com',
    searchPath: '/api.php/provide/vod',
    detailPath: '/api.php/provide/vod',
    headers: {
      'User-Agent': 'Mozilla/5.0',
    },
    enabled: true,
    priority: 1,
  },
  // Add more sources...
];

3. Run Development Server

npm run dev

Visit http://localhost:3000

Project Structure

kvideo/
├── app/
│   ├── api/
│   │   ├── search/route.ts       # Search API endpoint
│   │   └── detail/route.ts       # Detail API endpoint
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── lib/
│   ├── types/
│   │   └── index.ts              # TypeScript type definitions
│   ├── api/
│   │   ├── video-sources.ts      # Source configuration
│   │   └── client.ts             # HTTP client
│   ├── store/
│   │   ├── player-store.ts       # Player state (Zustand)
│   │   └── history-store.ts      # History state (Zustand)
│   └── utils/
│       ├── progress-tracker.ts   # Progress management
│       ├── error-handler.ts      # Error handling
│       ├── search.ts             # Search utilities
│       ├── episode-manager.ts    # Episode navigation
│       ├── source-switcher.ts    # Source testing
│       └── m3u8-filter.ts        # Ad filtering
├── components/
│   └── player/
│       └── VideoPlayer.tsx       # (To be created)
├── IMPLEMENTATION.md             # Detailed architecture guide
└── package.json

Core Functionality

1. Multi-Source Video Search

// Example: Search across multiple sources
import { searchVideos } from '@/lib/api/client';
import { getEnabledSources } from '@/lib/api/video-sources';

const sources = getEnabledSources();
const results = await searchVideos('movie name', sources, 1);

// Results include response time and source attribution
results.forEach(result => {
  console.log(`Source: ${result.source}`);
  console.log(`Response time: ${result.responseTime}ms`);
  console.log(`Results: ${result.results.length}`);
});

2. Video Player State Management

// Example: Using player store
import { usePlayerStore } from '@/lib/store/player-store';

function VideoPlayer() {
  const { currentVideo, episodes, nextEpisode } = usePlayerStore();
  
  const handleVideoEnd = () => {
    const next = nextEpisode();
    if (next) {
      console.log('Auto-playing next episode:', next.name);
    }
  };
  
  // Player component logic...
}

3. Progress Tracking

// Example: Save and restore progress
import { saveProgress, getProgress, shouldResumeProgress } from '@/lib/utils/progress-tracker';

// Save progress every 5 seconds
const handleTimeUpdate = (currentTime: number) => {
  saveProgress(videoId, source, currentTime, duration, episodeIndex);
};

// Resume on load
const storedProgress = getProgress(videoId, source);
if (shouldResumeProgress(storedProgress)) {
  player.currentTime = storedProgress.position;
}

4. Source Speed Testing

// Example: Test and switch sources
import { testAllSources, getSpeedIndicator } from '@/lib/utils/source-switcher';

const results = await testAllSources(videoTitle, sources, currentSource);

results.forEach(result => {
  const indicator = getSpeedIndicator(result.speed);
  console.log(`${result.sourceName}: ${indicator.label} (${result.speed}ms)`);
});

// Get fastest source
const fastest = results.find(r => r.available);

5. M3U8 Ad Filtering

// Example: Initialize HLS with ad filtering
import Hls from 'hls.js';
import { createAdFilteringConfig } from '@/lib/utils/m3u8-filter';

const hls = new Hls(createAdFilteringConfig());
hls.loadSource(m3u8Url);
hls.attachMedia(videoElement);

API Usage

Search Endpoint

POST /api/search

Request:

{
  "query": "movie name",
  "sources": ["source_1", "source_2"],
  "page": 1
}

Response:

{
  "success": true,
  "query": "movie name",
  "page": 1,
  "sources": [
    {
      "results": [...],
      "source": "source_1",
      "responseTime": 234
    }
  ],
  "totalResults": 42
}

Detail Endpoint

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

Response:

{
  "success": true,
  "data": {
    "vod_id": 123,
    "vod_name": "Movie Title",
    "vod_pic": "https://...",
    "episodes": [
      {
        "name": "Episode 1",
        "url": "https://...",
        "index": 0
      }
    ],
    "source": "source_1"
  }
}

Environment Variables

Create .env.local:

# Optional: Default video sources
NEXT_PUBLIC_DEFAULT_SOURCE_1=https://api.example1.com
NEXT_PUBLIC_DEFAULT_SOURCE_2=https://api.example2.com

# Optional: Analytics
NEXT_PUBLIC_GA_ID=your-google-analytics-id

# Development
NODE_ENV=development

Building for Production

# Build the application
npm run build

# Start production server
npm start

Testing

Test API Sources

# Use the health check function
node -e "
const { healthCheckSources, getAllSources } = require('./lib/api/video-sources');
const sources = getAllSources();
healthCheckSources(sources).then(results => {
  results.forEach((result, sourceId) => {
    console.log(sourceId, result);
  });
});
"

Test Search Functionality

# Test search via API route
curl -X POST http://localhost:3000/api/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"test","sources":["source_1"],"page":1}'

Test Detail Fetch

# Test detail via API route
curl "http://localhost:3000/api/detail?id=123&source=source_1"

Common Issues

1. HLS.js Not Loading

Solution: Ensure the video URL is a valid M3U8 playlist and CORS is enabled on the video server.

// Add CORS headers in next.config.ts if needed
const nextConfig = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: '*' },
        ],
      },
    ];
  },
};

2. LocalStorage Quota Exceeded

Solution: The app auto-cleans old progress entries. You can also manually clear:

import { clearOldProgress } from '@/lib/utils/progress-tracker';
clearOldProgress(30); // Clear entries older than 30 days

3. Source Timeout

Solution: Adjust timeout in lib/api/client.ts:

const REQUEST_TIMEOUT = 15000; // Increase if needed

4. Ad Filtering Not Working

Solution: Add custom patterns:

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

Browser Compatibility

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+

Requirements:

• LocalStorage support
• Fetch API
• ES6+ JavaScript

Performance Tips

1. Limit Concurrent Sources: Test with 3-5 sources max for optimal speed
2. Enable Caching: Speed test results cached for 5 minutes
3. Throttle Progress: Auto-save limited to every 5 seconds
4. Lazy Load Episodes: Only fetch episodes when needed
5. Use CDN: Serve static assets via CDN for faster loading

Contributing

See IMPLEMENTATION.md for detailed architecture documentation.

License

MIT License - See LICENSE file for details

Support

For issues and questions:

1. Check IMPLEMENTATION.md for detailed documentation
2. Review error logs in browser console
3. Test API sources with health check function
4. Verify CORS configuration on video servers

---

Next Steps: Create UI components and integrate with the logic layers! All the core business logic is now implemented and ready to use.