README_EN.md

LunaTV Enhanced Edition

🎬 LunaTV Enhanced Edition is a comprehensive video streaming platform deeply customized from MoonTV. Built on top of the original version, it adds 50+ major feature enhancements including YouTube Integration, Cloud Drive Search, AI Recommendations, Short Drama, IPTV Live TV, Bangumi Anime, Playback Statistics, Danmaku System, and more, delivering the ultimate online streaming experience.

📢 Project Overview

This project is a deeply customized version based on MoonTV, continuously developed from v4.3.1 to the current v5.7.0, with 50+ major feature modules and 300+ detailed optimizations added. See CHANGELOG for all new features.

💡 Core Enhancement Highlights

🎥 Content Ecosystem Expansion

YouTube Integration: Complete YouTube search, playback, live streaming with cookieless domain support
Cloud Drive Search (PanSou): Integrated advanced filtering and cache management
Short Drama Features: Search, playback, dedicated detail pages, mobile API proxy
IPTV Live TV: m3u/m3u8 subscriptions, EPG program guide (multi-source & url-tvg support), source aggregation, logo proxy, channel search within current source, live source tab quick search
Bangumi Anime: Intelligent anime detection, API integration, caching mechanism

🤖 AI Recommendation System

AI Content Recommendations: Support for GPT-5/o series models, dynamic prompt management
Multiple Card Types: Video recommendations, YouTube videos, video link parsing
TMDB Actor Search: Complete actor search, filtering, and caching
Release Calendar & Upcoming Releases: Upcoming content preview and tracking, support favoriting upcoming releases, automatically becomes playable after release

💬 Danmaku Ecosystem

Third-party Danmaku API: Integrated Tencent Video, iQiyi, Youku, Bilibili platforms, smart content matching prevents trailers
Smart Performance Optimization: Device-based tiered rendering, Web Worker acceleration, hardware acceleration
Complete Configuration System: Font size, speed, opacity, display area, anti-overlap adjustments
Smart Caching: localStorage persistence, 30-minute cache, auto cleanup of expired data
Web-exclusive Input: Simple "Danmu" button for quick sending (auto-hidden on mobile)

📊 User Management Enhancement

Telegram Magic Link Authentication: Secure and convenient Telegram-based login with auto webhook configuration
User Level System: Replaces large login count numbers with friendly level display
Playback Statistics: Complete viewing data statistics, analysis, visualization, global/personal stats tab switching
Dual Reminder System: New episodes (red theme) and continue watching (blue theme) with gradient badges and halo effects
User Group Permissions: Fine-grained permission control for AI Assistant, YouTube features
Inactive User Cleanup: Smart auto-cleanup with detailed configuration and logging

🎮 Player Feature Enhancement

Chromecast Casting: Smart browser detection, auto-excludes OPPO, Xiaomi, Huawei, Samsung vendor browsers
iPad/iOS Optimization: HLS.js official source optimization, smart device detection, multi-attempt autoplay strategy
Skip Intro/Outro: Real-time marking button, draggable floating config window, remaining time mode, position persistence
Live DVR Detection: Auto-detect DVR/timeshift support after player loads, display seekable time range, one-click enable progress bar mode
Mobile Optimization: Volume control hover optimization, responsive controller, danmaku config desktop-only display
Episode Group Scrolling: Playback page episode selection supports scroll pagination for smooth browsing

📱 Interface Experience Optimization

Hero Banner Full Category Support: Homepage auto-rotating hero banner supports all content types (movies, series, variety shows, short dramas, anime), gradient background design
Modern Navigation UI: Desktop horizontal top navbar, mobile Liquid Glass bottom navigation, responsive switching
Mobile Banner Optimization: Swipeable card-style layout with touch gesture navigation, better suited for mobile devices
Mobile Layout Optimization: Reduced header height, tighter layout design, fixed excessive spacing issues
Virtual Scrolling: react-window 2.2.0, smooth loading for massive content, smart container size detection (ResizeObserver)
Virtual Scrolling Toggle: Gradient styles, icons, animations, user switchable display modes
Responsive Grid: 2-8 column adaptive, auto-calculated optimal layout
Douban Details Enhancement: Complete rating, cast & crew, premiere date, duration, production info, poster proxy to prevent 403 errors
Celebrity Avatars & Recommendations: Play page displays celebrity avatars (supports celebrity and personage URLs), similar movie recommendations, smart image proxy (auto-migrate from direct to server mode)
User Menu Features: Update reminders, continue watching (with new episode badges), favorites quick access, TVBox settings integration
Login Interface Modernization: Dynamic random wallpapers, gradient cards, responsive design
Back to Top Button: Quick return for long pages like release calendar

🔐 Security & Storage

