Self-hosted service
mtvpls/MoonTVPlus avatar
mtvpls/MoonTVPlus

MoonTVPlus: a self-hosted streaming aggregator that ships with no sources

MoonTVPlus is an enhanced video aggregation player built on MoonTV v100, adding external player support, video super-resolution, a danmaku (on-screen comment) system, comment scraping and other features for a stronger viewing experience.

3,734 stars3,449 forksTypeScriptNOASSERTION

At a glance

What is it?
MoonTVPlus is a TypeScript and Next.js 14 fork of MoonTV v100 that adds external player handoff, WebGPU upscaling, danmaku and Douban comment scraping. It is a shell you have to fill yourself, and the README says so.
Who is it for?
Adopt MoonTVPlus if you already run your own media sources and want a Next.js front end that can hand playback to PotPlayer or IINA, plus danmaku and Douban comments on top. Do not adopt it if you expect a working catalogue after deployment: the README states the deployed project is an empty shell with no built-in playback or live sources, and you must collect those yourself.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 18 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mtvpls/MoonTVPlus3,734 ★ · +462
Star history
Repository2026-09-242026-11-15
mtvpls/MoonTVPlus3.3k3.7k

462 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What MoonTVPlus actually is and who it is for

MoonTVPlus is a fork of MoonTV v100, described in its README as an enhanced film and television aggregation player. It is a Next.js 14 application written in TypeScript, using Tailwind CSS 3, ArtPlayer and HLS.js for playback. The target user is someone who already has access to streaming source lists and wants a self-hosted front end over them, not someone looking for a finished service.

The README is blunt about this. It states that after deployment the project is an empty shell with no built-in playback sources and no live sources, and that you must collect them yourself. That single sentence decides most adoption questions. If you cannot supply source definitions, MoonTVPlus has nothing to show you.

The fork adds features the upstream project does not have: jumping to external players such as PotPlayer, VLC, MPV, MX Player, nPlayer and IINA; Anime4K upscaling through WebGPU at 1.5x, 2x, 3x or 4x; a danmaku system with search, matching, loading, persistent settings and blocking; Douban short-comment scraping with pagination; an experimental script system for custom sources; a watch room with chat and voice; M3U8 download with in-browser merging; server-side offline download with resume; and a private library that connects to OpenList, Emby or Xiaoya.

That is a long list, and the README marks several items as experimental. Treat the watch room and the source-script system as unfinished ground rather than as product features.

Architecture: App Router, a custom server and a swappable storage layer

The stack is conventional Next.js with one notable deviation. The dev and start scripts do not call next start. They run node server.js. That custom server is what carries Socket.IO for the watch room, and the Dockerfile copies it into the runtime image alongside start.js. This matters for deployment planning: any host that only runs the standard Next.js serverless output will not have the same runtime.

Storage is pluggable. The README names Kvrocks, Redis and Upstash for favourites and watch progress, and the deployment sections add Cloudflare D1 and Turso as options. The choice is expressed through the NEXT_PUBLIC_STORAGE_TYPE environment variable, with values such as upstash, d1 and turso appearing in the documented secret tables. Repository scripts confirm four initialisers: init:sqlite, init:postgres, init:turso and a db:reset that deletes .data/moontv.db along with its WAL files before re-initialising SQLite.

The Dockerfile is a three-stage build on node:24-alpine. Dependencies install with pnpm install --frozen-lockfile, the build runs pnpm run build with DOCKER_ENV=true, and production dependencies are extracted with pnpm deploy --filter=. --prod --legacy. The runtime stage adds su-exec, creates a nextjs user at UID 1001, and copies the standalone output, scripts, migrations, start.js and server.js. It sets PORT=3000, HOSTNAME=0.0.0.0, SQLITE_DB_PATH=/app/.data/moontv.db and OFFLINE_DOWNLOAD_DIR=/data.

Two entrypoints exist, Dockerfile and Dockerfile.lite, and the README does not explain the difference between them. That is a gap worth resolving by reading both files before you pick one.

Installing MoonTVPlus and playing something for the first time

The README offers Docker, Vercel, Netlify, Cloudflare Workers, EdgeOne Pages, Zeabur and Render as deployment targets. The Docker path is the one whose internals are visible in the repository. The runtime image sets PORT=3000, so the container listens there by default.

The README does not publish a ready-made docker run line, so the image has to be built from the Dockerfile at the repository root first. The runtime stage sets HOSTNAME=0.0.0.0, which is what makes port 3000 reachable from outside the container.

dockerfile
FROM node:24-alpine AS deps
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

That is the first stage of the repository's Dockerfile, reproduced from the file. Building it produces the image the runtime stage later consumes.

For local development the package scripts expect pnpm. The dev script regenerates a manifest and then starts the custom server.

bash
pnpm install
pnpm dev

Running pnpm dev executes pnpm gen:manifest first, which calls scripts/generate-manifest.js, then node server.js. You should see the Next.js app served on port 3000 with the watch-room socket server attached.

After the app is up, the first real task is not playback. It is adding a source. The README states the deployed project has none, and it points to SOURCE_SCRIPT.md for the experimental script system that defines search, detail and playback parsing. Until a source is defined, search returns nothing and the detail pages have nothing to render.

Where MoonTVPlus breaks, and when it is the wrong tool

The empty-shell constraint is the largest one, and it is structural rather than a bug. A fresh deployment has no catalogue. Every search result, every detail page and every stream depends on source definitions you supply or write. Compare that to a media server such as Jellyfin or Emby, which indexes files you own and works immediately after a library scan. MoonTVPlus is a player and a catalogue interface, not an indexer.

