iptvnator/docs/architecture/m3u-playlist-module.md

M3U Playlist Module Architecture

This document describes the M3U playlist module architecture, which handles traditional M3U/M3U8 playlists (as opposed to Xtream Codes or Stalker Portal).

Overview

The M3U playlist module provides:

• Channel list display with virtual scrolling (90,000+ channels support)
• EPG (Electronic Program Guide) integration
• Favorites management with drag-and-drop reordering
• Channel grouping, search, and per-list channel sorting
• Per-playlist group visibility management in the groups view
• Video playback with multiple player backends

Module Structure

┌─────────────────────────────────────────────────────────────────────┐
│                         VIDEO PLAYER PAGE                            │
│          libs/playlist/m3u/feature-player/src/lib/video-player/     │
├─────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌──────────────────────┐  ┌────────────────────┐ │
│  │   Sidebar   │  │    Video Player      │  │  EPG Timeline      │ │
│  │             │  │  (ArtPlayer/Video.js)│  │  (panel below)     │ │
│  │ ┌─────────┐ │  │                      │  │                    │ │
│  │ │Channel  │ │  │                      │  │                    │ │
│  │ │List     │ │  │                      │  │                    │ │
│  │ │Container│ │  │                      │  │                    │ │
│  │ └─────────┘ │  │                      │  │                    │ │
│  └─────────────┘  └──────────────────────┘  └────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        NgRx STORE (m3u-state)                        │
│                         libs/m3u-state/                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ Playlist │ │ Channel  │ │   EPG    │ │Favorites │ │  Filter  │  │
│  │ Reducer  │ │ Reducer  │ │ Reducer  │ │ Reducer  │ │ Reducer  │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────────────────┘

State Management (libs/m3u-state/)

State Structure

interface PlaylistState {
    // Active channel being played
    active: Channel | undefined;

    // Whether the current route is still resolving channel data
    channelsLoading: boolean;

    // All channels from current playlist
    channels: Channel[];

    // EPG state
    epg: {
        epgAvailable: boolean;
        activeEpgProgram: EpgProgram | undefined;
        currentEpgProgram: EpgProgram | undefined;
    };

    // Playlist metadata (entity adapter)
    playlistsMeta: {
        ids: string[];
        entities: Record<string, PlaylistMeta>;
        selectedId: string | undefined;
        allPlaylistsLoaded: boolean;
        selectedFilters: PlaylistSourceFilter[];
    };
}

PlaylistMeta is the persisted playlist-facing subset of the playlist entity. For M3U playlists it now also carries hiddenGroupTitles?: string[], which is used by the groups view to remember which group titles the user has hidden.

Actions

Action Group	Actions	Purpose
PlaylistActions	loadPlaylists, addPlaylist, removePlaylist, parsePlaylist, setActivePlaylist	Playlist CRUD
ChannelActions	setChannels, setActiveChannel, setAdjacentChannelAsActive	Channel selection & navigation
EpgActions	setActiveEpgProgram, setCurrentEpgProgram, setEpgAvailableFlag	EPG state
FavoritesActions	updateFavorites, setFavorites	Favorites management
FilterActions	setSelectedFilters	Playlist type filtering

Key Selectors

// Channel selectors
selectActive; // Current playing channel
selectChannelsLoading; // Channel list loading flag
selectChannels; // All channels array
selectFavorites; // Favorite channel URLs

// Playlist selectors
selectAllPlaylistsMeta; // All playlists
selectActivePlaylistId; // Selected playlist ID
selectCurrentPlaylist; // Active playlist object
selectPlaylistTitle; // Title with "Global favorites" fallback

// EPG selectors
selectIsEpgAvailable; // EPG data available flag
selectCurrentEpgProgram; // Current playing program

Channel List Container

Location: libs/ui/components/src/lib/channel-list-container/

Component Architecture

