Comprehensive Overview of NodeCast-TV: A Modern Web-Based IPTV Player

Introduction

NodeCast-TV is a cutting-edge, web-based Internet Protocol Television (IPTV) player designed to deliver an optimized viewing experience with support for live television, on-demand content (VOD), and interactive TV guides. Built with performance in mind, NodeCast-TV leverages modern web technologies while offering advanced features such as hardware transcoding, single sign-on (SSO) integration, and seamless synchronization across devices. This detailed description explores its architecture, key functionalities, deployment options, troubleshooting tips, and technical specifications.

---

Core Features of NodeCast-TV

1. Live TV Experience

NodeCast-TV provides a fast and responsive live television experience with the following capabilities:

• Fast Channel Zapping: Users can navigate through channels quickly without lag.
• Category Grouping: Channels are organized into intuitive categories for easy access.
• Search Functionality: Users can search for specific channels or shows directly within the interface.

The live TV dashboard (as seen in the attached screenshot) features a clean, modern UI with a grid layout that dynamically adjusts to screen size. The player supports adaptive bitrate streaming, ensuring smooth playback even on unstable networks.

2. Interactive TV Guide (EPG)

One of the standout features of NodeCast-TV is its interactive Electronic Program Guide (EPG). This feature allows users to:

• View a 24-hour timeline with scheduled programs.
• Search for specific shows or channels within the guide.
• Dynamically resize the EPG layout for better usability on different screen sizes.

The EPG interface includes rich metadata such as show posters, ratings, and brief descriptions. Users can mark their favorite shows to create personalized watchlists.

3. On-Demand Content (VOD) Support

NodeCast-TV supports a dedicated section for movies and TV series with the following features:

• Rich Metadata: Each title includes posters, release dates, genres, and synopses.
• Seasonal Episode Lists: Users can browse episodes by season or directly jump to specific episodes.
• Favorites System: A unified favorites system allows users to save channels, movies, and series across all platforms.

The VOD section (as depicted in the screenshot) is organized into intuitive categories, making it easy for users to discover new content. The player also supports smart recommendations based on viewing history.

4. Authentication and User Roles

NodeCast-TV implements a robust authentication system with the following features:

• User Login: Users can log in via traditional credentials or integrate Single Sign-On (SSO) using OpenID Connect (OIDC).
• Admin vs. Viewer Roles:
• Admins have full control over content sources, settings, and user permissions.
• Viewers can only access their personalized content without administrative privileges.

The authentication system is detailed in the repository’s pull request #23, ensuring secure management of user accounts.

5. Single Sign-On (SSO) with OIDC

NodeCast-TV supports SSO via OpenID Connect (OIDC) providers such as Authentik and Keycloak. Users can log in once using their preferred identity provider, and NodeCast-TV automatically syncs their credentials across devices.

To enable SSO:

1. Configure the necessary environment variables in a .env file or Docker environment.
2. Set up an OIDC issuer URL, client ID, and callback URL.
3. Users will be redirected to the OIDC provider for authentication upon first login.

6. Performance Optimization

NodeCast-TV is designed with performance in mind, ensuring smooth playback even on large playlists:

• Virtual Scrolling: The interface efficiently handles thousands of channels without excessive memory usage.
• Batch Rendering: Multiple streams are processed simultaneously to reduce latency.
• Hardware Acceleration: Supports GPU-accelerated transcoding via NVIDIA NVENC, AMD AMF, Intel QuickSync, and VAAPI.

7. Management Features

NodeCast-TV provides administrators with tools to manage content sources and playback preferences:

• Xtream Codes & M3U Playlists: Supports both Xtream Codes (a common IPTV authentication method) and M3U playlists for easy integration.
• Hidden Content Categories: Administrators can hide specific channels or categories from users.
• Playback Preferences:
• Volume memory settings to retain audio volume across sessions.
• Auto-play options to start playback automatically when a user selects a title.

8. Hardware Transcoding

NodeCast-TV leverages hardware transcoding for optimal performance:

• GPU-Accelerated Encoding: Supports NVIDIA NVENC, AMD AMF, Intel QuickSync, and VAAPI for real-time encoding.
• Smart Audio Processing: Configurable audio downmixing presets (ITU, Night Mode, Cinematic) to enhance sound quality.

9. Stream Processing

The application includes advanced stream processing capabilities:

• Auto-Detection of Codecs: Automatically detects and transcodes incompatible media formats for browser compatibility.
• Smart Remux/Transcode Decisions: Minimizes unnecessary re-encoding by only transcoding when necessary.

---

Deployment Options

Prerequisites

Before deploying NodeCast-TV, users must meet the following requirements:

• Node.js (v14 or higher)
• npm (Node Package Manager)

Installation via GitHub Repository

To install NodeCast-TV locally:

1. Clone the repository using Git:

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

2. Install dependencies with npm:

   npm install

