LunaTV: Aggregate video search and streaming with Next.js 14
A Docker video aggregator for personal site owners that searches multiple sources and syncs progress, but requires self-provided sources.
GitHub MoonTechLab/LunaTV Updated 2026-09-08 Branch main Stars 9.7K Forks 9.0K
Next.js 14 Video aggregation HLS.js Docker

🧭 Decision Guide

Try it if you

  • You already have Docker and want a video aggregation frontend based on Next.js 14, Tailwind CSS 3, and TypeScript.
    The README technical stack lists Next.js 14, Tailwind CSS 3, and TypeScript; the deployment section says only Docker or Docker-based platforms are supported.
  • You need Kvrocks, Redis, or Upstash to store favorites and watch history and synchronize progress.
    The README features list multi-device synchronization through Kvrocks/Redis/Upstash; environment variables support redis, kvrocks, and upstash.
  • You need PWA and responsive navigation and plan to use Selene with a version above v100.0.0.
    The README features list PWA and responsive layout; the client section states that versions above v100.0.0 can work with Selene.

Skip it if you

  • You need a ready-to-use video catalog and will not collect playback sources yourself.
    The README warning says the deployed project is an empty shell with no built-in playback or live-stream sources and that users must collect them.
  • You plan to publicly share the instance, provide a public service, or use it commercially.
    The README security section requires personal use and no public sharing; the project description states that CC BY-NC-SA prohibits commercialization.
  • Your deployment platform does not support Docker or a Docker-based platform.
    The README deployment section explicitly says the project only supports Docker or other Docker-based platforms.

Requirements

  • Docker or a Docker-based platform is required; the README says: “本项目仅支持 Docker 或其他基于 Docker 的平台部署。”
  • USERNAME and PASSWORD must be set; the environment-variable table marks both as required with no defaults.
  • NEXT_PUBLIC_STORAGE_TYPE must be set to redis, kvrocks, or upstash.
  • api_site must be filled in the configuration; the README states that no playback sources are included and the site owner must provide the configuration.
  • When using Kvrocks, KVROCKS_URL is required; the example uses redis://moontv-kvrocks:6666.

First step (verbatim from README)

image: ghcr.io/moontechlab/lunatv:latest

Watch out

  • After Zeabur deployment, a Domain must still be configured or the site cannot be accessed in a browser.
    The important notice in README “zeabur 一键部署”.
  • When configuring api_site, api must be the vod JSON API root URL provided by the source site.
    The api_site field description in README “配置文件”.
  • A public instance creates the legal risks listed in the README; the project requires setting PASSWORD and disabling public registration.
    README “安全与隐私提醒” and “部署要求”.
  • NEXT_PUBLIC_SEARCH_MAX_PAGE ranges from 1 to 50 and defaults to 5.
    README “环境变量” table.

Alternatives

  • Selene:Use it when you need a more mobile-friendly experience with full LunaTV data synchronization; the README specifies compatibility above v100.0.0.
    README “客户端” section
  • OrionTV:Use it when the target device is Android TV; the README says LunaTV can act as an OrionTV backend and synchronize watch history.
    README “AndroidTV 使用” section

Not stated in the README

  • The README does not specify required CPU, memory, disk, or concurrency capacity.
  • The README does not specify the availability, stability, or content coverage of self-collected sources.
  • The README omits details of Redis data-loss risk, Upstash setup steps, and operational limits.
  • The README does not explain the specific changes from v100.0.0 to v100.1.3.
  • The README provides no information about HLS.js and ArtPlayer format compatibility, browser coverage, or DRM support.

💡 Deep Analysis

6
No I want to deploy MoonTV as a public commercial video-streaming service with my own operations and billing. Is it suitable under this commercial constraint?
For: A product team planning to operate the aggregation site as a commercial streaming service or public content platform

No, because the project explicitly prohibits commercial use and places public-service and copyright responsibility on the deployer.

  • The project description states that it uses CC BY-NC-SA, prohibits all commercialization, and requires derivative projects to retain the project address and use the same license.
  • The Security and Privacy section says it is for personal use, asks users not to publicly share or distribute instances, and strongly recommends disabling public registration.
  • The project is a video-aggregation frontend, not a platform for content storage, transcoding, rights management, commercial billing, or enterprise auditing.
  • The README also says deployments contain no built-in playback sources and depend on third-party APIs. Commercial operation, public access, and content-compliance responsibilities therefore conflict with your requirements.
  • Project description: CC BY-NC-SA and all commercialization is prohibited
  • Project description: Derivative projects must retain the project address and use the same license
  • Security and Privacy: for personal use; do not use deployments commercially or as public services
  • Security and Privacy: strongly recommends disabling public registration
  • Project insight: unsuitable for content upload, media transcoding, granular permissions, commercial billing, or enterprise auditing