TVBox Complete Ecosystem:
- IP whitelist, user-specific Token authentication, full API compatibility, intelligent search proxy
- TVBox Intelligent Search Proxy with adult content filtering, path prefix support, UI controls
- Deep JAR diagnostic system (file header verification, smart health check)
- Spider management system (multi-Spider JAR backup sources, fallback proxy, gaotianliuyun third backup source)
- Regular user access support (/api/tvbox-config endpoint)
Adult Content Management: Dual-layer filtering system, auto-detection, batch operations, user/group-level controls
Video Source Import/Export: Array/config file format export, backup & migration, quick copy buttons
Source Browser & Testing Module: Source testing, health checks, mobile responsive layout
Resource Search API Authentication: Enhanced security with user authentication
Calendar Cache Migration: Migrated from localStorage to database, cross-device sync support
Cache Optimization: Unified cache management (YouTube, cloud drive, Douban, danmaku)
Enhanced Storage Modes: Full Kvrocks/Redis/Upstash support, memory cache prevents QuotaExceededError
User Registration System (configurable toggle)

⚠️ Important Notices

📦 Project Status

Notice: After deployment, this is an empty shell project with no built-in video sources or live streaming sources. You need to collect and configure them yourself.
Demo Sites:
- Zeabur Deployment: https://smonetv.zeabur.app
- Vercel Deployment: https://lunatv.smone.us
- For short-term testing. Database is cleaned regularly.

🚫 Distribution Restrictions

Do NOT promote this project on Bilibili, Xiaohongshu (RedNote), WeChat Official Accounts, Douyin (TikTok China), Toutiao, or other Chinese mainland social platforms through videos or articles. This project does NOT authorize any "Tech Weekly/Monthly" projects or sites to include it.

📜 Open Source License

This project is licensed under CC BY-NC-SA 4.0, with the following terms:

❌ Commercial use is prohibited
✅ Personal learning and use is allowed
✅ Derivative works and distribution are allowed
⚠️ Any derivative projects must retain this project's address and be open-sourced under the same license

✨ Complete Feature List

🎬 Content Aggregation

✅ Multi-source video aggregation search (streaming output, smart variants, language-aware filtering)
✅ YouTube integration (search, live streaming, iframe playback, time filtering & sorting)
✅ Cloud drive search (PanSou integration, advanced filtering, cache management)
✅ Short drama features (search, playback, dedicated detail pages, mobile API proxy)
✅ IPTV live TV (m3u subscriptions, EPG guide, multi-source support, url-tvg, source aggregation, channel search)
✅ Bangumi anime (info detection, API integration, 3-6 digit ID support)
✅ TMDB actor search (filtering, caching)

🤖 Smart Recommendations

✅ AI recommendation system (GPT-5/o support, dynamic prompts)
✅ Release calendar (upcoming content preview)
✅ Douban details enhancement (complete cast & crew info)
✅ Smart search optimization (language-aware, fuzzy matching)

💬 Danmaku System

✅ Third-party danmaku API (Tencent, iQiyi, Youku, Bilibili, caiji.cyou multi-platform aggregation)
✅ Smart content matching (auto-filter commentary, trailers, irrelevant content)
✅ Smart performance optimization (device tiering, Web Worker, hardware acceleration, segmented loading)
✅ Complete configuration (font size, speed, opacity, display area, anti-overlap, type masking)
✅ Smart caching (localStorage, 30-min expiry, page refresh persistence)
✅ Danmaku input (web-only "Danmu" button, auto-hidden on mobile)
✅ EXT-X-MEDIA URI handling (prevents HLS audio track loading errors)

📊 User Management

✅ Telegram Magic Link authentication (secure convenient login, auto webhook config)
✅ User level system (replaces large login count numbers)
✅ Playback statistics (watch time, video count, recent records, global/personal tab switching)
✅ Dual reminder system (new episodes red theme, continue watching blue theme, gradient badges)
✅ VideoCard watch update display (replaces popup-style updates)
✅ User group permissions (AI, YouTube feature control)
✅ Inactive user auto-cleanup (smart config, logging)
✅ Login time tracking (enhanced admin analytics)

🎮 Player Enhancement

✅ Chromecast casting (smart browser detection, excludes vendor browsers)
✅ iPad/iOS optimization (HLS.js official source optimization, smart device detection, multi-attempt autoplay retry)
✅ Skip intro/outro (real-time marking button, draggable floating window, remaining time mode, cross-episode support)
✅ Live DVR detection (auto-detect DVR/timeshift support after player loads, display seekable time range, one-click enable progress bar mode)
✅ Danmaku config panel (desktop display, mobile hidden)
✅ Volume control optimization (hover area optimization, precise detection)
✅ Episode switching optimization (debounce, state management, correct playback time reset)
✅ Episode group scroll pagination (smooth browsing for large episode counts)

🎨 Interface Experience

