KVideo README

The project's README from github.com/KuekHaoYang/KVideo. As one markdown file: README.md.

Upstream Sync

Ask DeepWiki

Buy Me A Coffee

Buy Me A Coffee

视频聚合平台 (KVideo)

KVideo Banner

一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言,提供流畅的视觉体验和强大的视频搜索功能。

在线体验:https://kvideo.pages.dev/

Next.js React Tailwind CSS TypeScript License

项目简介

KVideo 是一个高性能、现代化的视频聚合与播放应用,专注于提供极致的用户体验和视觉设计。本项目利用 Next.js 16 的最新特性,结合 React 19 和 Tailwind CSS v4,打造了一个既美观又强大的视频浏览平台。

说明:仓库默认不内置任何视频源、高级源或 IPTV 源。部署者必须自行配置已获授权、可合法使用且允许当前部署方式访问的内容来源。

核心设计理念:Liquid Glass(液态玻璃)

项目的视觉设计基于 "Liquid Glass" 设计系统,这是一套融合了以下特性的现代化 UI 设计语言:

核心功能

智能视频播放

多源并行搜索

多线路折叠

IPTV 直播

豆瓣集成

个性化推荐

收藏管理

观看历史管理

弹幕 (Danmaku)

广告过滤

响应式设计

主题系统

PWA 支持

跨设备配置同步

解决 iOS Safari「添加到主屏幕」后 PWA 与浏览器之间 localStorage 不共享的问题(#119),同时实现多设备配置共享(#115)。

工作原理:

  1. 服务端存储(Upstash Redis):用户配置通过 /api/user/config API 存储在 Upstash Redis 中,使用 user:config:{profileId} 作为 key。Edge Runtime 兼容,Cloudflare Pages / Vercel 均可部署。
  2. 自动拉取(Pull):应用加载时,useConfigSync hook 从服务端拉取配置,与本地 updatedAt 时间戳比较——服务端更新时自动合并到本地。
  3. 自动推送(Push):本地设置变更后,自动延迟 3 秒推送到服务端(防抖),避免频繁写入。
  4. 同步范围:视频源 (sources)、高级源 (premiumSources)、订阅列表 (subscriptions)、屏蔽分类 (blockedCategories)、排序偏好 (sortBy)、语言 (locale)。
  5. 数据隔离:按 profileId(SHA-256 哈希)隔离,不同账户互不影响。

使用前提:

典型场景:

无障碍设计

高级模式

TV/大屏适配

Android TV 应用

Apple TV 应用

数据管理

隐私保护

本应用注重用户隐私:

账户与访问控制

KVideo 现在支持两套认证模式:

方式一:托管账户模式(推荐)

启用条件:

启用后:

强制优先托管模式:设置 MANAGED_AUTH_ENABLED=true 只会改变认证模式选择,不会跳过 AUTH_SECRET 和 Redis 检查。缺少 AUTH_SECRET、UPSTASH_REDIS_REST_URL 或 UPSTASH_REDIS_REST_TOKEN 时,托管账户模式仍不会启用。 首次启用时,如果 Redis 里还没有账户,会自动使用 ADMIN_PASSWORD 和 ACCOUNTS 作为引导种子创建首批托管账户。

方式二:单管理员密码(环境变量模式)

通过 ADMIN_PASSWORD 环境变量设置管理员密码:

# Docker
docker run -d -p 3000:3000 -e ADMIN_PASSWORD=your_password --name kvideo kuekhaoyang/kvideo:latest

登录后自动获得超级管理员权限,可管理所有设置。

向后兼容:ACCESS_PASSWORD 环境变量仍然有效,当 ADMIN_PASSWORD 未设置时,ACCESS_PASSWORD 将作为管理员密码使用。

方式三:多账户系统(环境变量模式)

通过 ACCOUNTS 环境变量配置多个账户,每个账户拥有独立的数据空间(收藏、历史、设置、个人源等)。

兼容格式:

多个账户之间用逗号分隔。

# 基本用法
docker run -d -p 3000:3000 \
  -e ACCOUNTS="pass1:张三:admin,pass2:李四:viewer,pass3:王五" \
  --name kvideo kuekhaoyang/kvideo:latest

# 为观众添加额外权限(如 IPTV 访问和源管理)
docker run -d -p 3000:3000 \
  -e ACCOUNTS="pass1:张三:admin,pass2:李四:viewer:iptv_access|source_management" \
  --name kvideo kuekhaoyang/kvideo:latest

KVideo (KuekHaoYang/KVideo)

Searching Database…

4.2K ·GitHub
What is this?KVideo is a self-hosted video aggregation and streaming platform built with Next.js 16, featuring a 'Liquid Glass' glassmorphism UI, parallel multi-source search, IPTV live TV, and a danmaku comment overlay.
Is this a hosted service or something I deploy myself?It is self-hosted: you run the image yourself (for example via Docker) and point it at your own legally-available video sources; there is no managed KVideo service.
How do I deploy it?Pull and run the Docker image exposing port 3000, set login via ACCOUNTS or ADMINPASSWORD env vars, then add your own video sources from the settings page.
Does it come with any video sources built in?No, the repo ships with zero built-in video, premium or IPTV sources; you must configure your own authorized, legally-accessible sources after deploying.
What do I need for cross-device config sync to work?Without an Upstash Redis instance (UPSTASHREDISRESTURL/TOKEN), settings and sources stay local to each browser; with Redis configured, sources, subscriptions and preferences sync automatically across devices and PWA installs, including the iOS Safari 'add to home screen' case.
Can I use this on a TV instead of just in a browser?Yes — besides a responsive web UI with TV spatial/remote navigation, there are dedicated lightweight WebView apps for Android TV and a SwiftUI app for Apple TV (tvOS) that just load your deployed instance.
What is the 'Liquid Glass' design about?It is KVideo's visual design system built around frosted glass backdrop-filter effects, consistent rounded corners, glowing hover/focus states, and physics-based cubic-bezier animations for a cohesive, modern feel.
Does it support IPTV live channels in addition to on-demand video?Yes, it imports M3U/M3U8 playlists or JSON channel lists, auto-detects HEVC playback issues, proxies streams to fix CORS/User-Agent problems, and auto-switches to the lowest-latency source when a channel fails.
How does the danmaku (scrolling comments) feature work?KVideo connects to a self-hosted danmuapi-compatible aggregation API and renders hundreds of scrolling/top/bottom comments on a Canvas overlay without hurting playback performance, with adjustable opacity, font size and screen coverage.
Can I block ads during playback?Yes, there is a built-in ad filter with keyword, heuristic (beta), and aggressive modes that you can switch live from the player's settings menu.
Size
3.1 MB
Stars
4.2K
Age
11mo
Commits · 90 Days