IPTVnator Documentation

IPTVnator is an open-source IPTV player application. It supports the following protocols and formats:

• M3U/M3U8 playlists
• Xtream Codes API
• Stalker portals

It is available as a desktop application (via Electron) and as a Progressive Web App (PWA) that runs directly in a web browser.

The IPTVnator active panel uses a tiered approach to fetch EPG data from Stalker portals to ensure usability even when APIs are inconsistent:

1. Primary Method (get_epg_info): Attempts a bulk request to fetch EPG data for multiple channels.
2. Fallback Method (get_short_epg): If the bulk request fails, returns an empty response, or the selected channel is missing from the bulk cache, the active panel falls back to per-channel requests via get_short_epg.

Limitation: While the active panel falls back to per-channel requests, row previews do not. Row previews will remain empty until the bulk EPG (get_epg_info) becomes available.

Supported Formats

IPTVnator uses the XMLTV format for EPG data. Supported file extensions include:

• .xml
• .xml.gz (compressed)

EPG Features

Once configured, the following information is available in the UI:

• Current program: Displayed next to channels in the channel list.
• Progress bar: Indicates the elapsed time of the current program.
• Program details: Shown in the right sidebar when a channel is selected.
• Upcoming schedule: Displays times and descriptions for future programs.

Performance and Management

• Caching: Parsed EPG data is cached in the database (Electron version) to handle large files efficiently.
• Multiple Sources: You can add multiple EPG sources per playlist.
• Auto-refresh: The EPG automatically refreshes periodically to maintain schedule accuracy.

Version 0.22.0 introduces several UI and desktop improvements:

• Custom title bar: Includes window controls on Windows and Linux.
• Improved Sidebar Layout: The Live TV channel sidebar no longer shares its width with the navigation panel.
• Visual Polish: Updates to the Sources page design.
• Remote Control: Volume controls now apply to the built-in M3U players.

IPTVnator uses an engine-agnostic contract to separate player UI presentation from the underlying media engine. This allows the same UI component (app-player-controls) to work across different playback engines like HTML5, Video.js, ArtPlayer, and Embedded MPV.

Architecture Layers:

1. Presentation: The app-player-controls component handles rendering menus, feedback, auto-hide, and scrub UI.
2. Contract: The PlayerController interface acts as the bridge.
3. Adapters: Engines implement the contract via adapters (e.g., WebVideoControlsAdapter for web engines or EmbeddedMpvControlsAdapter for MPV).
4. Engines: The actual media players (HTML5, Video.js, ArtPlayer, or MPV) that execute the commands.

The Download Manager is a desktop-only feature in IPTVnator that provides a curated queue, progress tracking, storage configuration, and playback controls. It operates by layering these capabilities on top of existing Xtream and Stalker portal views.

Architecture overview:

• Backend (Electron process): Handles queue control, range-aware byte transfers (using Axios), destination collision policies, and IPC (Inter-Process Communication) management.
• Renderer (Angular): Exposes the /downloads route, manages the UI via a dedicated DownloadsService, and communicates with the backend through the window.electron bridge.
• Data Persistence: Uses a shared downloads SQLite table to track statuses (queued, downloading, paused, completed, failed, canceled) and metadata like bytesDownloaded, totalBytes, and resume_validator.

The ChannelListContainerComponent acts as a shared state coordinator for the channel sidebar. It manages several key signals to coordinate data across different views:

• channelEpgMap: A Map<string, EpgProgram> for EPG data.
• progressTick: A number updated at 30s intervals to drive EPG progress updates.
• shouldShowEpg: A boolean flag.
• favoriteIds: A Set<string> containing favorite channel IDs.

Data flows from this parent component down to specialized views: AllChannelsView, GroupsView, FavoritesView, and RecentView. When a channel is selected in any view, it emits a channelSelected output which triggers ChannelActions.setActiveChannel in the store.

IPTVnator uses two distinct rendering paths for its embedded MPV integration depending on the platform and engine used:

1. Native-view engine: Renders into an app-owned platform video surface:
   • macOS: Uses the libmpv render API within an NSOpenGLView (to avoid black video surfaces caused by the wid path).
   • Windows: Loads libmpv via a native Node addon and uses the mpv wid option targeting an IPTVnator-owned child HWND.
   • Linux: Creates an IPTVnator-owned X11/Xwayland child Window and starts an out-of-process mpv --wid=<window> instance.
2. Frame-copy engine (Experimental): Uploads frames produced by a helper process to a Chromium-owned DOM canvas. This is available for Apple Silicon (macOS), Linux x64, and Windows.

The /workspace route is the primary application surface. The WorkspaceShellComponent provides a persistent frame consisting of a left rail, a top header, an optional context panel, a main content outlet, and an optional external playback footer.

All descendant workspace pages inherit the layout = 'workspace' configuration from the /workspace root route. Instead of using nested provider shell components, the system uses route-scoped session providers to bootstrap state (like active playlists) and clean up local state when routes are destroyed.