# KVideo

> 基于 Liquid Glass 设计理念的现代化流媒体视频聚合平台

[![Next.js](https://img.shields.io/badge/Next.js-16.0-black?style=flat-square&logo=next.js)](https://nextjs.org/)
[![React](https://img.shields.io/badge/React-19.2-blue?style=flat-square&logo=react)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4.0-38B2AC?style=flat-square&logo=tailwind-css)](https://tailwindcss.com/)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)

## 目录

- [关于项目](#关于项目)
  - [核心特性](#核心特性)
  - [技术栈](#技术栈)
  - [设计理念](#设计理念)
- [快速开始](#快速开始)
  - [系统要求](#系统要求)
  - [安装步骤](#安装步骤)
- [使用指南](#使用指南)
  - [开发模式](#开发模式)
  - [生产构建](#生产构建)
- [核心功能](#核心功能)
  - [智能并行搜索](#智能并行搜索)
  - [实时流式传输](#实时流式传输)
  - [源可用性检测](#源可用性检测)
  - [观看历史管理](#观看历史管理)
  - [自适应视频播放器](#自适应视频播放器)
- [项目架构](#项目架构)
- [贡献指南](#贡献指南)
- [许可证](#许可证)
- [联系方式](#联系方式)

## 关于项目

KVideo 是一个现代化的流媒体视频聚合平台，采用 **Liquid Glass** 设计系统打造极致的用户体验。平台通过智能并行搜索技术，实时聚合多个视频源的内容，为用户提供流畅、直观且视觉震撼的观影体验。

### 核心特性

- 🔍 **智能并行搜索** - 同时查询 15+ 视频源，实时流式返回结果
- 🎬 **自适应播放器** - 支持 HLS/M3U8 流，自动源切换，断点续播
- 🎨 **Liquid Glass UI** - 毛玻璃效果，流体动画，深浅色主题无缝切换
- ⚡ **实时可用性检测** - 搜索时自动过滤失效源，确保播放成功率
- 📊 **类型智能筛选** - 自动识别分类（电影/剧集/综艺），支持多选过滤
- 📚 **观看历史追踪** - 自动记录播放进度，快速恢复观看
- 🌐 **无服务器架构** - 基于 Next.js App Router，API Routes 处理所有后端逻辑
- 📱 **响应式设计** - 完美适配桌面、平板、移动设备

### 技术栈

**前端框架**
- [Next.js 16.0](https://nextjs.org/) - React 元框架，提供服务端渲染和路由
- [React 19.2](https://reactjs.org/) - 用户界面构建库
- [TypeScript 5.x](https://www.typescriptlang.org/) - 类型安全的 JavaScript 超集

**样式系统**
- [Tailwind CSS 4.0](https://tailwindcss.com/) - 实用优先的 CSS 框架
- 自定义 Liquid Glass CSS 变量系统

**状态管理 & 工具**
- [Zustand 5.0](https://github.com/pmndrs/zustand) - 轻量级状态管理
- [Artplayer 5.1](https://artplayer.org/) - 现代化 HTML5 视频播放器
- [HLS.js 1.5](https://github.com/video-dev/hls.js/) - HLS 流协议支持

**视频源整合**
- 电影天堂、如意、暴风、天涯等 15+ 第三方视频 API
- 自定义源配置系统，支持动态添加

### 设计理念

KVideo 严格遵循 **Liquid Glass** 设计系统，灵感源自 Apple 的 visionOS 和 Jony Ive 的极简主义哲学：

1. **玻璃效果** - 毛玻璃材质（`backdrop-filter: blur(25px) saturate(180%)`）营造深度感
2. **通用柔软度** - 所有元素采用 `rounded-2xl` 或 `rounded-full` 圆角，无硬边
3. **流体动画** - 物理感知的缓动曲线（`cubic-bezier(0.2, 0.8, 0.2, 1)`）
4. **光学交互** - 悬停时内发光效果，仿佛组件在捕捉光线
5. **层次分明** - 清晰的 Z 轴深度，交互层始终位于视觉顶部

## 快速开始

### 系统要求

- **Node.js** 20.x 或更高版本
- **npm** 或 **pnpm** 包管理器
- 现代浏览器（Chrome 90+、Safari 14+、Firefox 88+）

### 安装步骤

1. **克隆仓库**
   ```bash
   git clone https://github.com/KuekHaoYang/kvideo.git
   cd kvideo
   ```

2. **安装依赖**
   ```bash
   npm install
   # 或使用 pnpm
   pnpm install
   ```

3. **启动开发服务器**
   ```bash
   npm run dev
   ```

4. **访问应用**
   
   打开浏览器访问 [http://localhost:3000](http://localhost:3000)

## 使用指南

### 开发模式

开发模式支持热重载和快速调试：

```bash
npm run dev
```

应用将在 `http://localhost:3000` 启动，代码更改会自动刷新页面。

### 生产构建

构建优化后的生产版本：

```bash
# 构建应用
npm run build

# 启动生产服务器
npm start
```

### 代码检查

运行 ESLint 检查代码质量：

```bash
npm run lint
```

## 核心功能

### 智能并行搜索

KVideo 采用先进的并行搜索架构，同时查询多个视频源：

- **并发请求** - 15 个视频源同时搜索，无需等待
- **流式传输** - 结果实时流式返回，即查即得
- **缓存机制** - 搜索结果本地缓存，秒开历史查询
- **相关性排序** - 智能匹配算法，最相关内容优先展示

```typescript
// 核心搜索 Hook - useParallelSearch
const { results, loading, performSearch } = useParallelSearch(
  saveToCache,
  onUrlUpdate
);

performSearch('电影名称'); // 触发并行搜索
```

### 实时流式传输

搜索过程采用服务端推送（SSE）技术：

1. **搜索阶段** - 显示已完成源数量 / 总源数量
2. **检测阶段** - 显示已验证视频数 / 总视频数
3. **结果推送** - 每验证通过一批视频立即推送

```typescript
// API Route - /api/search-stream
// 返回格式：
// data: {"type": "progress", "stage": "searching", "checkedSources": 5}
// data: {"type": "videos", "videos": [...], "checkedVideos": 10}
// data: {"type": "complete", "totalResults": 120}
```

### 源可用性检测

搜索时自动验证视频源可用性，过滤无效链接：

- **URL 格式验证** - 检查链接是否符合 M3U8/MP4 规范
- **HEAD 请求预检** - 验证资源是否存在（状态码 200/206）
- **内容大小检测** - 确保内容大小 > 1KB，排除空文件
- **并发控制** - 同时检测 8 个链接，平衡速度与服务器压力

```typescript
// 源检测核心函数
const availableVideos = await checkMultipleVideos(allVideos, 8);
// 仅返回可播放的视频
```

### 观看历史管理

基于 Zustand 的持久化历史记录：

- **自动记录** - 播放时自动保存到 localStorage
- **进度追踪** - 记录每集观看进度，支持断点续播
- **侧边栏展示** - 快速访问最近观看的视频
- **一键清除** - 支持批量或单个删除历史

```typescript
// 历史存储 Store
const { addToHistory, clearHistory } = useHistoryStore();

addToHistory(videoId, title, playUrl, source, episodeName, currentTime);
```

### 自适应视频播放器

基于 Artplayer 构建的高级播放器：

- **HLS 流支持** - 集成 hls.js，无缝播放 M3U8 格式
- **自动源切换** - 播放失败时自动尝试备用源
- **倍速播放** - 0.5x - 2x 速度调节
- **画质选择** - 自动识别多码率流
- **全屏控制** - 支持网页全屏和系统全屏
- **快捷键支持** - 空格暂停、方向键快进/快退

```typescript
// 播放器核心 Hook - useVideoPlayer
const { videoData, playUrl, currentEpisode } = useVideoPlayer(
  videoId,
  source,
  episodeParam
);
```

## 项目架构

```
kvideo/
├── app/                        # Next.js App Router
│   ├── api/                    # API Routes
│   │   ├── search/             # 标准搜索 API
│   │   ├── search-stream/      # 流式搜索 API
│   │   ├── search-parallel/    # 并行搜索 API
│   │   ├── detail/             # 视频详情 API
│   │   └── hot/                # 热门推荐 API
│   ├── player/                 # 播放器页面
│   ├── history/                # 历史记录页面
│   ├── layout.tsx              # 根布局组件
│   ├── page.tsx                # 首页/搜索页
│   └── globals.css             # Liquid Glass 全局样式
│
├── components/                 # React 组件
│   ├── search/                 # 搜索相关组件
│   │   ├── SearchForm.tsx      # 搜索表单
│   │   ├── VideoGrid.tsx       # 视频网格布局
│   │   ├── TypeBadges.tsx      # 类型筛选徽章
│   │   └── ResultsHeader.tsx   # 搜索结果头部
│   ├── player/                 # 播放器组件
│   │   ├── VideoPlayer.tsx     # 主播放器
│   │   ├── EpisodeList.tsx     # 剧集列表
│   │   └── VideoMetadata.tsx   # 视频元数据
│   ├── history/                # 历史记录组件
│   │   └── WatchHistorySidebar.tsx
│   ├── home/                   # 首页组件
│   │   └── PopularFeatures.tsx
│   ├── ThemeProvider.tsx       # 主题提供器
│   └── ThemeSwitcher.tsx       # 主题切换器
│
├── lib/                        # 核心逻辑库
│   ├── api/                    # API 客户端
│   │   ├── client.ts           # HTTP 请求封装
│   │   └── video-sources.ts    # 视频源配置
│   ├── hooks/                  # 自定义 React Hooks
│   │   ├── useParallelSearch.ts    # 并行搜索 Hook
│   │   ├── useSearchStream.ts      # 流式搜索 Hook
│   │   ├── useVideoPlayer.ts       # 播放器 Hook
│   │   ├── useTypeBadges.ts        # 类型筛选 Hook
│   │   └── useSearchCache.ts       # 搜索缓存 Hook
│   ├── store/                  # Zustand 状态管理
│   │   ├── history-store.ts    # 历史记录 Store
│   │   ├── player-store.ts     # 播放器 Store
│   │   └── search-history-store.ts  # 搜索历史 Store
│   ├── types/                  # TypeScript 类型定义
│   │   └── index.ts
│   └── utils/                  # 工具函数
│       ├── source-checker.ts   # 源可用性检测
│       ├── url-validator.ts    # URL 验证
│       ├── m3u8-filter.ts      # M3U8 过滤
│       ├── episode-manager.ts  # 剧集管理
│       └── progress-tracker.ts # 进度追踪
│
├── public/                     # 静态资源
├── next.config.ts              # Next.js 配置
├── tailwind.config.ts          # Tailwind 配置
├── tsconfig.json               # TypeScript 配置
└── package.json                # 项目依赖
```

### 核心模块说明

#### API Routes（/app/api）

- **search/** - 标准搜索，返回完整结果
- **search-stream/** - SSE 流式搜索，实时推送
- **search-parallel/** - 并行搜索，最快响应
- **detail/** - 获取视频详细信息和播放链接

#### Hooks（/lib/hooks）

- **useParallelSearch** - 并行搜索管理，状态同步
- **useVideoPlayer** - 播放器状态、剧集切换
- **useTypeBadges** - 类型筛选逻辑
- **useSearchCache** - localStorage 缓存管理

#### Utils（/lib/utils）

- **source-checker** - 视频源健康检查
- **url-validator** - URL 格式验证
- **m3u8-filter** - M3U8 播放列表过滤
- **episode-manager** - 剧集解析与排序

## 贡献指南

我们热烈欢迎社区贡献！无论是修复 Bug、新增功能还是改进文档，您的参与都将使 KVideo 变得更好。

在开始贡献之前，请仔细阅读我们的 **[贡献指南（CONTRIBUTING.md）](CONTRIBUTING.md)**，其中包含：

- 📋 完整的贡献流程
- 💻 代码规范和最佳实践
- 🎨 Liquid Glass UI 设计规范详解
- ✅ PR 提交检查清单
- 🧪 测试指南

### 快速开始

1. **Fork 本仓库并克隆**
   ```bash
   git clone https://github.com/YOUR_USERNAME/kvideo.git
   cd kvideo
   ```

2. **创建特性分支**
   ```bash
   git checkout -b feature/your-feature-name
   ```

3. **安装依赖并开发**
   ```bash
   npm install
   npm run dev
   ```

4. **提交更改（遵循 Conventional Commits）**
   ```bash
   git commit -m "feat: 添加某个功能"
   ```

5. **推送并创建 Pull Request**
   ```bash
   git push origin feature/your-feature-name
   ```

### 核心规范速览

**代码规范：**
- ✅ TypeScript 严格模式
- ✅ 单个文件不超过 150 行
- ✅ 遵循 [Conventional Commits](https://www.conventionalcommits.org/)

**Liquid Glass UI 设计规范：**
- ✅ 容器类组件使用 `rounded-2xl`（1.5rem）
- ✅ 圆形/胶囊组件使用 `rounded-full`
- ✅ 毛玻璃效果：`backdrop-filter: blur(25px) saturate(180%)`
- ✅ 流体动画：`cubic-bezier(0.2, 0.8, 0.2, 1)`
- ✅ 使用 CSS 变量而非硬编码颜色

详细规范请查看 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

本项目采用 **MIT 许可证**。详见 [LICENSE](LICENSE) 文件。

这意味着您可以自由地：

- ✅ 商业使用
- ✅ 修改源代码
- ✅ 分发副本
- ✅ 私人使用

唯一的要求是在所有副本或重要部分中包含版权声明和许可证声明。

```
MIT License - Copyright (c) 2025 Kuek Hao Yang
```

## 联系方式

- **作者：** Kuek Hao Yang
- **GitHub：** [@KuekHaoYang](https://github.com/KuekHaoYang)
- **项目地址：** [https://github.com/KuekHaoYang/kvideo](https://github.com/KuekHaoYang/kvideo)

### 获取帮助

- 🐛 **报告 Bug：** [提交 Issue](https://github.com/KuekHaoYang/kvideo/issues/new)
- 💡 **功能建议：** [发起讨论](https://github.com/KuekHaoYang/kvideo/discussions)
- 🤝 **贡献代码：** 查看 [贡献指南](CONTRIBUTING.md)
- 📖 **文档问题：** 通过 Issues 反馈

---

<p align="center">
  使用 ❤️ 和 <strong>Liquid Glass</strong> 设计系统打造<br>
  <em>让每一帧画面都如同触摸玻璃般流畅</em>
</p>