4grayandClaude Opus 4.8
d76b2d2a57
* fix(tmdb): stop a broken provider tmdb_id from suppressing enrichment
Providers ship dead and stale tmdb_id values, and enrich() trusted them
unconditionally:
parseProviderTmdbId(query.tmdbId) ?? await resolveIdBySearch(...)
A garbage-but-integer id short-circuited the title search entirely. The
details fetch then 404'd, the outer catch swallowed it, and the item was
left permanently unenriched — no plot, no cast, no artwork — for a title
the search would have matched. Failed detail fetches cache nothing, so
the wasted request repeated on every re-open. The stale-but-valid case
was worse: it never threw, nothing sanity-checked the resolved title, and
we confidently rendered another film's metadata.
enrich() now treats the provider id as a hint. If it fails to resolve, or
resolves to something whose title matches none of the search variants we
would have queried, the confidence-gated title search gets its turn — and
proven-bad ids are negative-cached (7d, language-independent row) so the
404 is not repeated forever.
Deliberately NOT a hard rejection on title mismatch: TMDB returns titles
in the REQUEST language, so a Russian provider title legitimately fails
the name check against an en-US payload. A mismatch only lets the search
compete; when the search finds nothing confident, the provider payload is
kept. The change can therefore only add enrichment, never remove it.
Extracts the search resolution and the bad-id cache into
TmdbIdResolverService — tmdb-enrichment.service.ts was at 290 lines
against the 300-line target, and the resolver is independently testable.
Tests: new tmdb-enrichment.service.spec.ts covers the happy path issuing
exactly one details call and no search, 404 fallback, stale-id override,
the keep-the-payload safety property, bad-id skip, and the no-match case;
matcher spec covers detailsMatchProviderTitle and the namespaced cache key.
Refs docs/architecture/tmdb-roadmap.md A1.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tmdb): only blame a provider id when TMDB confirms it does not exist
Review found the bad-id negative cache too eager in two ways, both of
which could deny enrichment to items whose id was fine.
1. Any failure recorded the verdict. A 401, 429, 5xx or an offline blip
would mark a perfectly valid id as dead for seven days, so after the
service recovered — or the user fixed their API key — titles that the
search cannot resolve confidently stayed unenriched until the marker
expired. TmdbApiService now throws a typed TmdbApiError carrying the
status, and only a confirmed 404 is recorded.
2. Title mismatches were recorded too. That id EXISTS; it is merely wrong
for this item. The row is keyed by id alone and shared across
playlists, so a stale mapping on one item disabled the direct lookup
for every other item that legitimately used the same id. Mismatches
are no longer cached at all — the search verdict is cached anyway, so
the repeat cost is a single details fetch.
Documents the row kind in the cache contract, which listed only two of
the (now six) lookup_key shapes.
Tests: 404 records, 429 does not, network error does not, mismatch does
not.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tmdb): keep provider details when the competing search fails
detailsForProviderId only runs the search to see whether it can beat a
title-mismatched provider payload. A throw from that best-effort search
(offline, rate limit, 5xx) propagated to enrich()'s outer catch and threw
away details we already had — the searched-details fetch right below it
was already tolerant. Fail to the details in hand instead.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tmdb): decide a suspect provider id on evidence, not on the title
The title check alone was both too weak and too dangerous.
Too weak: normalizeTitle strips trailing years, so "Blade Runner 2049"
carrying the 1982 film's id matched and the wrong film was rendered —
exactly the stale-id case this was meant to catch.
Too dangerous: an ALL-CAPS leading token reads as a language tag, so
"IT - Chapter Two" normalizes to "chapter two". The correct payload
failed the name check, and a year-less search for "chapter two" would
confidently return the 1979 film and overwrite it. Master trusted the
provider id here and got it right.
assessProviderId weighs both signals: title or year agrees means use the
details; both years known and incompatible means the search may take
over; a title-only mismatch is inconclusive and keeps the details. The
search branch now always has a year, so its own gate corroborates
whatever it returns instead of matching on name alone.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tmdb): do not search after a transient provider-id failure
enrich() reads a null from detailsForProviderId as "the id is unusable,
try the search". A 401/429/5xx/offline failure gave it that null, so an
outage turned into a second request that would fail too — and if it did
come back, a title match replaced a provider id that was probably fine.
Only a 404 falls through to the search now; everything else rethrows and
leaves the id retryable.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs(tmdb): add the release note for the provider-id fix
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
IPTVnator - IPTV Player Application
🌐 Website | Telegram channel for discussions | Buy me a coffee | GitHub Sponsors
IPTVnator is a video player application that provides support for IPTV playlist playback (m3u, m3u8). The application allows users to import playlists using remote URLs or by uploading files from the local file system. Additionally, it supports EPG information in XMLTV format which can be provided via URL.
The application is a cross-platform, open-source project built with Electron and Angular.
⚠️ Note: IPTVnator does not provide any playlists or other digital content. The channels and pictures in the screenshots are for demonstration purposes only.
Important
Official sources only. IPTVnator is a free, open-source player — it never sells IPTV subscriptions, channels, or playlists. Websites offering "IPTVnator subscriptions/channels/premium/activated" builds are not affiliated with this project. Get the app only from the official website or GitHub Releases. See Beware of unofficial IPTVnator websites and IPTV services for details.
Features
Playlists & sources
- M3U / M3U8 playlists from local files or remote URLs 📂, with automatic updates on startup
- Xtream Codes (XC) and Stalker / Ministra (STB) portal support
- Custom "User-Agent" header per playlist
Playback
- Built-in HTML5 player (HLS.js or Video.js) with a resizable, resumable inline view
- Optional unified IPTVnator controls for HTML5, Video.js, and ArtPlayer, enabled in Settings → Playback (experimental)
- External players — MPV, VLC, and IINA on macOS (
mpv.app/VLC.appbundle paths supported) (desktop) - Embedded MPV — native mpv rendered inside the app window on macOS, Windows & Linux 🖥️ (experimental · desktop)
- Dedicated radio player for
radio="true"streams 📻
Live TV & EPG
- EPG / XMLTV TV guide with a live timeline ribbon and multi-channel grid (desktop)
- TV archive / catch-up / timeshift (desktop)
- Group-based channel list, channel-number selection, and search 🔍
Movies & series (VOD)
- Redesigned two-state detail pages (browse ↔ watch) with season tabs and resume positions
- Download manager for offline movies & episodes ⬇️ (desktop)
- "Recently added" feeds and category grids with sorting & pagination
Discovery & metadata
- Global search across live TV, movies, and series (desktop)
- TMDB enrichment (opt-in) — plots, cast & crew, trailers, ratings, artwork, a "Similar" rail, clickable actor pages, and a trending dashboard rail (trending rail: desktop)
- Dashboard with recently watched & continue-watching
Organization
- Per-playlist and global favorites, aggregated across all playlists ⭐
- Recently viewed / watch history
- Command palette (
Ctrl/Cmd+K)
Platform
- Cross-platform desktop (Electron) and installable PWA
- Desktop auto-updater and mobile remote control (desktop)
- Docker self-hosting for the PWA + web backend
- 19 languages (translation files), light & dark themes, and keyboard shortcuts
Keyboard shortcuts
Press ? or Shift+/ in the workspace to open the in-app shortcuts list.
| Area | Shortcut | Action |
|---|---|---|
| Global | Ctrl/Cmd+K |
Open command palette |
| Global | Ctrl/Cmd+F |
Open global search in the desktop app |
| Global | Ctrl/Cmd+R |
Open recently viewed in the desktop app |
| Global | Enter in workspace search |
Submit the current search |
| Navigation | Ctrl/Cmd+B |
Toggle the live sidebar |
| Navigation | 0-9 |
Select an M3U channel by number |
| Playback | Space / K |
Play or pause embedded MPV playback in the desktop app |
| Playback | F |
Toggle embedded MPV fullscreen in the desktop app |
| Playback | ArrowLeft / ArrowRight |
Seek embedded MPV playback by 5 seconds in the desktop app |
| Playback | ArrowUp / ArrowDown |
Adjust volume by 5% |
| Playback | M |
Mute audio |
| Dialogs and lists | ArrowUp / ArrowDown |
Move command palette selection |
| Dialogs and lists | Enter |
Run the selected command or open a focused item |
| Dialogs and lists | Escape |
Close dialogs and dismiss overlays |
Screenshots:
| Dashboard with recently watched content | Live channels with inline player and EPG |
|---|---|
 |