channel-list-container/
├── channel-list-container.component.ts   # Parent - shared state coordinator
├── channel-list-container.component.html
├── channel-list-container.component.scss
│
├── all-channels-tab/                      # Virtual scroll + search
│   ├── all-channels-tab.component.ts
│   ├── all-channels-tab.component.html
│   └── all-channels-tab.component.scss
│
├── groups-tab/                            # Expansion panels + infinite scroll
│   ├── groups-tab.component.ts
│   ├── groups-tab.component.html
│   └── groups-tab.component.scss
│
├── favorites-tab/                         # Drag-drop reordering
│   ├── favorites-tab.component.ts
│   ├── favorites-tab.component.html
│   └── favorites-tab.component.scss
│
└── channel-list-item/                     # Individual channel display
    ├── channel-list-item.component.ts
    ├── channel-list-item.component.html
    └── channel-list-item.component.scss

Data Flow

┌──────────────────────────────────────────────────────────────┐
│              ChannelListContainerComponent                    │
│                      (Parent)                                 │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ Shared State (Signals):                                │  │
│  │  - channelEpgMap: Map<string, EpgProgram>              │  │
│  │  - progressTick: number (30s interval)                 │  │
│  │  - shouldShowEpg: boolean                              │  │
│  │  - favoriteIds: Set<string>                            │  │
│  └────────────────────────────────────────────────────────┘  │
│                           │                                   │
│     ┌─────────────────────┼─────────────────────┐            │
│     ▼                     ▼                     ▼            │
│ ┌─────────┐         ┌──────────┐         ┌───────────┐      │
│ │   All   │         │  Groups  │         │ Favorites │      │
│ │Channels │         │   Tab    │         │    Tab    │      │
│ │  Tab    │         │          │         │           │      │
│ └────┬────┘         └────┬─────┘         └─────┬─────┘      │
│      │                   │                     │             │
│      └───────────────────┴─────────────────────┘             │
│                          │                                   │
│                          ▼                                   │
│              (channelSelected) output                        │
│                          │                                   │
└──────────────────────────┼───────────────────────────────────┘
                           ▼
                    Store Dispatch
              ChannelActions.setActiveChannel

Loading States

• M3uWorkspaceRouteSession owns route-driven channel loading for the player/sidebar routes: all and groups.
• The route session sets channelsLoading before getPlaylist() resolves and clears it when ChannelActions.setChannels lands.
• ChannelListContainerComponent now renders a dedicated skeleton state while channelsLoading is true.
• ChannelListContainerComponent no longer clears channels on destroy; route/session code is the single owner of shared list lifecycle during navigation.
• The dedicated /workspace/playlists/:id/favorites and /workspace/playlists/:id/recent collection routes do not drive the shared sidebar channel list; they default to the playlist scope so rail links always open the current playlist view, not the last persisted global scope.
• M3U favorites and recent collection rows preserve their full Channel payload on unified live items so the shared live list can open the read-only channel details context menu without reconstructing partial channel data.
• Recent live rows support context-menu removal in the unified all-playlists view; the row-level delete shortcut remains available on playlist-scoped M3U recent rows.
• Empty playlists and empty search results are no longer conflated:
  • loading: skeletons
  • empty source: no channels in the playlist after loading completes
  • empty search: no matches within an already loaded playlist

Group Visibility Management

• GroupsViewComponent owns the M3U-only "Manage groups" action and dialog in libs/ui/components/src/lib/channel-list-container/groups-view/.
• The groups rail header also owns an inline search toggle that filters the currently visible groups without mutating the workspace-level route search term used by the broader channel views.
• The dialog operates on the full grouped dataset, while the left rail and channel pane render only groups whose titles are not listed in hiddenGroupTitles.
• ChannelListContainerComponent reads hiddenGroupTitles from the active M3U playlist metadata and passes it into the groups view. Saving dialog changes dispatches PlaylistActions.updatePlaylistMeta.
• PlaylistsService.updatePlaylistMeta() persists hiddenGroupTitles into the stored playlist payload, and M3U refresh/update flows preserve the existing value when refreshed playlist data omits the field.
• The groups route keeps the manage action reachable even when every group is hidden by separating "playlist has no groups" from "no visible/search-matching groups" empty states.

Channel Sorting