✅ Hero banner (homepage auto-rotating, gradient backgrounds, enhanced visual appeal, full category support for all content types)
✅ Modern navigation UI (desktop horizontal top bar, mobile Liquid Glass bottom nav, responsive switching)
✅ Mobile banner optimization (swipeable card-style layout, touch gesture navigation, better mobile experience)
✅ Mobile layout optimization (reduced header height, tighter layout, fixed excessive spacing)
✅ Virtual scrolling (react-window 2.2.0, ResizeObserver smart detection, progressive loading)
✅ Virtual scrolling toggle (gradient styles, icons, animations, user switchable)
✅ Responsive grid (2-8 column adaptive, actual container width dynamic calculation)
✅ Douban details enhancement (rating, cast & crew, premiere date, duration, production info, poster proxy to prevent 403)
✅ User menu enhancement (update reminders, continue watching with new episode badges, favorites quick access, TVBox settings)
✅ Login/register modernization (dynamic random wallpapers, gradient cards, responsive design)
✅ Back to top button (long pages like release calendar)
✅ Completed series badges (based on vod_remarks, search API priority)
✅ Search result filtering (source, title, year filtering, year sorting)
✅ Video card right-click/long-press menu (new tab play, favorites, etc.)
✅ z-index hierarchy optimization (cards, badges, modals display correctly)

🔐 Security & Storage

✅ TVBox complete ecosystem (IP whitelist, user-specific Token auth, full API compatibility, intelligent search proxy)
✅ TVBox intelligent search proxy (adult content filtering, path prefix support, UI controls)
✅ Adult content management system (dual-layer filtering, auto-detection, batch operations, user/group-level controls)
✅ Video source import/export (array/config file formats, backup & migration, quick copy buttons)
✅ TVBox deep diagnostics (JAR file header verification, smart health check, config field display)
✅ Spider management system (multi-JAR backup sources, fallback proxy, gaotianliuyun third backup source)
✅ Source browser & testing module (source testing, health checks, mobile responsive)
✅ Resource search API authentication (enhanced security)
✅ Calendar cache database migration (cross-device sync)
✅ Unified cache management system (YouTube, cloud drive, Douban, danmaku)
✅ Kvrocks/Redis/Upstash storage (full compatibility handling)
✅ Memory cache prevents QuotaExceededError (Kvrocks/Upstash memory cache)
✅ User registration system (configurable toggle, admin user creation)
✅ Cross-device original episode tracking (prevents API cache issues)

🛠️ Technical Optimization

✅ ArtPlayer 5.3.0 + HLS.js 1.6.15 (official source optimization)
✅ Danmaku plugin 5.2.0 (Web Worker acceleration, useWorker: true, lockTime: 2)
✅ Next.js SSR compatibility (dynamic import, client-side loading)
✅ Docker build optimization (no-cache flag, dependency verification)
✅ TypeScript type safety (const assertion, type annotations)
✅ Semantic versioning (Git tag-based, CHANGELOG auto-extraction)
✅ HLS.js mobile optimization (buffer strategy, memory management, ABR optimization)
✅ Douban details engine refactor (accurate parsing based on real HTML structure)

🗺 Table of Contents

🔧 Tech Stack

Category	Main Dependencies
Frontend	Next.js 14.2.23 · App Router
UI & Styling	Tailwind CSS 3.4.17 · Framer Motion 12
Language	TypeScript 4.9.5
Player	ArtPlayer 5.3.0 · HLS.js 1.6.15 · artplayer-plugin-danmuku 5.2.0
State Mgmt	React Context API · React Hooks
Data Storage	Kvrocks · Redis · Upstash · localStorage
Virtualization	react-window 2.2.0 · ResizeObserver
UI Components	@headlessui/react 2 · Lucide Icons · React Icons 5
Code Quality	ESLint · Prettier · Jest · Husky
Deployment	Docker · Docker Compose

🚀 Deployment

⚡ One-Click Deploy to Zeabur (Easiest)

Click the button below for one-click deployment, automatically configures LunaTV + Kvrocks database:

Advantages:

✅ Zero configuration, instant startup (auto-deploy complete environment)
✅ Automatic HTTPS and global CDN acceleration
✅ Persistent storage, data never lost
✅ Free tier sufficient for personal use

⚠️ Important Notice: After deployment completes, you need to set up an access domain (Domain) for the LunaTV service in Zeabur before you can access it in your browser. See the Set Up Access Domain step below for details.

After clicking the button, just fill in the environment variables to complete deployment! See Zeabur Deployment Guide below for details.

🐳 Docker Self-Hosted Deployment

This project only supports Docker or Docker-based platforms (such as Dockge, Portainer, Komodo, etc.).

📦 Recommended: Kvrocks Storage

Kvrocks is a persistent Redis-compatible storage based on RocksDB, recommended for production environments.

services:
  moontv-core:
    image: ghcr.io/szemeng76/lunatv:latest
    container_name: moontv-core
    restart: on-failure
    ports:
      - '3000:3000'
    environment:
      - USERNAME=admin
      - PASSWORD=your_secure_password
      - NEXT_PUBLIC_STORAGE_TYPE=kvrocks
      - KVROCKS_URL=redis://moontv-kvrocks:6666
      # Optional: Site configuration
      - SITE_BASE=https://your-domain.com
      - NEXT_PUBLIC_SITE_NAME=LunaTV Enhanced
    networks:
      - moontv-network
    depends_on:
      - moontv-kvrocks

  moontv-kvrocks:
    image: apache/kvrocks
    container_name: moontv-kvrocks
    restart: unless-stopped
    volumes:
      - kvrocks-data:/var/lib/kvrocks
    networks:
      - moontv-network

