nodecast-tv is a modern, web-based IPTV player featuring Live TV, EPG, Movies (VOD), and Series support. Built with performance and user experience in mind.

• 📺 Live TV: Fast channel zapping, category grouping, and search.
• 📅 TV Guide (EPG): Interactive grid guide with 24h timeline, search, and dynamic resizing.
• 🎬 VOD Support: Dedicated sections for Movies and TV Series with rich metadata, posters, and seasonal episode lists.
• ❤️ Favorites System: Unified favorites for channels, movies, and series with instant synchronization.
• 🔐 Authentication: User login system with admin and viewer roles (details).
• ⚡ High Performance: Optimized for large playlists (7000+ channels) using virtual scrolling and batch rendering.
• ⚙️ Management:
  • Support for Xtream Codes and M3U playlists.
  • Manage hidden content categories.
  • Playback preferences (volume memory, auto-play).
• 🔊 Audio Transcoding: Optional FFmpeg-based audio transcoding for Dolby/AC3/EAC3 compatibility.
• 📦 Stream Remux: Lightweight FFmpeg remux for raw MPEG-TS streams from IPTV middleware.
• 🐳 Docker Ready: Easy deployment containerization.

• Node.js (v14 or higher)
• npm

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

4. Open your browser at http://localhost:3000.

You can run nodecast-tv easily using Docker.

1. Create a docker-compose.yml file (or copy the one from this repo):

   services:
     nodecast-tv:
       build: https://github.com/technomancer702/nodecast-tv.git#main
       container_name: nodecast-tv
       ports:
         - "3000:3000" # Host:Container
       volumes:
         - ./data:/app/data
       restart: unless-stopped
       environment:
         - NODE_ENV=production
         - PORT=3000 # Optional: Internal container port

2. Run the container:

   docker-compose up -d

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

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

nodecast-tv is a web-based application, which means video decoding is handled by your browser, not by the server. The server simply proxies the stream data - it does not transcode or re-encode video.

This means codec support depends entirely on what your browser can decode natively:

Notes:

1. Chrome may support HEVC on macOS with hardware decoder
2. Edge requires the paid "HEVC Video Extensions" from Microsoft Store ($0.99)
3. Safari VP9 support varies by device/version

If a stream doesn't play:

• The stream codec may not be supported by your browser
• Try a different browser (Safari for HEVC/Dolby, Chrome/Edge for VP9/AV1)
• Check if your IPTV provider offers alternative stream formats
• For Dolby audio issues, enable "Force Audio Transcode" in Settings → Streaming

For streams with Dolby Digital (AC3/EAC3) audio that browsers can't decode natively:

1. Install FFmpeg support: npm install ffmpeg-static (included as optional dependency)
2. Enable "Force Audio Transcode" in Settings → Streaming
3. Audio will be transcoded to AAC while video passes through unchanged

Note: For ad-stitched live streams (like Pluto TV), transcoding may struggle to keep up. These streams typically use AAC audio already, so the built-in HLS discontinuity handling manages audio transitions without transcoding.

nodecast-tv is optimized for HLS (HTTP Live Streaming).

• ✅ HLS (.m3u8): Fully supported and recommended. Best for adaptive bitrate and network resilience.
• ✅ MPEG-TS (.ts): Supported via Force Remux in settings.
• ⚠️ High Latency/P2P: For sources like Acestream, prefer HLS output (.m3u8) over raw TS streams to avoid timeouts during buffering.
• ❌ RTMP/RTSP: Not supported natively by browsers.

All streaming settings are found in Settings → Player → Streaming.

If you're running nodecast-tv behind a reverse proxy (Nginx, Caddy, Traefik) with HTTPS:

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
}

If you're using IPTV middleware like m3u-editor, dispatcharr, Threadfin, or xTeVe to manage your streams, you may need to adjust nodecast-tv settings for optimal playback. These tools typically use passthrough mode, which preserves original codecs (like HEVC/Dolby) that most browsers cannot decode natively, and may also trigger CORS restrictions.

Output Format Compatibility:

Why Proxied TS Fails: When middleware is set to "Proxy" mode, it wraps the stream in its own layer. NodeCast's Remux/FFmpeg can't parse this format (error: Invalid data found when processing input). Configure your middleware to output HLS (m3u8) instead.

Recommended Settings in nodecast-tv:

m3u-editor includes an internal proxy that remuxes streams to MPEG-TS.

Setup:

1. In m3u-editor, configure your playlist and enable the proxy if needed
2. In nodecast-tv, enable "Force Remux" in Settings → Streaming (for raw .ts streams)
3. If audio doesn't play, enable "Force Audio Transcode" instead

Note: m3u-editor's proxy preserves original codecs. If your source has HEVC or Dolby, you'll need transcoding or a compatible browser (Safari).

dispatcharr uses FFmpeg stream profiles to process streams. By default it outputs MPEG-TS with passthrough codecs.

Setup:

1. In dispatcharr, streams are proxied by default via stream profiles
2. In nodecast-tv, enable "Force Remux" in Settings → Streaming (for raw .ts streams)
3. If audio doesn't play, enable "Force Audio Transcode" instead

Custom dispatcharr profile for browser compatibility: If you want dispatcharr to transcode audio for you instead of nodecast-tv:

-user_agent {userAgent} -i {streamUrl} -c:v copy -c:a aac -f mpegts pipe:1

This keeps video passthrough but converts audio to AAC.

These HDHomeRun emulators work similarly to other middleware.

Setup:

1. Add your Threadfin/xTeVe M3U URL as an M3U source in nodecast-tv
2. Enable "Force Remux" in Settings → Streaming (for raw .ts streams)
3. If needed, enable "Force Audio Transcode" instead for Dolby audio

If you're using TVHeadend as your source, you may need to configure a few settings for streams to play correctly in nodecast-tv:

Option 1: Enable Force Backend Proxy (Easiest)

• In nodecast-tv, go to Settings → Player → Streaming
• Enable "Force Backend Proxy"
• This routes streams through the server, bypassing browser CORS restrictions

Option 2: Configure TVHeadend CORS

• In TVHeadend, go to Configuration → General → Base → HTTP Server Settings
• Add your nodecast-tv URL to "CORS origin" (e.g., http://192.168.1.100:3000)
• Note: You must include the protocol (http:// or https://)

Additional Tips:

• Enable "digest+plain" authentication in TVHeadend if using username/password in the M3U URL
• Try different stream profiles (?profile=pass or ?profile=matroska) if playback issues persist

If you are using acestream-docker-home or similar tools, you MUST use the HLS output format.

• Don't use: http://proxy:6878/ace/getstream?id=... (This is a raw MPEG-TS stream)
• Do use: http://proxy:6878/ace/manifest.m3u8?id=... (This wraps the stream in a browser-friendly HLS playlist)

• Backend: Node.js, Express
• Frontend: Vanilla JavaScript (ES6+), CSS3
• Database: SQLite (via better-sqlite3) for high-performance data storage
• Streaming: HLS.js for stream playback
• Audio Transcoding: FFmpeg (optional, via ffmpeg-static)

nodecast-tv/
├── public/              # Frontend assets
│   ├── 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/              # Backend 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)

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You are free to:

• Run the program for any purpose
• Study how the program works and change it
• Redistribute copies
• Distribute copies of your modified versions

Under the condition that:

• You typically must distinguish your modifications from the original work
• You provide the source code to recipients
• You license any derivative works under the same GPL-3.0 license

See the LICENSE file for details.