• AllChannelsViewComponent owns sorting for the all-channels list and persists the selected mode under m3u-all-channels-sort-mode.
• GroupsViewComponent owns sorting for the selected group's channel pane and persists the selected mode under m3u-groups-channel-sort-mode.
• Both views support three modes: Playlist Order, Name A-Z, and Name Z-A. Playlist Order is the default and preserves the original channel order from the M3U playlist.
• Sorting is applied after the current search filter and before virtual-scroll rendering. Playlist order avoids cloning the full list when no search term is active.

EnrichedChannel Pattern

For performance optimization, channels are pre-enriched with EPG data:

interface EnrichedChannel extends Channel {
    epgProgram: EpgProgram | null | undefined;
    logo: string; // Playlist tvg-logo first, XMLTV icon fallback second
    progressPercentage: number; // Pre-computed by parent
}

The renderer now keeps two lookup maps for M3U collection views:

• channelEpgMap for current-program preview data
• channelIconMap for XMLTV channel icon fallback data

Logo resolution is runtime-only and follows this rule:

1. playlist tvg-logo
2. matched XMLTV <channel><icon src="...">
3. generic live_tv fallback in the list item component

EPG lookup keys use the same precedence in both program and icon paths:

1. tvg-id
2. tvg-name
3. channel name

All four collection tabs (all-channels, groups, favorites, recent) share a single EPG-enrichment implementation in channel-list-container/epg-enrichment.util.ts, fed the same channelEpgMap/channelIconMap from the container — there is no per-tab EPG logic:

• calculateEpgProgress(program, now?) — clamped, rounded progress in [0, 100], guarded against missing/invalid timestamps and zero-length programmes (never returns NaN).
• resolveChannelEpgProgram(channel, channelEpgMap) — the current programme for a channel by its lookup key (used by the per-item recent view).
• buildChannelEpgMetadataMap(channelEpgMap, now?) — the side-car key → {epgProgram, progressPercentage} map (used by all-channels/groups/ favorites). Callers read their progressTick() signal first so the computed re-runs on the ~30s tick.

EPG Panel (Timeline & List views)

The programme guide under the player renders in one of two interchangeable views, chosen by the epgViewMode setting ('timeline' default, or 'list'; Settings → EPG → Guide view):

• Timeline — a horizontal ribbon (app-epg-timeline, libs/ui/epg/src/lib/epg-timeline/).
• List — a vertical, single-day programme list (app-epg-list-view, libs/ui/epg/src/lib/epg-list-view/) with a prev/today/next stepper.

Both are shared by all four live surfaces: the M3U video player, the unified live tab, and the Xtream and Stalker live-stream layouts (replacing the former vertical app-epg-list / app-epg-view). EpgListViewComponent mirrors EpgTimelineComponent's input/output contract 1:1, so each host swaps them with a plain @if (epgViewMode() === 'list') { <app-epg-list-view … /> } @else { <app-epg-timeline … /> } — identical bindings in both branches. Hosts read epgViewMode from SettingsStore (a signal), so flipping the setting swaps the panel live. The setting flows end-to-end (Settings.epgViewMode → DEFAULT_SETTINGS → SettingsStore/StorageMap → the segmented control in settings-epg-section) and needs no backend change. The control is Electron-only in practice — the EPG settings section (and the form control) is gated behind supportsEpg, which is false in PWA; there the stored value simply stays at the 'timeline' default.

Both components stay presentation-focused; the reusable, view-agnostic pieces (shared by the timeline and the list) are split out and re-exported from @iptvnator/ui/epg:

• epg-timeline.utils.ts (axis/blocks/date helpers) + epg-timeline-render.util.ts (short-programme tiers, grouping, zoom bounds) — the ribbon geometry.
• epg-archive.util.ts — catch-up gating (isWithinArchiveWindow, canCatchUpProgramme, epgDialogActionFor) off when/startMs primitives.
• epg-summary.util.ts — EpgTimelineSummary + collapsed-summary progress maths (summaryProgress / summaryMinutesLeft / …).
• epg-programme-dialog.service.ts — EpgProgrammeDialogService, opens the shared details dialog and returns the chosen live / timeshift action.
• epg-timeline-scroll.controller.ts — TimelineScrollController (ribbon scrolling + channel-select auto-focus); timeline-specific, kept out of the component so it stays under the line ceiling.