networks:
  moontv-network:
    driver: bridge

volumes:
  kvrocks-data:

🔴 Redis Storage (Risk of Data Loss)

Redis default configuration may lead to data loss. Persistence must be enabled.

services:
  moontv-core:
    image: ghcr.io/szemeng76/lunatv:latest
    container_name: moontv-core
    restart: on-failure
    ports:
      - '3000:3000'
    environment:
      - USERNAME=admin
      - PASSWORD=your_secure_password
      - NEXT_PUBLIC_STORAGE_TYPE=redis
      - REDIS_URL=redis://moontv-redis:6379
    networks:
      - moontv-network
    depends_on:
      - moontv-redis

  moontv-redis:
    image: redis:alpine
    container_name: moontv-redis
    restart: unless-stopped
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - ./data:/data
    networks:
      - moontv-network

networks:
  moontv-network:
    driver: bridge

☁️ Upstash Cloud Storage (Docker)

Suitable for scenarios where self-hosted databases are not available. Fully managed Redis service.

Register an account at upstash.com and create a Redis instance
Copy HTTPS ENDPOINT and TOKEN
Use the following configuration:

services:
  moontv-core:
    image: ghcr.io/szemeng76/lunatv:latest
    container_name: moontv-core
    restart: on-failure
    ports:
      - '3000:3000'
    environment:
      - USERNAME=admin
      - PASSWORD=your_secure_password
      - NEXT_PUBLIC_STORAGE_TYPE=upstash
      - UPSTASH_URL=https://your-instance.upstash.io
      - UPSTASH_TOKEN=your_upstash_token

☁️ Zeabur Deployment (Recommended)

Zeabur is a one-stop cloud deployment platform. Using pre-built Docker images allows for quick deployment without waiting for builds.

Deployment Steps:

Add KVRocks Service (Add database first)
- Click "Add Service" > "Docker Images"
- Enter image name: apache/kvrocks
- Configure port: 6666 (TCP)
- Remember the service name (usually apachekvrocks)
- Configure Persistent Volume (Important):
  - Find "Volumes" section in service settings
  - Click "Add Volume" to add new volume
  - Volume ID: kvrocks-data (customizable, only letters, numbers, and hyphens)
  - Path: /var/lib/kvrocks/db
  - Save configuration
💡 Important: Persistent volume path must be set to /var/lib/kvrocks/db (KVRocks data directory). This keeps config files in the container while persisting database files, preventing data loss on restart!
Add LunaTV Service
- Click "Add Service" > "Docker Images"
- Enter image name: ghcr.io/szemeng76/lunatv:latest
- Configure port: 3000 (HTTP)

Configure Environment Variables

Add the following environment variables to your LunaTV service:

# Required: Admin Account
USERNAME=admin
PASSWORD=your_secure_password

# Required: Storage Configuration
NEXT_PUBLIC_STORAGE_TYPE=kvrocks
KVROCKS_URL=redis://apachekvrocks:6666

# Optional: Site Configuration
SITE_BASE=https://your-domain.zeabur.app
NEXT_PUBLIC_SITE_NAME=LunaTV Enhanced
ANNOUNCEMENT=Welcome to LunaTV Enhanced Edition

# Optional: Douban Proxy (Recommended)
NEXT_PUBLIC_DOUBAN_PROXY_TYPE=cmliussss-cdn-tencent
NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE=cmliussss-cdn-tencent

Note:

Use service name as hostname: redis://apachekvrocks:6666
Replace with actual service name if different
Both services must be in the same Project

Deployment Complete
- Zeabur will automatically pull images and start services
- After services are ready, you need to manually set up an access domain (see next step)

5. Set Up Access Domain (Required)

In the LunaTV service page, click the "Networking" or "Network" tab
Click "Generate Domain" to create a free Zeabur domain (e.g., xxx.zeabur.app)
Or bind a custom domain:
- Click "Add Domain" to add your domain
- Follow the prompts to configure DNS CNAME record pointing to the Zeabur-provided target
Once the domain is set up, you can access LunaTV through the domain

Bind Custom Domain (Optional)
- In service settings, click "Domains"
- Add your custom domain
- Configure DNS CNAME record to point to the Zeabur-provided domain

🔄 Updating Docker Images

When a new Docker image version is released, Zeabur won't automatically update. Manual trigger is required.

Update Steps:

Enter Service Page
- Click on the service you want to update (LunaTV or KVRocks)
Restart Service
- Click on the "Overview" page, and then click the "Restart" button
- Zeabur will automatically pull the latest latest image and redeploy

💡 Tips:

When using latest tag, Restart will automatically pull the latest image

