Does LibreTV come with built-in video content or sources?

No. It ships with no sources by default; you must add your own Apple CMS-style collection APIs and M3U playlists, or subscribe to a remote source list, before you can search or watch anything.

What license is LibreTV released under?

AGPL-3.0, which requires that modified versions running as a network service also make their source code available.

Can I self-host LibreTV without Docker?

Yes. You can run it with plain Node.js: `npm install`, then `PASSWORD=your-password npm run build` followed by `npm start`, which listens on port 8080.

Why does login fail even with the correct password?

In production the session cookie is marked `Secure`, so browsers drop it over plain HTTP on non-localhost addresses. Put the deployment behind HTTPS via a reverse proxy, or set `COOKIE_SECURE=false` only if you understand the tradeoff.

Does LibreTV support live TV/IPTV, not just on-demand video?

Yes. You can add M3U/M3U8 playlists as live sources, browse and search channels on the `/live` page, and view XMLTV EPG data when a channel's `tvg-id` and an EPG URL are configured.

How does LibreTV differ from projects like LunaTV or MoonCakeTV?

Those are separate, independently maintained forks/derivatives listed in the README with their own storage backends and tech choices; LibreTV itself is the Next.js-based original with its own source subscription format and live TV support.

LibreTV: Self-hosted video search and player

LibreTV is a self-hosted platform for searching and watching video content from third-party aggregation APIs and IPTV playlists. It's built with Next.js (App Router), TypeScript, and Tailwind CSS, with ArtPlayer and hls.js handling playback. It doesn't host or produce any video itself; it's a front end and proxy layer for sources you configure (Apple CMS-style collection APIs and M3U live streams). It's aimed at people who already know where to find video source APIs and want a clean, personal interface to search, watch, and track progress across them, rather than a service that ships content.

The project targets self-hosters comfortable running Docker containers or a Node.js server, and who want control over their own source list instead of relying on a public streaming site.

Key features

Aggregated search: queries multiple configured collection sites in parallel from the server and merges results.
Cross-source deduplication: identical titles from different sources are merged into one card so you can compare and pick a source.
HLS playback: ArtPlayer + hls.js with ad-segment filtering, auto-continue to the next episode, variable speed, keyboard shortcuts, and 3x speed on long-press for mobile.
Live TV / IPTV: parses M3U playlists, groups and searches channels on a /live page, supports HLS and HTTP-FLV streams, XMLTV EPG, and channel favorites.
Progress sync: watch history and resume position are stored locally in IndexedDB, down to the second.
Source speed test and switching: ranks same-title sources by speed and lets you switch sources mid-watch while keeping your episode position.
Source health checks and subscriptions: one-click health checks for VOD and live sources, automatic tiered disabling of repeatedly failing sources, and subscription to remote source lists (its own JSON format or a TVBOX config URL), importable and exportable.
Homepage recommendations: Douban, Bangumi, or a hot-list feed (via the 60s API), fetched server-side and cached.
PWA support: installable to desktop or home screen, with light/dark themes and no flash on load.

Ideal use cases

LibreTV fits someone who wants a single, searchable interface for video sources they already have or can find (CMS-style APIs, M3U playlists), deployed on their own server or VPS behind HTTPS. It also works well for self-hosters who want IPTV channel browsing with EPG support alongside on-demand video search, or who want to aggregate and dedupe results from several mirror sites.

It is not a content library or streaming service by itself: it ships with no built-in sources, so you need to supply working CMS API endpoints or M3U playlists for it to be useful. It's also not a good fit if you can't run Docker or Node, or if you can't put the deployment behind TLS, since production sessions rely on secure cookies that require HTTPS (localhost is exempt). If you need a native TV app, look at the listed derivative projects (OrionTV, Selene-TV, etc.) that pair with compatible backends.

Installation

The recommended path is Docker Compose. Set a password, then pull and run:

echo "PASSWORD=your-password" > .env
docker compose pull && docker compose up -d

Or build from source:

docker compose up -d --build

A minimal docker-compose.yml service definition:

services:
  libretv:
    image: ghcr.io/librespark/libretv:latest
    container_name: libretv
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - PASSWORD=change-me

Optional environment variables let you preset sources (DEFAULT_SOURCES, DEFAULT_LIVE_SOURCES, DEFAULT_SUBSCRIPTIONS), tune proxy timeouts and retries, set a signing key for multi-instance deployments (PROXY_SECRET), and allow internal IPTV sources (LIVE_ALLOW_PRIVATE). Images are published on both GHCR and Docker Hub for linux/amd64 and linux/arm64.

For manual deployment without Docker:

npm install
PASSWORD=your-password npm run build
PASSWORD=your-password npm start   # listens on port 8080

For local development:

npm install
PASSWORD=dev-password npm run dev   # http://localhost:8080
npm test
npm run typecheck

Production deployments must sit behind HTTPS (via a reverse proxy like Nginx, Caddy, or Cloudflare); session cookies carry the Secure flag, so plain HTTP access over a non-localhost address will silently fail to persist the login session.