3. Start the development server:

   npm run dev

4. Open the application in a browser at http://localhost:3000.

Docker Deployment

NodeCast-TV can be easily containerized using Docker for seamless deployment across different environments.

Step 1: Create a docker-compose.yml File

Copy the provided template or create your own:

services:
  nodecast-tv:
    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

Step 2: Run the Container

Execute the following command to deploy NodeCast-TV in Docker:

docker-compose up -d

The application will be accessible at http://localhost:3000.

---

Hardware Acceleration Setup

To enable hardware transcoding, users must configure their Docker setup based on their GPU type:

For Intel (QSV) & AMD (VAAPI)

Update the docker-compose.yml file to include DRI device mapping and group permissions:

services:
  nodecast-tv:
    build: https://github.com/technomancer702/nodecast-tv.git#main
    container_name: nodecast-tv
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    devices:
      - /dev/dri:/dev/dri  # Required for VAAPI/QuickSync/AMF
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - PORT=3000

For NVIDIA (NVENC)

Ensure the NVIDIA Container Toolkit is installed on your host machine. Update docker-compose.yml to include GPU resources:

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

Verification

After restarting the container, navigate to Settings → Transcoding and verify that your GPU is detected (e.g., "NVIDIA GPU Detected" or "VAAPI Available").

---

Single Sign-On (SSO) Setup

To enable SSO with an OIDC provider (such as Authentik or Keycloak), configure the .env file:

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

New users signing in via SSO will be assigned the Viewer role by default. Administrators must manually promote them to Admin if needed.

---

Usage Guide

Adding IPTV Sources

1. Go to Settings → Content Sources.
2. Add your IPTV provider details (Xtream Codes or M3U URL).
3. Click "Refresh Sources" to load the new content.
4. Navigate to Live TV, Movies, or Series to browse your content.

Browser Codec Support & Transcoding

NodeCast-TV is a web-based application, so video decoding is handled by the user’s browser by default. However, it includes smart transcoding to ensure compatibility across different browsers:

| Codec | Chrome | Firefox | Safari | Edge | |-------------|--------|---------|--------|---------------| | H.264 (AVC) | ✅ | ✅ | ✅ | ✅ | | H.265 (HEVC) | Auto-Transcode | Auto-Transcode | ✅ | ⚠️ (Requires HEVC Extensions) | | AV1 | ✅ | ✅ | Auto-Transcode | ✅ | | AAC Audio | ✅ | ✅ | ✅ | ✅ | | AC3/EAC3 (Dolby) | Auto-Transcode | Auto-Transcode | ✅ | Auto-Transcode |

Supported Stream Types

NodeCast-TV is optimized for HLS (HTTP Live Streaming):

• ✅ HLS (.m3u8): Fully supported and recommended for adaptive bitrate streaming.
• ✅ MPEG-TS (.ts): Supported via force remux in settings.
• ⚠️ High Latency/P2P: For sources like Acestream, prefer HLS output to avoid buffering issues.

Transcoding Settings

All transcoding and stream processing settings are accessible via Settings → Transcoding:

Hardware Encoder Options

| Setting | Options | Description | |------------------|----------------------------------|---------------------------------| | Hardware Encoder | Auto, NVENC, AMF, QSV, VAAPI | GPU-accelerated encoding. | | Max Resolution | 4K, 1080p, 720p, 480p | Limit output resolution. | | Quality Preset | High, Medium, Low | Encoding quality/speed tradeoff.| | Audio Mix Preset | Auto, ITU, Night Mode, Cinematic, Passthrough | Sound downmixing options |

Audio Mix Presets

• Auto (Smart): Copies stereo AAC as-is; uses ITU downmix for 5.1+ audio.
• ITU-R BS.775: Industry-standard balanced downmix.
• Night Mode: Boosts dialogue, reduces bass for quiet viewing.
• Cinematic: Enhances soundstage immersion.
• Passthrough: No processing (may cause errors on Dolby sources).

Stream Processing

| Setting | What It Does | When to Enable | |-----------------------------|------------------------------------------------------------------------------|------------------------| | Auto Transcode (Smart) | Probes streams and transcodes only when needed. | Recommended (default ON)| | Force Audio Transcode | Transcodes audio to AAC (video passes through). | For Dolby/AC3 sources | | Force Video Transcode | Full transcode of both audio and video. | For HEVC/VP9 sources | | Force Remux | Remuxes MPEG-TS to MP4 (no re-encoding). | For raw .ts streams |

---

Troubleshooting Common Issues

Video Won’t Play (Black Screen or Loading Forever)

| Symptom | Likely Cause | Solution | |-----------------------------------|----------------------------------|-------------------------------------------| | Black screen + CORS error | Mixed content (HTTPS page loading HTTP streams) | Enable "Force Backend Proxy" in Settings → Transcoding. | | Black screen with MEDIA_ERR_DECODE | Unsupported codec (HEVC/VP9) | Ensure "Auto Transcode" is enabled. | | Loading forever (no error) | Browser decoder stuck | Enable "Force Video Transcode". |