For production environments, it's recommended to use fixed version tags (e.g., v5.5.5) to avoid unexpected updates

✨ Zeabur Deployment Advantages

✅ Automatic HTTPS: Free SSL certificate auto-configured
✅ Global CDN: Built-in worldwide acceleration
✅ Zero-Config Deployment: Automatic Dockerfile detection
✅ Service Discovery: Containers communicate via service names automatically
✅ Persistent Storage: Volume mounting support
✅ CI/CD Integration: Auto-deployment on Git push
✅ Real-time Logs: Web interface for runtime logs

⚠️ Zeabur Considerations

Pricing Model: Pay-as-you-go based on actual resource usage, free tier sufficient for small projects
Region Selection: Recommend choosing the region closest to your users
Service Networking: Services in the same Project communicate via service names (e.g., apachekvrocks:6666)
Persistent Storage: KVRocks must configure persistent volume to /var/lib/kvrocks/db directory, otherwise data will be lost on restart

🌐 Vercel Deployment (Serverless)

Vercel + Upstash Solution

Perfect for users without servers. Completely free deployment (Vercel Free Tier + Upstash Free Tier).

Prerequisites

Create Upstash Redis Instance
- Visit upstash.com
- Register and create a new Redis database
- Select region (choose the closest to your location)
- Copy REST URL and REST TOKEN
Fork This Project
- Fork this repository to your GitHub account

Deployment Steps

Import to Vercel
- Visit vercel.com
- Login and click "Add New" > "Project"
- Import your forked repository
- Click "Import"

Configure Environment Variables

Add the following environment variables in Vercel project settings:

# Required: Admin Account
USERNAME=admin
PASSWORD=your_secure_password

# Required: Storage Configuration
NEXT_PUBLIC_STORAGE_TYPE=upstash
UPSTASH_URL=https://your-redis-instance.upstash.io
UPSTASH_TOKEN=AxxxxxxxxxxxxxxxxxxxxxxxxxxxQ==

# Optional: Site Configuration
SITE_BASE=https://your-domain.vercel.app
NEXT_PUBLIC_SITE_NAME=LunaTV Enhanced
ANNOUNCEMENT=Welcome to LunaTV Enhanced Edition

# Optional: Douban Proxy (Recommended)
NEXT_PUBLIC_DOUBAN_PROXY_TYPE=cmliussss-cdn-tencent
NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE=cmliussss-cdn-tencent

# Optional: Search Configuration
NEXT_PUBLIC_SEARCH_MAX_PAGE=5
NEXT_PUBLIC_FLUID_SEARCH=true

Deploy Project
- Click "Deploy" button
- Wait for build to complete (approximately 2-5 minutes)
- Access the domain provided by Vercel after successful deployment
Bind Custom Domain (Optional)
- Click "Domains" in Vercel project settings
- Add your custom domain
- Configure DNS resolution as instructed

⚠️ Vercel Deployment Limitations

Serverless Constraints: Vercel free tier has 10-second function execution time limit, some time-consuming operations may timeout
Traffic Limit: Vercel free tier provides 100GB monthly bandwidth, sufficient for personal use
Cold Start: First visit after long inactivity may be slower (approximately 1-3 seconds)
Limited Features: Due to serverless architecture, the following features may be restricted:
- High concurrent search requests
- Long video danmaku loading
- Complex data analytics

💡 Vercel Deployment Advantages

✅ Completely Free: Vercel and Upstash free tiers are sufficient for personal use
✅ Zero Maintenance: No server management required, auto-scaling
✅ Global CDN: Fast access worldwide
✅ Auto Deployment: Automatic deployment on code push
✅ HTTPS Support: Automatic SSL certificate configuration

⚙️ Configuration File

After deployment, it's an empty shell application. You need to fill in the configuration in Admin Panel > Configuration File.

📝 Configuration Format

{
  "cache_time": 7200,
  "api_site": {
    "example_source": {
      "api": "http://example.com/api.php/provide/vod",
      "name": "Example Resource",
      "detail": "http://example.com"
    }
  },
  "custom_category": [
    {
      "name": "Chinese Movies",
      "type": "movie",
      "query": "华语"
    },
    {
      "name": "US TV Series",
      "type": "tv",
      "query": "美剧"
    }
  ]
}

📖 Field Description

cache_time: API cache duration (seconds), recommended 3600-7200
api_site: Video resource site configuration
- key: Unique identifier (lowercase letters/numbers)
- api: Resource site vod JSON API address (supports Apple CMS V10 format)
- name: Display name in the interface
- detail: (Optional) Web detail root URL for scraping episode details
custom_category: Custom categories (based on Douban search)
- name: Category display name
- type: movie (movies) or tv (TV series)
- query: Douban search keyword

🎯 Recommended Custom Categories

Movie Categories: Popular, Latest, Classic, High-rated, Hidden Gems, Chinese, Western, Korean, Japanese, Action, Comedy, Romance, Sci-Fi, Mystery, Horror, Healing