The list view (epg-list-view/) composes those same shared modules — it does not duplicate classification or gating logic. It reuses classifyTimelineWhen / hasProgramsForDateKey / nearestDateKeyWithPrograms, epg-archive.util, epg-summary.util, the epg-date helpers, EpgProgrammeDialogService, and the shared app-epg-timeline-empty-state — and drops all ribbon geometry, zoom, and horizontal scroll. It filters the loaded window to the selected day (overlap-based, matching hasProgramsForDateKey), sorts, and deduplicates via a pure buildEpgListRows (epg-list-view.utils.ts); renders each row through the dumb app-epg-list-view-row; and delegates its own vertical auto-focus + sticky "now" strip to EpgListScrollController (epg-list-scroll.controller.ts). Render states, the collapsed inline summary, the date stepper, catch-up/timeshift activation, and the details dialog behave identically to the timeline.

• One channel, preloaded window. The panel always shows a single channel. Each provider returns a multi-day window in roughly one call (M3U GET_CHANNEL_PROGRAMS; Stalker get_epg_info; Xtream get_simple_data_table), so the whole ribbon is rendered up front and day navigation is scroll within the loaded window — no per-day lazy fetch. The date stepper / "Now" jump scroll the ribbon; the day label follows the scroll position.
• Auto-focus on channel select. When a channel's EPG (re)loads or the ribbon (re)mounts, the timeline centres the currently airing programme in the viewport instantly (behavior: 'auto', no scroll animation) — selecting a channel lands on "now" without the user pressing the Now button. The jump is deduped by programme-set identity (programsFocusKey), so the 30s now-tick, zoom changes, or a host re-emitting the same data never re-jump the viewport; switching channels (or returning after viewing an empty-day channel) re-centres. The explicit "Now" button still animates (behavior: 'smooth') since it is a deliberate user action. See TimelineScrollController.maybeAutoFocus / focusCurrentProgram in epg-timeline-scroll.controller.ts.
• Controlled component. app-epg-timeline is presentation-only: it takes programs, archivePlaybackAvailable, archiveDays, activeProgram, isLivePlayback, loading, emptyReason, selectedDate, collapsed, summary and emits programActivated, returnToLive, selectedDateChange, openEpgSettings, retry, collapsedChange. The host layout owns playback, persists the collapse state (liveEpgPanelState in localStorage), and (for the M3U player) the EpgActions.setCurrentEpgProgram / setEpgAvailableFlag / setActiveEpgProgram dispatches. The timeline owns the single panel bar — collapse chevron + channel name on the left, return-to-live / jump / date stepper on the right — and the collapsed inline summary; the former app-live-epg-panel wrapper has been removed from the live layouts.
• Dynamic bar subtitle. Under the channel name the bar shows the now-playing programme title when expanded and a summary exists (.epg-timeline__subtitle) — readable title style, not the uppercase mono label. During timeshift it switches to the archive programme with a history icon and cyan accent (.is-arch). It falls back to the static sourceLabel (Timeline / Xtream / Stalker Portal) only when collapsed or when the channel has no programme.
• State-aware toolbar controls. The right-side controls are hidden (not disabled) when they cannot act, so a channel with no EPG shows a clean bar instead of dead controls: showRibbonControls() gates "Now" + zoom to the ribbon state only (nothing to jump to or zoom otherwise), and showDateStepper() keeps the date stepper for ribbon and empty-day (the only states where the channel has EPG on some day), hiding it for the no-EPG-anywhere states and while loading. Return-to-live is a playback control (!isLivePlayback()) and is independent of EPG state.
• State-driven affordances. Blocks are coloured past / now / future, with a red "now" playhead. Catch-up "Watch" appears on past blocks — and as a start-over replay button on the currently-airing block — only when archivePlaybackAvailable (Xtream tv_archive, M3U catchup-*); Stalker is schedule-only (dimmed past + a notice, no false buttons). The "i" button opens the shared app-epg-item-description dialog with a state-aware action.
• Empty / error states. emptyReason selects one of six states (loading skeleton, empty-day, channel-unmapped, provider-no-epg, m3u-needs-setup, error) via app-epg-timeline-empty-state. Icon tone is neutral for info, blue for actionable, red for errors; an action button is shown only when one really exists. The empty-state host flex: 1-fills the area below the toolbar and centres within that (compact icon/title/sub), rather than a fixed min-height that used to overflow the compact inline panel and push the icon/text — and the empty-day action buttons — below the visible edge. empty-day itself is decided by hasProgramsForDateKey, which is overlap-based (a programme counts for a day when [start, stop) intersects it, end-exclusive) — so a film that starts the previous evening and runs past midnight still keeps the ribbon on "today" while it airs, matching the sidebar (which matches by "airing now"); a start-date-only check used to drop to empty-day after midnight even though the programme was on air.
• Short-programme strategy. In a proportional ribbon a 5-minute programme would be an unreadable sliver, so buildTimelineRenderItems (epg-timeline.utils.ts) applies a layered fix: (A) a minimum block width (TIMELINE_MIN_BLOCK_WIDTH_PX); (B) width-adaptive content tiers — wide (title + time, 3-line clamp) → med (one-line ellipsis) → narrow (vertical title, no time) → micro (just a marker); (C) a hover/focus popover revealing the full title + time + description for any non-wide block (it flips above the block when the panel is near the screen bottom); (D) a px-per-minute zoom slider (tick density adapts via timelineTickStepForScale); and (E) grouping of ≥4 consecutive short (<10 min) programmes into one dashed "N short" chip when zoomed out (scale < TIMELINE_GROUP_ZOOM_MAX), expanded by clicking it. The ribbon canvas lives in the child app-epg-timeline-track; the parent owns the scroller, toolbar (incl. the zoom slider) and state.
• Panel height & titles. Block titles wrap onto as many lines as the card height allows and are clipped (not single-line ellipsis); the foot ("ON NOW" tag / "Watch") stays pinned at the bottom. With an inline player the guide is a compact panel (.epg.epg--inline → flex: 0 0 clamp(180px, 36vh, 264px) in _portal-layout.scss) so the player stays dominant; with an external player the guide keeps flex: 1 and fills the whole content area. In list mode the hosts also set .epg--list, which raises only the inline clamp (--epg-inline-height: clamp(280px, 46vh, 430px)) — vertical rows need more height than the ribbon; the timeline height is unchanged, and the collapsed 56px clamp still wins because the modifier sets just the CSS variable.
• Wide-tier description preview. When a block is the wide tier (rendered width ≥ 132px, i.e. long programmes and/or zoomed in) and the programme has a desc, a dimmed (--text-secondary) preview of the description renders under the title (.epg-timeline__block-desc). Gated to wide only, so narrower cards and the moderate default zoom stay clean; the full description still lives in the hover popover for every tier. To avoid ugly mid-line cuts, wide-tier time/title/desc use flex-shrink: 0 so flexbox can never shrink them to a fractional height: each self-clips on whole lines with an ellipsis via -webkit-line-clamp (title ≤ 2 lines, description ≤ 3) instead of being cut mid-line by the parent's overflow: hidden. At the usual inline panel height the title + 3-line preview fit without the parent clipping at all.