The custom server is the second constraint. Because the start script runs node server.js rather than the Next.js production server, features tied to that process, notably the Socket.IO watch room, depend on a host that runs a persistent Node process. The README's Cloudflare Workers and EdgeOne Pages paths go through OpenNext and edge build targets instead, with a separate build:cloudflare script. The README does not state which features are unavailable on those edge targets. Verify that before choosing an edge deployment for a watch-room use case.

Storage is a third area where the documentation is thin. The README lists Kvrocks, Redis, Upstash, D1 and Turso across different sections, and the repository ships initialisers for sqlite, postgres and turso. It does not provide a single table mapping each backend to the features it supports. Favourites and watch progress are the stated consumers, but the README does not say whether the watch room, danmaku or the private library also require the same store.

Finally, the README includes a notice asking people not to publish videos or articles about the project on Bilibili, Xiaohongshu, WeChat public accounts, Douyin, Toutiao and other mainland Chinese social platforms, and stating that it does not authorise technology weekly or monthly publications to index it. That is a distribution constraint, not a technical one, but it affects whether you can write about your deployment publicly.

MoonTVPlus against MoonTV and LibreTV

The closest comparison is the upstream project. MoonTVPlus is explicitly a second-development fork of MoonTV v100, and its README frames the additions as a list of deltas: external player handoff, WebGPU upscaling, danmaku, Douban comments, source scripts, custom ad-removal code, the watch room, M3U8 download, server-side offline download and the private library. Upstream MoonTV does not carry those, according to the fork's own description.

The practical difference is scope. Choosing upstream means a smaller surface and a codebase that tracks one author's direction. Choosing MoonTVPlus means accepting a fork that has drifted, with its own deployment workflows, its own environment variables such as SQLITE_DB_PATH and OFFLINE_DOWNLOAD_DIR, and its own build scripts for Cloudflare and EdgeOne. You inherit the fork's maintenance, not the upstream's.

LibreTV appears in the related searches around this project and is a different kind of tool: a lighter, browser-oriented aggregator rather than a Next.js application with a custom Node server, a database layer and a private library integration. If your requirement is a single-page player you can host anywhere static, the heavier MoonTVPlus architecture is a cost you are paying for features you may not use. If you need danmaku, external player handoff or a synced watch room, that cost is the point.

The repository has no published releases, so there is no published changelog to compare versions against. Version tracking happens through VERSION.txt and the CHANGELOG file at the repository root.

Maintenance, upgrades and the licence question

The last push to the default branch was on 2026-09-09, and the repository is not archived. That is recent enough that the project is being touched, but the retrieved data shows no releases, so there is no tagged version to pin against. Upgrades therefore mean tracking main or a named branch and rebuilding.

That has a concrete cost. The Dockerfile installs with pnpm install --frozen-lockfile, so a rebuild only reproduces the lockfile's dependency set. When you pull new source, the lockfile may have moved, and the three-stage build reruns from the dependency layer down. The migrations directory is copied into the runtime image, which suggests schema changes are applied at container start rather than baked in at build time. The README does not document rollback, so plan your own: keep the SQLite file or your external store snapshotted before pulling.

The Cloudflare and EdgeOne paths add a second upgrade surface. Both rely on GitHub Actions workflows, cloudflare-deploy.yml and edgeone-deploy.yml, plus a set of repository secrets. Changing storage type or provider means editing secrets, not just environment variables, and the README documents the required names for each platform.

On licensing, the situation is inconsistent and you should resolve it before relying on it. The repository metadata reports the licence as NOASSERTION, while the README badge displays MIT. The LICENSE file is present at the repository root. Read that file rather than the badge or the metadata, because the two disagree. This is not legal advice; it is a note that the project's own signals conflict.

Editorial conclusion

Adopt MoonTVPlus if you already run your own media sources and want a Next.js front end that can hand playback to PotPlayer or IINA, plus danmaku and Douban comments on top. Do not adopt it if you expect a working catalogue after deployment: the README states the deployed project is an empty shell with no built-in playback or live sources, and you must collect those yourself. Before committing, verify three things: which storage backend you will set in NEXT_PUBLIC_STORAGE_TYPE (sqlite, upstash, d1 or turso), whether your chosen platform can run server.js with Socket.IO for the watch room, and what the LICENSE file actually grants, since the repository reports NOASSERTION while the README badge says MIT.

Frequently asked questions

Does MoonTVPlus come with video sources built in?

No. The README states that after deployment the project is an empty shell with no built-in playback sources and no live sources, and that you must collect them yourself. Source definitions are supplied through the experimental script system described in SOURCE_SCRIPT.md.

What storage backends can MoonTVPlus use for favourites and watch progress?

The README names Kvrocks, Redis and Upstash, and its deployment sections add Cloudflare D1 and Turso. The backend is selected with the NEXT_PUBLIC_STORAGE_TYPE environment variable, and the repository ships initialisers for sqlite, postgres and turso.

Which external players can MoonTVPlus hand a stream off to?

The README lists PotPlayer, VLC, MPV, MX Player, nPlayer and IINA as supported external players. It describes this as one of the features added on top of MoonTV v100.

Is the MoonTVPlus watch room available on every deployment target?

The README does not say. The watch room depends on Socket.IO, which lives in the custom server.js that the start script runs, while the Cloudflare Workers and EdgeOne Pages paths use separate build targets. Verify feature parity on your chosen host before relying on it.

Official sources

  1. Issues
  2. mtvpls/MoonTVPlus on GitHub
  3. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mtvpls-moontvplus.svg)](https://hysenlabs.com/projects/mtvpls-moontvplus)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mtvpls-moontvplus.svg)](https://hysenlabs.com/projects/mtvpls-moontvplus)

Was this useful?