TV Series Categories: Popular, US Series, UK Series, Korean Drama, Japanese Drama, Chinese Drama, Hong Kong Drama, Japanese Animation, Variety Shows, Documentaries

You can also enter specific content like "Harry Potter", which works the same as Douban search.

🌐 Environment Variables

Required Variables

Variable	Description	Example Value
`USERNAME`	Admin account	`admin`
`PASSWORD`	Admin password	`your_secure_password`
`NEXT_PUBLIC_STORAGE_TYPE`	Storage type	`kvrocks` / `redis` / `upstash`

Storage Configuration

Variable	Description	Example Value
`KVROCKS_URL`	Kvrocks connection URL	`redis://moontv-kvrocks:6666`
`REDIS_URL`	Redis connection URL	`redis://moontv-redis:6379`
`UPSTASH_URL`	Upstash endpoint	`https://xxx.upstash.io`
`UPSTASH_TOKEN`	Upstash Token	`AxxxxxxxxxxxxxxxxxxxxxxxxxxxQ==`

Optional Configuration

Variable	Description	Default	Options
`SITE_BASE`	Site URL	Empty	`https://example.com`
`NEXT_PUBLIC_SITE_NAME`	Site name	`MoonTV`	Any string
`ANNOUNCEMENT`	Site announcement	Default	Any string
`NEXT_PUBLIC_SEARCH_MAX_PAGE`	Max search pages	`5`	`1-50`
`NEXT_PUBLIC_DOUBAN_PROXY_TYPE`	Douban data proxy type	`direct`	`direct` / `cors-proxy-zwei` / `cmliussss-cdn-tencent` / `cmliussss-cdn-ali` / `custom`
`NEXT_PUBLIC_DOUBAN_PROXY`	Custom Douban proxy	Empty	URL prefix
`NEXT_PUBLIC_DOUBAN_IMAGE_PROXY_TYPE`	Douban image proxy type	`direct`	`direct` / `server` / `img3` / `cmliussss-cdn-tencent` / `cmliussss-cdn-ali` / `custom`
`NEXT_PUBLIC_DOUBAN_IMAGE_PROXY`	Custom image proxy	Empty	URL prefix
`NEXT_PUBLIC_DISABLE_YELLOW_FILTER`	Disable adult filter	`false`	`true` / `false`
`NEXT_PUBLIC_FLUID_SEARCH`	Streaming search output	`true`	`true` / `false`

Douban Proxy Options

DOUBAN_PROXY_TYPE Options:

direct: Server directly requests Douban (may be blocked)
cors-proxy-zwei: Via CORS proxy provided by Zwei
cmliussss-cdn-tencent: Tencent Cloud CDN provided by CMLiussss
cmliussss-cdn-ali: Alibaba Cloud CDN provided by CMLiussss
custom: Custom proxy (requires DOUBAN_PROXY)

DOUBAN_IMAGE_PROXY_TYPE Options:

direct: Browser directly requests Douban image domain
server: Server proxies requests
img3: Douban official Alibaba Cloud CDN
cmliussss-cdn-tencent: CMLiussss Tencent Cloud CDN
cmliussss-cdn-ali: CMLiussss Alibaba Cloud CDN
custom: Custom proxy (requires DOUBAN_IMAGE_PROXY)

🎛️ Feature Configuration

All features can be configured in the Admin Panel without modifying code or restarting services.

Admin Panel Access

Visit http://your-domain:3000/admin and login with admin account.

Admin Panel Feature Modules

The admin panel provides the following feature modules (some features are owner-only):

📁 Configuration File (Owner Only)

Configuration Subscription:
- Subscription URL settings
- Auto-fetch remote configuration
- Support for Base58 encoded JSON format
Configuration File Editor:
- JSON format configuration editor
- Online save configuration

⚙️ Site Configuration

Basic Settings:
- Site name
- Site announcement
Douban Data Proxy:
- Direct/Cors Proxy/Douban CDN/Custom proxy
- Custom proxy URL
Douban Image Proxy:
- Direct/Server proxy/Official CDN/Custom proxy
- Custom image proxy URL
Search Interface Settings:
- Max search pages (1-50)
- API cache time (seconds)
- Fluid search toggle
Content Filtering:
- Adult content filter toggle
TMDB Actor Search:
- TMDB API Key
- Language settings (Chinese/English/Japanese/Korean)
- Feature enable toggle

👥 User Configuration

User Registration Settings (Owner Only):
- User registration toggle
- Auto cleanup inactive users
- Retention days configuration
User Group Management:
- Add/Edit/Delete user groups
- Available video source permission configuration
User List:
- Batch assign user groups
- Add/Edit users
- Change password
- Ban/Unban users
- Set admin privileges
- Delete users

🎬 Video Source Configuration

Video Source Management:
- Add video source (name, API address)
- Batch enable/disable/delete
- Import/Export video sources (batch config management for backup and migration)
- Video source validity detection
- Drag-and-drop sorting
- Edit/Delete individual sources
Source Browser & Testing Module:
- Browse and search source content
- Source testing and health checks
- Mobile responsive layout
- Side drawer test results display