No Audio (Video Plays Fine)

| Symptom | Likely Cause | Solution | |-----------------------------------|----------------------------------|-------------------------------------------| | No audio at all | Dolby/AC3/EAC3 audio | Enable "Force Audio Transcode". | | Audio out of sync | Stream encoding issue | Try changing stream format to TS in Settings. |

Buffering Issues

| Symptom | Likely Cause | Solution | |-----------------------------------|----------------------------------|-------------------------------------------| | Constant buffering | Slow network or weak GPU | 1. Lower "Max Resolution" (e.g., to 720p).
2. Try TS format instead of HLS. |

HTTPS / Reverse Proxy Issues

If NodeCast-TV is running behind a reverse proxy (Nginx, Caddy, Traefik), ensure proper configuration:

CORS & Backend Proxy

Enable "Force Backend Proxy" in Settings → Transcoding → Network to route streams through the server.

Reverse Proxy Examples

Caddy Example

tv.domain.com {
  reverse_proxy nodecast:3000 {
    flush_interval -1
    header_up X-Forwarded-Proto {scheme}
  }
}

Nginx Example

location / {
  proxy_pass http://nodecast:3000;
  proxy_http_version 1.1; # Required for chunked transfers and keep-alive
  proxy_buffering off;    # Don't buffer responses (required for streaming)
  proxy_request_buffering off; # Don't buffer requests
  proxy_read_timeout 300s;   # VOD: 5 min timeout for large files
  proxy_connect_timeout 60s; # VOD: Connection timeout
  client_max_body_size 0;    # No upload size limit
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme; # Required for HTTPS detection
  proxy_set_header Connection ""; # VOD: Enable keep-alive for Range requests
}

IPTV Middleware (m3u-editor, DispatchArr, Threadfin, xTeVe)

If using middleware tools like m3u-editor or TVHeadend, ensure:

1. "Force Backend Proxy" is enabled to bypass CORS restrictions.
2. Auto-transcoding detects and remuxes raw MPEG-TS streams automatically.

TVHeadend Integration

To integrate NodeCast-TV with TVHeadend:

1. Enable "Force Backend Proxy" in Settings → Transcoding → Network.
2. Alternatively, configure TVHeadend to allow CORS requests from your NodeCast-TV URL.
3. Ensure proper authentication (digest+plain) if using username/password in M3U URLs.

Acestream / P2P Streaming

For Acestream sources:

• Prefer HLS output format (http://proxy:6878/ace/manifest.m3u8?id=...) to reduce server load.
• If raw MPEG-TS streams are used, NodeCast-TV will automatically remux them.

---

Technical Stack

NodeCast-TV is built with a modern and efficient tech stack:

| Component | Technology Used | |-----------------|----------------------------------------| | Backend | Node.js, Express | | Frontend | Vanilla JavaScript (ES6+), CSS3 | | Database | SQLite (via better-sqlite3) | | Streaming | HLS.js for stream playback | | Transcoding | FFmpeg (integrated for hardware/software transcoding) |

---

Project Structure

The NodeCast-TV repository follows a modular structure:

nodecast-tv/
├── public/
│   ├── css/          # Stylesheets
│   ├── js/           # Client-side logic
│       ├── components/  # UI Components (ChannelList, EpgGuide, etc.)
│       ├── pages/     # Page Controllers (Movies, Series, etc.)
│       └── api.js    # API Client
│   └── index.html    # Main entry point
├── server/
│   ├── routes/       # API Endpoints (proxy, transcode)
│   ├── services/     # Playlist parsers, SyncService, etc.
│   ├── db/          # Database Logic
│       ├── index.js  # Legacy DB Wrapper
│       └── sqlite.js # SQLite Connection & Schema
│   └── index.js      # Server Entry Point
└── data/            # Persistent storage (content.db, playlists)

---

License

NodeCast-TV is licensed under the GNU General Public License v3.0 (GPL-3.0). This means:

• You can run, study, and modify the software for any purpose.
• You must provide source code to recipients.
• Any derivative works must also be licensed under GPL-3.0.

For more details, refer to the LICENSE file in the repository.

---

Conclusion

NodeCast-TV is a versatile and high-performance web-based IPTV player designed for both administrators and end-users. Its features—such as live TV streaming, an interactive EPG, VOD support, hardware transcoding, and SSO integration—make it a powerful tool for managing and delivering digital television content. Whether deployed locally via Docker or integrated with middleware like TVHeadend, NodeCast-TV provides flexibility and scalability for modern IPTV setups.

For further customization, users can explore the project’s source code, modify settings, and extend functionality based on their specific requirements. The application’s open-source nature ensures transparency and community-driven improvements in the future.