# nodecast-tv: Self-Hosted IPTV Playback and Transcoding

> nodecast-tv gives authorized Xtream Codes and M3U users a browser interface for live channels, EPG data, movies, and series, with authentication and optional GPU transcoding. It fits shared media servers, but playback remains dependent on provider access and browser codec support.

**technomancer702/nodecast-tv** — A self-hosted web application that lets you stream Live TV, Movies, and Series from your Xtream Codes or M3U provider directly in your browser. It's built with performance in mind and handles large libraries smoothly.

- Repository: https://github.com/technomancer702/nodecast-tv
- Stars: 1,560 · Forks: 252
- Language: JavaScript
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/technomancer702-nodecast-tv

## Why Operators Choose nodecast-tv

nodecast-tv addresses the problem of presenting a large IPTV catalog through a maintained web interface rather than opening raw M3U playlists and individual stream URLs. It is intended for people who already have authorized access to an Xtream Codes or M3U provider and want live television, an electronic program guide, movies, and series available through one browser application. A household media server, family viewing group, or small organization with a shared catalog are plausible deployment contexts.

The project does not supply television subscriptions or channel packages. Users must add their own provider details before the library has content to display. This boundary is important when assessing adoption. nodecast-tv manages catalog presentation, access, favorites, and playback, while account validity, source availability, and provider-side delivery remain outside its control.

Its library-oriented features solve concrete navigation problems. The README describes category grouping and search for live channels, a 24-hour EPG timeline, posters and metadata for movies, and seasonal episode lists for series. Favorites span channels, movies, and series rather than being isolated by content type. Playback preferences include volume memory and auto-play.

Large libraries receive particular attention. The README says the interface uses virtual scrolling and batch rendering for libraries with more than 7,000 channels. That avoids requiring the browser to render every channel at once. However, the README publishes no latency measurements, hardware requirements, or comparative rendering figures for that path.

nodecast-tv therefore solves catalog and playback management around existing IPTV access. It does not remove the need for authorized credentials, browser-compatible media, server maintenance, or persistent-data planning.

## How nodecast-tv Processes Provider Data

The documented source flow begins in Settings -> Content Sources. An operator enters either Xtream Codes details or an M3U URL, selects Refresh Sources, and then browses the imported Live TV, Movies, and Series sections. The repository's server dependencies support playlist XML and structured provider information. `xml2js` and `sax` are included for XML processing, while Express and the `server/` directory provide the backend.

Persistent data is managed through `better-sqlite3`. The README does not include the database schema, refresh interval, cache policy, or a complete inventory of records stored under the Docker data mount. Based on `docker-compose.yml`, `/app/data` is mapped from `./data`. Operators can use that directory when planning backups, but should inspect it before assuming it contains only one database file.

The server entry point is `server/index.js`. The npm scripts expose `npm run dev`, which invokes `node --watch server/index.js`, and `npm start`, which invokes the same entry point without watch mode. Authentication dependencies include Passport local, JWT, and OpenID Connect strategies. Express sessions and bcryptjs are also declared, matching the documented local login and role-based access features.

Media delivery includes direct playback and processing paths. The README names automatic codec detection, remux and transcode decisions, configurable 5.1-to-stereo downmix presets, and automatic passthrough where compatible. GPU encoders include NVIDIA NVENC, AMD AMF, Intel QuickSync, and VAAPI. The exact rules for choosing direct playback, remuxing, software transcoding, or hardware transcoding are not documented in full.

Catalog ingestion and media delivery are distinct layers. A channel can appear after a successful refresh but still fail if its source URL is unavailable or the browser cannot decode it. Troubleshooting therefore requires separating source refresh errors from playback and transcoding errors.

## Installing nodecast-tv and Connecting a Provider

The README lists Node.js and npm as local prerequisites, but its Node.js statement conflicts with `package.json`. The README says Node.js v14 or higher, while the package manifest requires Node.js 18 or newer. The manifest provides the stricter project constraint, so local deployment should use Node.js 18 or newer.

Clone the repository and enter its directory:

```bash
git clone https://github.com/technomancer702/nodecast-tv.git
cd nodecast-tv
```

Install the declared dependencies:

```bash
npm install
```

Start the development server:

```bash
npm run dev
```

This invokes `node --watch server/index.js`. After the server starts, open `http://localhost:3000`, go to Settings -> Content Sources, enter authorized Xtream Codes or M3U provider information, and select Refresh Sources. Imported entries should then appear under Live TV, Movies, and Series.

For container deployment, the README publishes images at `ghcr.io/technomancer702/nodecast-tv`. Its compose example maps port 3000, persists `./data`, and sets production values:

```yaml
services:
  nodecast-tv:
    image: ghcr.io/technomancer702/nodecast-tv:latest
    build: https://github.com/technomancer702/nodecast-tv.git#main
    container_name: nodecast-tv
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - PORT=3000
```

The repository's `docker-compose.yml` declares both `image` and `build`. The README does not explain how a specific Compose implementation resolves those keys in this file. Operators who require reproducibility should check the selected image tag or build revision instead of assuming `latest` always represents the desired version.

Start the service with:

```bash
docker-compose up -d
```

The application is then available at `http://localhost:3000`. The Dockerfile installs Node.js, FFmpeg, build tools, and architecture-specific acceleration packages. It exposes port 3000, defines a health check, starts `node server/index.js`, and creates `/app/data` plus `/app/transcode-cache` during image construction.

## OIDC Configuration and Default Viewer Access

nodecast-tv supports OIDC single sign-on through providers such as Authentik and Keycloak. Its documented variables are placed in `.env` or supplied through the container environment. The example credentials must be replaced with values from an actual provider registration.

```env
OIDC_ISSUER_URL=https://your-idp.com/application/o/nodecast/
OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_client_secret
OIDC_CALLBACK_URL=http://localhost:3000/api/auth/oidc/callback
```

The HTTP callback is shown for local use. A remote deployment needs an address consistent with the provider's registered redirect URI and the application's HTTPS requirements. The README states that HTTPS issuers require HTTPS endpoints, while HTTP remains available for local development.

By default, the app loads `/.well-known/openid-configuration` from the issuer. Discovery has a five-second timeout and a 128 KiB response limit. The returned issuer must match `OIDC_ISSUER_URL` exactly, including a trailing slash when one is present. Operators can override discovered endpoints through `OIDC_AUTH_URL`, `OIDC_TOKEN_URL`, and `OIDC_USERINFO_URL`. Supplying all three skips discovery.

An OIDC outage or malformed discovery response does not remove the local login path. The README says SSO reports an unavailable message while local login remains usable. This provides a recovery path, although an operator needs a local account when OIDC was the only method initially configured.

New OIDC users receive the Viewer role automatically. An administrator must manually promote a user to Admin when higher access is required. This prevents new SSO accounts from receiving administrative privileges immediately, but it adds an onboarding step.

## GPU Access for Hardware Transcoding

Hardware transcoding depends on container device access and encoder availability. The README documents separate configurations for Intel QuickSync, AMD VAAPI and AMF, and NVIDIA NVENC.

For Intel and AMD acceleration on Linux, map the DRI device directory:

```yaml
devices:
  - /dev/dri:/dev/dri
```

A container process that does not run as root may need host group permissions:

```yaml
group_add:
  - "video"
  - "render"
```

The README directs operators to find host group information with `getent group video` and `getent group render`. Numeric group IDs should not be copied without checking the host. A device can be mapped and still be inaccessible when permissions are wrong.

NVIDIA deployments require NVIDIA Container Toolkit. The documented reservation requests one GPU and several relevant capabilities:

```yaml
deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 1
          capabilities: [gpu, utility, video, compute]
```

After restarting the container, open Settings -> Transcoding. The status should identify available hardware. On Linux, the QuickSync check verifies an accessible Intel render device and performs a short H.264 encode through the configured FFmpeg. If that check fails, QuickSync is not automatically recommended.

The Dockerfile adds Mesa VA drivers, Intel media drivers, and related libraries for `amd64`. It includes `pciutils` for hosts where vendor details are not exposed through sysfs. Another CPU architecture does not receive the same conditional package set, so encoder support should not be assumed to be identical.

Hardware conversion still consumes GPU and FFmpeg resources. Direct browser playback remains preferable when the source is supported and passthrough rules permit it.

## nodecast-tv Playback and Upgrade Boundaries

The main limitation is provider dependence. nodecast-tv does not bundle channels or subscriptions, and the README does not claim that it can repair an invalid provider account. An expired account, unreachable M3U URL, failed Xtream Codes request, or unavailable stream can prevent browsing or playback.

Browser decoding is another boundary. nodecast-tv runs in a web browser, so direct playback depends on the media formats the browser can decode. The README begins its codec discussion with that dependency but does not publish a complete compatibility table. A stream that appears correctly in the catalog may still require remuxing or transcoding.

Transcoding is a conditional fallback. It depends on FFmpeg, encoder support, container permissions, and enough compute capacity. The documented hardware paths also vary by GPU vendor and CPU architecture. A supported GPU is insufficient when `/dev/dri` permissions or NVIDIA Container Toolkit configuration are incomplete.

OIDC has separate failure points. Issuer mismatch, an invalid callback registration, inaccessible endpoints, or discovery timeout can break SSO. Local login remains available according to the README, but administrators need to retain access to that account.