📺 Live Source Configuration

Live Source Management:
- Add live source (name, m3u/m3u8 address)
- Refresh live source data
- Drag-and-drop sorting
- Edit/Delete live sources

🏷️ Category Configuration

Custom Categories:
- Add/Edit custom categories
- Drag-and-drop sorting
- Douban search-based categories

🔍 Cloud Drive Search Configuration

Basic Settings:
- Cloud drive search feature toggle
- PanSou service address
- Request timeout
Supported Cloud Disk Types:
- Baidu Netdisk, Aliyun Drive, Quark, Tianyi Cloud
- UC Drive, Mobile Cloud, 115 Drive, PikPak
- Xunlei, 123 Drive
- Magnet links, ED2K links

🤖 AI Recommendation Configuration

OpenAI API configuration
Model selection and parameters
Recommendation prompt management

🎥 YouTube Configuration

YouTube Data API v3 key
Search and cache configuration
Feature enable toggle

🔐 TVBox Security Configuration

IP whitelist management
Token authentication configuration
TVBox API settings

🗄️ Cache Management (Owner Only)

View and clear various caches
YouTube, cloud drive, Douban, danmaku cache statistics

📦 Data Migration (Owner Only)

Import/Export entire site data
Database migration tools

🔄 Auto Update

Using Watchtower

Watchtower can automatically detect and update Docker containers to the latest images.

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 86400 --cleanup
    restart: unless-stopped

UI Tools Auto Update

Dockge: Built-in auto-update feature
Portainer: Supports container image auto-update
Komodo: Provides auto-update configuration options

📱 Mobile App Usage

Selene - Official Mobile Client

Selene is the official mobile app developed by the original MoonTV author, built with Flutter and optimized for mobile phones.

Supported Platforms

Android: 5.0+ (API 21), ARM64 architecture only
iOS: 12.0+

Key Features

🎨 Modern Material Design 3 interface
🌗 Dark/light theme support
🔍 Multi-source aggregated search (with SSE real-time search)
▶️ High-performance FVP video player
📊 Smart playback tracking
❤️ Personal favorites management
🎬 Support for movies, TV series, anime, variety shows

Usage Instructions

Download the latest version from Selene Releases
- Android: Download .apk file
- iOS: Download .ipa file (requires self-signing)
Install the app on your phone
Open the app, fill in your server domain in settings: https://your-domain.com
Login with admin or regular user account
All playback records and favorites will sync with the web version automatically

Important Notes

⚠️ Selene is optimized for mobile phones, NOT compatible with tablets, TVs, emulators
⚠️ For Android TV or tablets, please use OrionTV below

📺 AndroidTV / Tablet Usage

OrionTV - Large Screen Client

This project works with OrionTV on Android TV and tablets.

Applicable Scenarios

Android TV / Smart TVs
Android tablets
Large screen devices

Configuration Steps

Install OrionTV on your device
Configure backend address in OrionTV: http://your-domain:3000
Login with admin or regular user account
Playback records will sync with web and Selene automatically

📜 Changelog

For complete feature updates and bug fixes, see CHANGELOG.

Latest Version: v5.7.0 (2025-12-06)

Added

🎭 Celebrity Avatars and Recommendations: Display celebrity avatars and similar movie recommendations on play page
🔍 Live Source Tab Search: Add search functionality to live source tabs for quick channel lookup

Improved

🖼️ Default Image Proxy Mode Changed to Server: Changed default image proxy from direct to server mode across all components
📅 Celebrity Info Display Optimization: Add tooltips for celebrity names and roles to prevent text truncation
📦 Dependency Upgrade: Upgrade hls.js to v1.6.15

Fixed

🖼️ Fix Celebrity Avatar Display Issues:
- Support both /celebrity/ and /personage/ URL formats
- Filter default placeholder avatars
- Implement automatic image proxy fix (migrate from direct to server mode)
- Auto-migrate legacy localStorage configurations
📱 Fix Recommendation Card Mobile Navigation:
- Use capture phase event listeners to intercept VideoCard internal events
- Add long press detection (500ms) to preserve action menu functionality
- Fix mobile tap jumping to page top issue
- Preserve all VideoCard hover effects and UI display
🎯 Fix Recommendation Card Event Conflicts:
- Use addEventListener capture mode to prioritize event interception
- Add stopImmediatePropagation to prevent event interference
- Short tap navigates, long press shows menu, perfect mobile and desktop compatibility
🔧 Fix Date Calculation Inconsistency: Fix date calculation differences between homepage and release calendar

Major Milestone Versions