Playlist-Declared EPG Sources

Some M3U providers declare XMLTV sources in the playlist header instead of requiring the user to add them in Settings. The importer extracts EPG URLs from #EXTM3U header attributes x-tvg-url, url-tvg, and tvg-url in @iptvnator/shared/m3u-utils, then stores the normalized, deduplicated candidates on Playlist.detectedEpgUrls.

Playlist.epgUrls is the enabled playlist-scoped subset used for automatic import and lookup. Two additional lists preserve user edits:

• Playlist.manualEpgUrls stores URLs the user explicitly added for this playlist, including detected catalog URLs the user manually enabled.

• Playlist.disabledEpgUrls stores detected URLs the user removed from this playlist so playlist refreshes do not silently re-enable them.

• Up to five detected URLs are enabled automatically.

• Larger header lists are treated as provider catalogs. The importer keeps all candidates in detectedEpgUrls, but auto-enables only recommended URLs whose guides/<country> path matches playlist hints such as tvg-country or the country suffix in tvg-id (channel.ua). Language hints are used only when no country hints are present. If no recommendation can be made, the importer falls back to the first five detected URLs so generic provider catalogs still produce usable local EPG sources instead of silently enabling none.

• Recommendations are capped so a malformed or global provider list cannot start dozens of XMLTV downloads during playlist import.