Not stated in the README:The README does not state whether a separate commercial license or exception process exists.;It provides no audit, billing, content-moderation, or high-availability design for public services.
Yes I need favorites and watch history synchronized across the web, Selene, and OrionTV on Android TV. Can MoonTV cover these three clients?
For: A personal user who uses the web, Selene mobile client, and OrionTV on Android TV and requires synchronized favorites and watch progress

Yes, because the README explicitly places the web client, Selene, and OrionTV in one synchronized usage model.

  • The Features section states that favorites, continue-watching, and multi-device progress synchronization are supported through Kvrocks, Redis, or Upstash.
  • The Client section says versions 100.0.0 and above can work with Selene and that data is fully synchronized. The project data lists the latest release as v100.1.3, which meets that threshold.
  • The Android TV section says MoonTV can serve as an OrionTV backend and that watch history is synchronized with the web client.
  • PWA and responsive-layout support also cover desktop, mobile, and home-screen installation. However, the README does not promise identical behavior across all Android TV models, media formats, or playback-recovery cases.
  • Features: Favorites and continue-watching with multi-device progress synchronization
  • Client: v100.0.0 and above can work with Selene, with fully synchronized data
  • Android TV: MoonTV can work with OrionTV
  • Android TV: Watch history is synchronized with the web client
  • Project data: latest_release = v100.1.3
Not stated in the README:The README does not provide a client-version compatibility matrix for Selene and OrionTV.;It does not define the limits of remote navigation, resolution support, or TV-model compatibility.
Yes I already have a personal server, use Docker Compose, and want Kvrocks to store favorites, watch history, and cross-device progress. Is MoonTV suitable for me?
For: A self-hosting user running Docker Compose on a personal server who wants Kvrocks for favorites and watch history

Yes, because MoonTV officially targets Docker deployment and recommends Kvrocks for persistent storage.

  • The Technology Stack section lists Docker as the deployment method, while the Deployment section says it “only supports Docker or Docker-based platforms.”
  • The Kvrocks example starts both ghcr.io/moontechlab/lunatv:latest and apache/kvrocks, with /var/lib/kvrocks mounted to persistent storage.
  • The Features section states that Kvrocks, Redis, and Upstash support favorites, continue-watching, and multi-device synchronization.
  • However, the deployed application is an empty shell until Apple CMS V10 source configuration is added in the admin panel; a running container does not provide playable content by itself.
  • Technology Stack: Deployment | Docker
  • Deployment: “本项目仅支持 Docker 或其他基于 Docker 的平台”
  • Deployment: Kvrocks Storage (Recommended)
  • Features: Favorites + Continue Watching, supporting Kvrocks/Redis/Upstash
  • Notice: “部署后项目为空壳项目,无内置播放源和直播源”
Not stated in the README:The README does not specify minimum CPU, memory, or disk requirements for a personal server.;It does not provide a complete Kvrocks backup, restore, or upgrade-migration procedure.
Yes I plan to deploy MoonTV on a Docker platform and use only Upstash Redis for favorites and watch history, without maintaining local Redis or Kvrocks. Is this feasible?
For: A cloud deployer who only has Upstash Redis, no local database container, and wants to retain viewing state

Yes, because the README provides a standalone Upstash deployment path and does not require a local Redis or Kvrocks container for that option.

  • The Upstash Storage section instructs users to create a Redis instance and copy its HTTPS ENDPOINT and TOKEN.
  • The official example connects cloud storage through NEXT_PUBLIC_STORAGE_TYPE=upstash, UPSTASH_URL, and UPSTASH_TOKEN.
  • The Features section confirms that Upstash supports favorites, continue-watching, and multi-device synchronization.
  • If you use ordinary Redis instead, the README warns about data-loss risk and requires persistence. Therefore, an Upstash-only design avoids local Redis volume management, while still depending on Upstash availability and correct credentials.
  • Deployment: Upstash Storage
  • Deployment: `NEXT_PUBLIC_STORAGE_TYPE=upstash`, `UPSTASH_URL`, and `UPSTASH_TOKEN`
  • Features: Kvrocks/Redis/Upstash storage with synchronized progress
  • Deployment: Redis storage has some data-loss risk
  • Redis example: persistence must be enabled or data is lost after upgrades/restarts