v5.7.0: Celebrity Avatars & Recommendations, Live Source Search, Image Proxy Optimization, Mobile Navigation Fixes
v5.6.3: Short Drama Multi-source Search, Smart Source Filtering, Upcoming Smart Distribution, Comprehensive z-index Conflict Fixes
v5.6.2: Upcoming Release Calendar, Hero Banner Full Category Support, Live DVR Detection, Mobile Banner Optimization
v5.6.1: Hero Banner & Modern Navigation UI, TVBox Intelligent Search Proxy, Export Format Selection
v5.6.0: Telegram Magic Link authentication, Source Browser & Testing Module, video source import/export
v5.5.0: User level system, release calendar, inactive user cleanup
v5.4.0: Complete short drama features, playback statistics system
v5.3.0: YouTube integration, AI recommendation system, TVBox security config
v5.2.0: ArtPlayer 5.3.0 upgrade, cloud drive search integration
v5.1.0: Bangumi API, IPTV features, virtual scrolling support
v5.0.0: Douban details engine refactoring
v4.3.1: User registration, danmaku system foundation

View Complete Changelog for all version changes.

🔐 Security & Privacy Notice

⚠️ Important Security Recommendations

Set Strong Password: Use a complex PASSWORD environment variable
Disable Public Registration: Close user registration in admin panel
Personal Use Only: Do not publicly share or distribute your instance link
Comply with Local Laws: Ensure usage complies with local laws and regulations

📋 Disclaimer

This project is for educational and personal use only
Do not use for commercial purposes or public services
All content comes from third-party websites, this site stores no video resources
Users are solely responsible for legal issues arising from public sharing
Project developers assume no legal responsibility for user actions
This project does not provide services in mainland China. Legal risks and responsibilities from usage in that region are the user's personal actions, unrelated to this project

📄 License

This project is licensed under CC BY-NC-SA 4.0.

This means:

✅ You are free to share, copy, and modify this project
✅ You must give appropriate credit, provide a link to the license
❌ You may not use this project for commercial purposes
⚠️ If you remix, transform, or build upon the material, you must distribute your contributions under the same license

Based on MoonTV with extensive customization.

🙏 Acknowledgments

Original Projects

MoonTV — Original project
Selene — Official mobile app
LibreTV — Inspiration source

Core Dependencies

Next.js — React framework
ArtPlayer — Powerful web video player
HLS.js — HLS streaming support
react-window — Virtual scrolling component
Tailwind CSS — CSS framework

Data Sources & Services

Douban — Movie & TV info data
TMDB — Movie database
Bangumi — Anime information
Zwei — Douban CORS proxy
CMLiussss — Douban CDN service

Special Thanks

All sites providing free video APIs
Open source community contributors
Users who provide feedback and suggestions

📊 Star History

If this project helps you, please give it a ⭐ Star!

Made with ❤️ by LunaTV Enhanced Edition Team

FilesExpand file tree

README_EN.md

Latest commit

History

README_EN.md

File metadata and controls

LunaTV Enhanced Edition

📢 Project Overview

💡 Core Enhancement Highlights

🎥 Content Ecosystem Expansion

🤖 AI Recommendation System

💬 Danmaku Ecosystem

📊 User Management Enhancement

🎮 Player Feature Enhancement

📱 Interface Experience Optimization

🔐 Security & Storage

⚠️ Important Notices

📦 Project Status

🚫 Distribution Restrictions

📜 Open Source License

✨ Complete Feature List

🎬 Content Aggregation

🤖 Smart Recommendations

💬 Danmaku System

📊 User Management

🎮 Player Enhancement

🎨 Interface Experience

🔐 Security & Storage

🛠️ Technical Optimization

🗺 Table of Contents

🔧 Tech Stack

🚀 Deployment

⚡ One-Click Deploy to Zeabur (Easiest)

🐳 Docker Self-Hosted Deployment

📦 Recommended: Kvrocks Storage

🔴 Redis Storage (Risk of Data Loss)

☁️ Upstash Cloud Storage (Docker)

☁️ Zeabur Deployment (Recommended)

5. Set Up Access Domain (Required)

🔄 Updating Docker Images

✨ Zeabur Deployment Advantages

⚠️ Zeabur Considerations

🌐 Vercel Deployment (Serverless)

Vercel + Upstash Solution

Prerequisites

Deployment Steps

⚠️ Vercel Deployment Limitations

💡 Vercel Deployment Advantages

⚙️ Configuration File

📝 Configuration Format

📖 Field Description

🎯 Recommended Custom Categories

🌐 Environment Variables

Required Variables

Storage Configuration

Optional Configuration

Douban Proxy Options

🎛️ Feature Configuration

Admin Panel Access

Admin Panel Feature Modules

📁 Configuration File (Owner Only)

⚙️ Site Configuration

👥 User Configuration

🎬 Video Source Configuration

📺 Live Source Configuration

🏷️ Category Configuration

🔍 Cloud Drive Search Configuration

🤖 AI Recommendation Configuration

🎥 YouTube Configuration

🔐 TVBox Security Configuration

🗄️ Cache Management (Owner Only)

📦 Data Migration (Owner Only)

🔄 Auto Update

Using Watchtower

UI Tools Auto Update

📱 Mobile App Usage

Selene - Official Mobile Client

Supported Platforms

Key Features

Usage Instructions