These URLs are playlist-scoped by default:

• libs/m3u-state auto-fetches enabled epgUrls when M3U playlists are loaded, added, or refreshed, using the same EPG progress/import pipeline as Settings-managed XMLTV URLs. Before fetching, playlist URLs already present in global Settings are filtered out so the same XMLTV URL is not downloaded twice. Within a running session, the effect remembers the last fetchable URL set per playlist and only re-fetches when that URL set changes; metadata-only edits such as renaming a playlist or hiding groups do not re-download local EPG sources. When the local URL set expands, only newly added fetchable URLs are downloaded; disabling or removing one source does not re-download the remaining sources. Explicit playlist refreshes bypass that session fetch key and re-download the current fetchable local EPG URLs. Partial metadata updates that omit epgUrls preserve the previous fetch key, while an explicit empty epgUrls list clears it. Add/update metadata effects trigger playlist-local EPG fetches only after the playlist persistence call succeeds, and metadata updates that do not include any EPG source fields do not evaluate the fetch plan.
• The Electron EPG database stores source_url on imported programs so current program lookups can ask for the active playlist's EPG sources first. Existing databases backfill this column from epg_channels.source_url once, in bounded batches, after the scoped indexes are created. When multiple EPG files reuse the same XMLTV channel id, the channel row keeps its original source_url attribution instead of being overwritten by the last imported source; program scoping remains source-specific through epg_programs.source_url.
• ChannelListContainerComponent enables EPG rows when either global settings URLs or the active M3U playlist has epgUrls. EPG availability refreshes are debounced so several playlist-local XMLTV imports completing close together coalesce into one visible-channel EPG refresh. The visible channel list also refreshes when the effective EPG source context changes, so a playlist whose epgUrls arrive after the channels are rendered does not wait for the next periodic refresh before showing current programs. A successful EPG import clears current-program lookup caches before publishing availability, so an early "no current program" lookup cannot mask freshly imported rows until the TTL expires.
• Scoped lookups fall back only to Settings-managed EPG URLs for channels missing from the playlist-declared source. Playlist-local sources from other playlists are not treated as global fallback sources. Single-channel current program lookups include the source URL set in their cache and in-flight keys, so playlist-local and global lookups deduplicate without reusing the wrong source scope. Batch current-program lookups use the same source-scoped per-channel TTL cache and order-insensitive in-flight batch deduplication before reaching IPC; missing exact channel-id matches are resolved with batched id/display-name candidate queries rather than a per-channel fallback loop. Those candidate queries match the raw key case-sensitively as well as via LOWER(): SQLite's LOWER()/COLLATE NOCASE only fold ASCII, so for non-ASCII names (Cyrillic, Greek, …) a LOWER()-only match would miss channels whose M3U name and EPG display_name share the same casing — the raw exact match keeps parity with the timeline's single-channel exact-display-name lookup, and the JS resolveChannelMetadataCandidate then folds with full-Unicode toLowerCase(). The "airing now" window is compared with timezone-aware SQLite datetime() on both sides (EpgQueryService.isAiringAt), not raw string comparison: stored EPG timestamps often carry an offset (e.g. +03:00) while now is built as UTC (…Z), so a lexical compare would be wrong by the offset and surface a stale (or no) current programme. After the scoped + legacy candidate queries, any candidate that resolved by id/display-name but still has no in-scope current programme is retried once unscoped (all sources), mirroring the timeline's own unscoped getChannelPrograms lookup. This keeps the channel-list "now" line consistent with the timeline when a channel's row and its programmes carry different source_url values (shared XMLTV ids across multiple imports), where the channel resolves in scope but its programmes are tagged with a source that is not currently enabled. When upgrading an existing database whose historical programs have no source_url, scoped program and metadata queries try those legacy unscoped rows only after the requested source scope returns no result, so old EPG data remains visible without taking precedence over freshly imported scoped data. Channel metadata lookups use the same playlist-first, Settings-managed fallback strategy so icons and display names can still come from global EPG sources when the playlist-local guide only supplies programs. If multiple EPG sources reuse the same XMLTV channel id, channel metadata and display-name fallback lookups treat a channel as source-scoped when either the channel row itself or matching programs are tagged with the requested source_url.
• The playlist details dialog shows enabled EPG URLs with explicit actions to refresh, remove, or add a source to global Settings. It also allows adding one or more manual playlist-local sources and indicates when additional detected candidates were not auto-enabled. Removing a playlist-local source also clears programs tagged with that source_url and prunes only orphaned channel rows for that same source before saving the playlist metadata change, so a failed cleanup keeps the source enabled and visible. Shared XMLTV channel ids from other sources are preserved. Detected playlist sources are not silently promoted to global settings.