Not stated in the README:The README does not specify Upstash free-tier limits, latency, region selection, or request quotas.;It does not explain how favorites and watch history degrade when Upstash is unavailable.
It depends I maintain multiple Apple CMS V10 APIs and want one search to return results from all sources, but the source APIs change frequently. Can MoonTV meet this aggregation need?
For: A personal site operator maintaining multiple Apple CMS V10-compatible sources who wants unified search without building a video frontend

It depends, provided that your sources follow the standard Apple CMS V10 format and you are willing to maintain the configuration continuously.

  • The Features section promises that one search returns results from all configured sources, and api_site entries can be added, removed, or replaced.
  • The README explicitly says MoonTV supports the “standard Apple CMS V10 API format.” Each source can define an API URL, display name, and an optional detail URL when episode details cannot be obtained from the API.
  • The configuration also supports cache_time and custom_category for caching and custom movie or TV categories.
  • However, the project includes no playback sources. External APIs may fail, return incomplete fields, or expose unusable playback URLs; compatibility with non-standard APIs is not guaranteed.
  • Features: Multi-source aggregation search
  • Configuration: `api_site` can add, remove, or replace sources
  • Configuration: `cache_time`, `api_site`, and `custom_category`
  • README: MoonTV supports the standard Apple CMS V10 API format
  • Notice: No built-in playback or live-stream sources
Not stated in the README:The README does not define compatibility boundaries for vendor-specific differences in CMS V10 fields.;It does not describe automatic source health checks, failure detection, or source disabling.
Yes I use Next.js 14 App Router, TypeScript, and Tailwind CSS, and need HLS playback, responsive pages, and PWA support. Can MoonTV serve as a frontend foundation?
For: A frontend developer using Next.js 14, TypeScript, and Tailwind CSS who wants integrated playback and PWA behavior in a video aggregation site

Yes, because MoonTV’s existing stack and features directly match those frontend constraints.

  • The Technology Stack section specifies Next.js 14 App Router, Tailwind CSS 3, and TypeScript 4.
  • Playback uses ArtPlayer and HLS.js, and the README describes support for browser-based online playback.
  • The Features section includes PWA support, offline caching, installation to the desktop or home screen, and responsive navigation with a desktop sidebar and mobile bottom bar.
  • However, MoonTV is not a general media player or transcoding system. It depends on third-party playback URLs, and whether a specific stream works still depends on its format, CORS headers, and availability.
  • Technology Stack: Next.js 14 App Router, Tailwind CSS 3, TypeScript 4
  • Technology Stack: Player | ArtPlayer and HLS.js
  • Features: PWA with offline caching and installation
  • Features: Responsive desktop sidebar and mobile bottom navigation
  • Project insight: HLS.js and the player cannot guarantee every third-party format, CORS response, or abnormal stream
Not stated in the README:The README does not specify custom player-skin support, playback-error handling, or the supported scope of encrypted HLS streams.;It does not provide the exact PWA cache list or invalidation strategy.

✨ Highlights

  • Multi-source search returns all-source results at once
  • Playback integrates HLS.js and ArtPlayer
  • Kvrocks, Redis, and Upstash support progress sync
  • 9,716 stars, but deployment includes no built-in sources

🔧 Engineering

  • Next.js 14 App Router provides video search and detail pages
  • ArtPlayer and HLS.js handle online playback
  • Kvrocks, Redis, and Upstash store favorites and watch history
  • PWA supports offline caching and mobile installation

⚠️ Risks

  • Deployment is an empty shell and requires self-collected sources
  • CC BY-NC-SA prohibits commercialization and requires the same license
  • Docker is the only explicitly supported deployment method
  • PASSWORD is required and the README requires disabling public registration
  • Smart ad skipping is still marked experimental

👥 For who?

  • Personal video-aggregation site maintainers using Docker
  • Developers needing a Next.js 14 and TypeScript frontend
  • Users needing synchronization with Selene or OrionTV clients