Upgrade handling is thinly documented. The README does not define a rollback command or database migration procedure. Because the compose example persists `./data`, changing container images can affect stored application state. Operators should inspect that directory and the selected image tag before replacing a running deployment.

## nodecast-tv Against Direct Playlist Playback

A direct playlist workflow supplies an M3U URL or stream URL to a browser or dedicated player. It has fewer server components, but it does not add nodecast-tv's unified catalog, EPG grid, server-side roles, cross-content favorites, or provider management interface.

nodecast-tv requires more infrastructure: a Node.js or Docker deployment, persistent data, authentication configuration, source refresh handling, and sometimes a GPU-aware FFmpeg environment. In return, it centralizes live channels, movies, and series under one browser interface that can be deployed for multiple authorized viewers.

Direct playback is the simpler option when a user needs one known stream and already has a compatible player. It removes nodecast-tv's provider configuration, database, container image, and transcoding settings from the path. It also lacks the documented EPG, seasonal episode, favorites, and large-library rendering features.

nodecast-tv is the better choice when catalog navigation is the main requirement. Virtual scrolling and batch rendering target large live-channel lists, while EPG, movies, and series provide a consistent interface across content types. The tradeoff is more complex failure diagnosis involving provider refresh, stream delivery, browser decoding, authentication, and transcoding.

A narrow installation serving one known stream may not justify this application layer. Shared viewing across several content types gives nodecast-tv a clearer purpose.

## nodecast-tv Images, Versions, and GPL-3.0

The repository is not archived. Its last push was on 2026-10-14, and v2.2.1 was released on 2026-10-13. Versions v2.1.1 and v2.1.0 were released on 2026-01-19. These dates indicate recent development activity, but provider behavior, GPU configuration, and stored data still determine whether an upgrade is safe for a particular deployment.

The README states that GitHub releases publish images under `ghcr.io/technomancer702/nodecast-tv`. Stable releases publish a full version tag, a minor alias, and `latest`. Prereleases publish the full version tag without changing `latest` or the minor alias. Branch pushes, standalone tag pushes, and draft releases do not publish images.

A version mismatch deserves attention. The README uses v2.2.1 in its tag example, while `package.json` reports 2.2.7. The release list does not include a 2.2.7 release. This does not establish how package and container versions are coordinated, but it makes direct verification of the selected tag and source revision important.

The package manifest identifies the software as GPL-3.0-only, and the repository contains a `LICENSE` file. Anyone modifying or redistributing nodecast-tv should review the applicable license text and source-offer obligations. This identifies a licensing boundary rather than providing legal advice about a particular deployment.

Before replacing a container, inspect the selected image tag and the contents of `./data`. The README does not define a rollback or migration procedure for that persistent state.

## Conclusion

nodecast-tv fits operators who already have authorized Xtream Codes or M3U access and want a shared browser interface with EPG, VOD, authentication, and server-side stream processing. It does not suit users without a provider account, a compatible browser, or a prepared container host. Verify one provider stream first, then inspect browser codec support and Settings -> Transcoding before depending on converted playback. The repository is not archived, and its last push was on 2026-10-14.

## FAQ

### How do I install nodecast-tv with Docker Compose?

Create the repository's Compose configuration, which maps port 3000 and persists `./data`, then run `docker-compose up -d`. The README says the application will be available at `http://localhost:3000`.

### Which Node.js version does nodecast-tv require?

`package.json` requires Node.js 18 or newer. The README says Node.js v14 or higher, so its prerequisite conflicts with the package manifest.

### Does nodecast-tv support OIDC single sign-on?

Yes. It supports providers such as Authentik and Keycloak through `OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, and `OIDC_CALLBACK_URL`. New SSO users receive the Viewer role and require manual promotion for Admin access.

### How do I enable GPU transcoding for nodecast-tv?

Map `/dev/dri` for Intel or AMD acceleration, or configure NVIDIA GPU access with NVIDIA Container Toolkit. After restarting the container, check Settings -> Transcoding for detected hardware.

### Will nodecast-tv play any IPTV stream directly in the browser?

Not necessarily. Direct playback depends on browser codec support. FFmpeg processing and hardware acceleration cover selected cases, but the README does not publish a complete stream compatibility matrix.

## Sources

- [Issues](https://github.com/technomancer702/nodecast-tv/issues)
- [License: GPL-3.0](https://github.com/technomancer702/nodecast-tv/blob/main/LICENSE)
- [README](https://github.com/technomancer702/nodecast-tv/blob/main/README.md)
- [Releases](https://github.com/technomancer702/nodecast-tv/releases)
- [technomancer702/nodecast-tv on GitHub](https://github.com/technomancer702/nodecast-tv)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/technomancer702-nodecast-tv