Performance Optimizations

Optimization	Implementation
Virtual Scroll	CDK virtual scroll for 90,000+ channels
Computed Signals	enrichedChannels computed signal replaces template pipe
Debounced Search	300ms debounce on search input
Global Progress Tick	Single 30s interval instead of per-item intervals
OnPush Change Detection	All components use OnPush
Infinite Scroll in Groups	IntersectionObserver loads 50 channels at a time
Memoized Group Enrichment	enrichedGroupChannelsMap computed signal

Tab Components

AllChannelsViewComponent

• Inputs: channels, channelEpgMap, channelIconMap, progressTick, shouldShowEpg, itemSize, activeChannelUrl, favoriteIds
• Outputs: channelSelected, favoriteToggled
• Features: Workspace search, persisted channel sorting, virtual scrolling, no-results placeholder

GroupsViewComponent

• Inputs: Same as AllChannelsTab + groupedChannels
• Outputs: channelSelected, favoriteToggled
• Features: Resizable groups rail, local group search, group visibility management, persisted selected-group channel sorting

FavoritesViewComponent

• Inputs: favorites, channelEpgMap, channelIconMap, progressTick, shouldShowEpg, activeChannelUrl
• Outputs: channelSelected, favoriteToggled, favoritesReordered
• Features: Drag-and-drop reordering with CDK DragDrop, read-only channel details context menu

RecentViewComponent

• Inputs: recent channels, channelEpgMap, channelIconMap, progressTick, shouldShowEpg, activeChannelUrl
• Outputs: channelSelected, favoriteToggled, recentItemRemoved
• Features: Read-only channel details context menu, row-level and context-menu removal

EPG Integration

EpgService (@iptvnator/epg/data-access)

class EpgService {
    // Fetch EPG for multiple URLs
    fetchEpg(urls: string[]): void;

    // Get programs for a channel
    getChannelPrograms(channelId: string): void;

    // Batch fetch current programs
    getCurrentProgramsForChannels(
        channelIds: string[],
        options?: { sourceUrls?: string[] }
    ): Observable<Map<string, EpgProgram>>;

    // Batch fetch XMLTV channel metadata for logo fallback
    getChannelMetadataForChannels(
        channelIds: string[],
        options?: { sourceUrls?: string[] }
    ): Observable<Map<string, EpgChannelMetadata | null>>;

    // Observables
    epgAvailable$: Observable<boolean>;
    currentEpgPrograms$: Observable<EpgProgram[]>;
}

EPG Components

Component	Purpose
EpgTimelineComponent	Horizontal timeline for one channel
EpgListViewComponent	Vertical single-day list alternative
EpgItemDescriptionComponent	Program details dialog
MultiEpgContainerComponent	Grid view of all channels' schedules

Video Player

Location: libs/playlist/m3u/feature-player/src/lib/video-player/

Supported Players