|
| Add playlist dialog for M3U, Xtream, and Stalker | Live category channel list |
 |
 |
| Global search across live TV, movies, and series | Manage visible live categories |
 |
 |
| Movie category grid with sorting and pagination | Recently added movies and series |
 |
 |
| VOD details with playback and download actions | Download manager |
 |
 |
| Multi-channel EPG grid | External MPV player support |
 |
 |
| Radio playback with dedicated audio player | Light theme |
 |
 |
| Application settings | |
 |
Note: First version of the application which was developed as a PWA is available in an extra git branch.
Self-hosted PWA
The Docker setup builds the Angular PWA and the monorepo web backend into one
image. The backend handles remote M3U parsing plus Xtream and Stalker proxy
requests under /api, so a separate 4gray/iptvnator-backend container is not
required for the default self-hosted flow.
docker compose -f docker/docker-compose.yml up --build -d
The application is available at http://localhost:4333. See
docker/docker-compose.yml for the ready-to-run
compose file and docker/README.md for environment
variables, reverse proxy notes, PWA limitations, and build details.
The self-hosted image runs the browser PWA rather than the Electron desktop app: EPG/XMLTV panels, Embedded MPV, managed MPV/VLC launching, the download manager, and Electron remote-control features are not available there. If browser playback fails, copy the stream URL and open it manually in an external player such as MPV, VLC, or IINA.
Download
Download the latest version of the application for macOS, Windows, and Linux from the release page.
Alternatively, you can install the application using one of the following package managers:
Homebrew
$ brew install iptvnator
Snap
$ sudo snap install iptvnator
Arch
Also available as an Arch PKG, iptvnator-bin, in the AUR (using your favourite AUR-helper, .e.g. yay)
$ yay -S iptvnator-bin
Gentoo
You can install IPTVnator from the gentoo-zh overlay
sudo eselect repository enable gentoo-zh
sudo emerge --sync gentoo-zh
sudo emerge iptvnator-bin
Linux Embedded MPV Support
Embedded MPV on Linux is experimental and currently supports x64 desktop
sessions where IPTVnator runs under X11 or Xwayland. Native Wayland embedding
is not supported yet. Linux package launchers request X11 with
--ozone-platform=x11, so Wayland desktops still need Xwayland available.
The Linux backend starts a system mpv executable with --wid, so mpv must
be installed and available on PATH. CI validates the Linux native addon and
standard packages on Ubuntu 22.04, with Flatpak packaging built on Ubuntu 24.04.
Expected user targets are Ubuntu/Debian .deb, Arch/Manjaro pacman, RPM
distributions, and AppImage on x64 systems with X11/Xwayland plus mpv
installed. Flatpak and Snap builds remain available, but embedded MPV is not
announced as supported there yet because those sandboxed formats do not expose
the host mpv executable to the embedded backend by default.
Troubleshooting
macOS: "App is damaged and can't be opened"
Older unsigned macOS builds may require removing the quarantine flag from the downloaded application:
xattr -c /Applications/IPTVnator.app
Alternatively, if the app is located in a different directory:
xattr -c ~/Downloads/IPTVnator.app
Linux: chrome-sandbox Issues
If you encounter the following error when launching IPTVnator:
The SUID sandbox helper binary was found, but is not configured correctly.
Rather than run without sandboxing I'm aborting now.
You need to make sure that chrome-sandbox is owned by root and has mode 4755.
Solution 1: Fix chrome-sandbox permissions (Recommended for .deb/.rpm installations)
Navigate to the IPTVnator installation directory and run:
sudo chown root:root chrome-sandbox
sudo chmod 4755 chrome-sandbox
Solution 2: Launch with --no-sandbox flag
Edit the desktop launcher file to add the --no-sandbox flag:
-
Find your desktop file location:
- Ubuntu/Debian:
~/.local/share/applications/iptvnator.desktop - System-wide:
/usr/share/applications/iptvnator.desktop
- Ubuntu/Debian:
-
Edit the file and modify the
Execline:Exec=iptvnator --no-sandbox %U -
Save the file and relaunch the application from your application menu.
Alternatively, you can launch IPTVnator from the terminal with the flag:
iptvnator --no-sandbox
GNU/Linux: Wayland startup failure
If IPTVnator exits on GNU/Linux with errors about failing to connect to Wayland or initialize the Ozone platform, force X11/XWayland instead:
iptvnator --ozone-platform=x11
This workaround is mainly for older or problematic Linux graphics stacks. The Snap package already includes this X11 override by default. For AppImage, direct binaries, and other Linux package formats, pass the flag manually when needed.
How to Build and Develop
Requirements:
- Node.js with pnpm (via Corepack)
-
Clone this repository and install project dependencies:
$ corepack enable $ pnpm install -
Start the application:
$ pnpm run serve:backend
This will open the Electron app in a separate window, while the Angular dev server will run at http://localhost:4200.
The equivalent Nx command is:
$ nx serve electron-backend
To start Electron with an empty, isolated data directory instead of your normal
~/.iptvnator folder, set IPTVNATOR_E2E_DATA_DIR for that run:
$ rm -rf .tmp/iptvnator-empty && mkdir -p .tmp/iptvnator-empty
$ IPTVNATOR_E2E_DATA_DIR="$PWD/.tmp/iptvnator-empty" pnpm run serve:backend
This redirects the SQLite database, Electron user data, and local config under the given directory. Delete that directory whenever you want a fresh empty state.
If you need startup diagnostics for a white screen or a frozen route, you can also turn on opt-in Electron tracing. These logs are written to the Electron terminal output so they still help when the renderer DevTools never open:
$ IPTVNATOR_TRACE_STARTUP=1 pnpm run serve:backend
Nx equivalent:
$ IPTVNATOR_TRACE_STARTUP=1 nx serve electron-backend
Useful narrower flags:
IPTVNATOR_TRACE_IPC=1logs rendererwindow.electron.*calls reaching the Electron bridgeIPTVNATOR_TRACE_DB=1logs DB worker requests and request-scoped DB eventsIPTVNATOR_TRACE_SQL=1logs SQLite statements in both the main connection and DB worker connectionIPTVNATOR_TRACE_WINDOW=1logs BrowserWindow load, navigation, and unresponsive eventsIPTVNATOR_TRACE_RENDERER_CONSOLE=1mirrors renderer console messages into the Electron terminal output
Security-sensitive network compatibility flags are opt-in:
IPTVNATOR_ALLOW_PRIVATE_NETWORK_URLS=1permits strict EPG fetches from playlist metadata (x-tvg-url,url-tvg, ortvg-url) to resolve to localhost, LAN, or other private addresses. Directly configured Xtream/Stalker portals and private playlist servers remain supported without this flag. Prefer the in-app source-scoped “Allow source” action for a trusted EPG URL.IPTVNATOR_ALLOW_INSECURE_TLS=1disables certificate validation for remote playlist imports and refreshes for the whole Electron process. Prefer the in-app host-scoped trust action for a trusted provider with a self-signed or otherwise invalid certificate.
If the local Nx daemon gets into a bad state before rerunning Electron, reset it:
$ pnpm nx reset
To run only the Angular app without Electron, use:
$ pnpm run serve:frontend
Disclaimer
IPTVnator doesn't provide any playlists or other digital content.
Trademark
The name "IPTVnator" and the IPTVnator logo are unregistered trademarks of the project owner. The MIT license covers the source code only — it does not grant rights to the name or logo. Forks and redistributions (including app-store submissions) must use a different name and their own icon. See TRADEMARK.md for details.