• ArtPlayer (default) - Modern player with plugins
• Video.js - Fallback with HLS support
• HTML5 - Basic video element
• Audio - For radio streams

Player Features

• Channel navigation (prev/next)
• Favorites toggle
• EPG sidebar
• Collapsible inline EPG panel for internal players, persisted through the shared live-epg-panel-state preference
• Multi-EPG modal view
• Channel info overlay
• External player support (MPV, VLC) in Electron
• M3U archive/catch-up playback for supported replay schemes

Archive / Catch-Up Playback

• The shared EPG UI only shows the archive replay badge when the host confirms that the selected M3U channel has a playable replay scheme. Archive days alone are not enough.
• M3U catch-up support is resolved in @iptvnator/shared/m3u-utils from channel metadata and the archived program start time.
• Supported replay precedence:
  1. catchup.source if it is an HTTP(S) URL. IPTVNator rewrites or appends standard utc and lutc query params on that URL.
  2. Legacy same-stream shift playback when catchup.type === 'shift'. In that case IPTVNator rewrites or appends utc and lutc on channel.url.
  3. Legacy same-stream shift fallback when no explicit catch-up mode is declared, archive-day metadata exists (tvg.rec, timeshift, or catchup.days), and channel.url itself is an HTTP(S) stream URL. This covers providers that only advertise archive retention such as tvg-rec="7" but still expect standard utc and lutc query params on the live URL.
• tvg.rec, timeshift, and catchup.days still define the archive window shown in the EPG, but replay remains unavailable when the provider declares a different explicit catch-up scheme that IPTVNator does not understand or when the stream URL itself is not an HTTP(S) replay target.
• Active replay is stored separately from the selected channel in playlistState.activePlaybackUrl. Inline and external players use activePlaybackUrl ?? activeChannel.url, and returning to live playback clears the override.
• The unified favorites/recent live tab (libs/portal/shared/ui/.../unified-collection/unified-live-tab.component.ts) hosts the same timeline but does not use the NgRx playlist state; it keeps its own activeTimeshift signal, resolves the replay URL with resolveM3uCatchupUrl, and swaps the inline player's playback target (or hands the URL to the configured external player). Selecting another channel, closing the player, or "Return to live" clears the override.
• Catch-up activation is never silent: if the replay URL cannot be resolved for a programme the user clicked, both hosts surface a EPG.TIMELINE.CATCHUP_FAILED snackbar instead of doing nothing.

Interfaces

Channel Interface

interface Channel {
    id: string;
    url: string;
    name: string;
    group: { title: string };
    tvg: {
        id: string; // For EPG matching
        name: string;
        url: string;
        logo: string;
        rec: string;
    };
    epgParams?: string;
    timeshift?: string;
    catchup?: { type?: string; source?: string; days?: string };
    radio: string;
    http: {
        referrer: string;
        'user-agent': string;
        origin: string;
    };
}

Playlist State Additions

interface PlaylistState {
    active: Channel | undefined;
    activePlaybackUrl: string | null;
    currentEpgProgram: EpgProgram | undefined;
    epgAvailable: boolean;
    channels: Channel[];
}

EpgProgram Interface

interface EpgProgram {
    start: string; // ISO string
    stop: string; // ISO string
    channel: string; // TVG ID
    title: string;
    desc: string | null;
    category: string | null;
    episodeNum?: string | null;
    iconUrl?: string | null;
    rating?: string | null;
}

Routes

/playlists/:id          # Video player with playlist
/iptv                   # Default IPTV route

Adding New Features

To add a new tab to channel list:

1. Create component in channel-list-container/new-tab/
2. Accept inputs: channels, channelEpgMap, progressTick, shouldShowEpg, activeChannelUrl
3. Emit channelSelected output
4. Add to parent template and imports

To add EPG-related features:

1. Use EpgService for data fetching
2. Subscribe to channelEpgMap signal for current programs
3. Dispatch EpgActions for state updates

To modify favorites behavior:

1. Dispatch FavoritesActions.updateFavorites for toggle
2. Dispatch FavoritesActions.setFavorites for reordering
3. Effects automatically persist to database