Skip to content

Master prompt · IPTV player

The master prompt for a world-class IPTV player.

A complete, structured brief for Windows, macOS, iOS and Android. It specifies every feature in detail, sets measurable quality targets and makes your AI or developer reason through cross-platform architecture before writing a single line of code.

Read it first
Structured sections
25
Words, about 44 min to read
10,096
Platforms covered
4
Playlist source types
6

Specified for

  • Windows
  • macOS
  • iOS and iPadOS
  • Android and Android TV

What it covers

Every requirement, specified down to the detail.

Each area below is a full section of the prompt with concrete behaviour, platform notes and measurable targets. Select a card to jump straight to it.

Before any code

Cross-platform reasoning comes first

The prompt makes your AI or developer analyse every compatibility challenge across Windows, macOS, iOS and Android, score the main framework options and record each decision, so the architecture stays maintainable as it grows.

Compatibility challenges to analyse
16
Architectures to compare
7
Weighted decision criteria
8

How to use it

From copy to a reviewed plan in three steps.

The prompt is built to produce a careful plan first and code second, so you stay in control of every decision.

  1. Copy or download it

    Use Copy full prompt, or download the Markdown file. Headings, lists, tables and the interface sketch arrive intact when you paste.

  2. Hand it to your AI or your developer

    Paste it as the first message of a new conversation with a capable AI coding assistant, or send it to a development team or agency as the project brief.

  3. Review the plan, then build in phases

    It asks for assumptions, questions, a framework comparison and an architecture first, then pauses for your review before every phase.

Tips for the best results

  • Adjust the proposed minimum OS versions, launch languages and phase scope to your audience before you send it.
  • Answer the clarifying questions it asks. Your answers change the architecture it recommends.
  • With an AI assistant, ask for one phase at a time and keep the decision records it writes.
  • Refining one area? Copy just that section with the button next to its title.

The prompt

Read it, adjust it, then copy it.

Everything below is the exact text you copy or download. Jump between sections with the contents list, or copy a single section with the button beside its title.

Contents25 sections
  1. 01Your role and mission
  2. 02How to reason and respond
  3. 03Product scope and legal boundaries
  4. 04Target platforms and devices
  5. 05Cross-platform challenges to reason through
  6. 06Architecture and framework evaluation
  7. 07User interface and experience
  8. 08Streaming protocols and playback
  9. 09Playlist and source management
  10. 10Electronic Program Guide (EPG)
  11. 11Languages and localization
  12. 12User profiles
  13. 13Parental controls
  14. 14Recording, timeshift and playback
  15. 15Search, filters and categories
  16. 16Notifications
  17. 17Performance and optimization
  18. 18Offline mode
  19. 19Security and privacy
  20. 20Casting and integrations
  21. 21Updates, releases and maintenance
  22. 22Data model and storage
  23. 23Testing and quality
  24. 24Delivery plan and phases
  25. 25Your first response
iptv-player-master-prompt.md

Master prompt: an advanced cross-platform IPTV player for Windows, macOS, iOS and Android

Read this entire brief before you respond. It is written for an AI coding assistant or a software team, and it defines what to build, the quality bar, the constraints of each platform and the order of delivery. Where it suggests a technology, treat that as a hypothesis to test, not a decision already made. If any requirement conflicts with platform rules, store policies or the law, say so and propose a compliant alternative.

01

Your role and mission

Act as a principal cross-platform architect and lead engineer with deep, hands-on experience in video streaming, native media frameworks and consumer apps on Windows, macOS, iOS, iPadOS and Android (phones, tablets, Android TV and Google TV). Think equally like a product designer, a QA lead, a security engineer and a release manager.

Your mission is to design, plan and then build a highly advanced, feature-rich IPTV player, called "the Player" in this brief. It runs on Windows desktop, macOS, iOS and iPadOS, and Android, and plays live TV, catch-up, movies and series from sources the user adds. It must feel native, fast and dependable on every platform.

The Player is successful when it:

  • Plays the real-world mix of IPTV streams (HLS, MPEG-DASH, MPEG-TS, RTMP and more) with fast channel changes and minimal buffering.
  • Handles very large catalogues (100,000+ channels and millions of guide entries) without freezing or crashing.
  • Shares as much code as possible without compromising playback quality or the look and feel of each platform.
  • Is secure, private, accessible, localized and maintainable for many years.
02

How to reason and respond

Work like a senior engineer preparing for a design review. Before writing implementation code:

  1. Restate the goal in your own words and list your assumptions.
  2. Ask up to 10 clarifying questions whose answers would materially change the architecture (team skills, budget, monetization, whether a backend is allowed, priority platforms, DRM needs, target markets). If you cannot wait for answers, state the assumption you will proceed with for each question.
  3. Reason explicitly through every cross-platform challenge in section 5. For each one, explain how it shows up on each platform, the options, your recommended mitigation and where it is isolated in the architecture.
  4. Compare the architecture and framework options in section 6 with a weighted decision matrix. Justify your recommendation with evidence rather than habit, and name the risks of your choice.
  5. Record every major decision as an Architecture Decision Record: context, options considered, decision and consequences.
  6. Prove the riskiest assumptions first with a playback spike on all four platforms before building features.
  7. Deliver in the phases described in section 24 and stop for review at the end of each phase.

Quality rules for everything you produce:

  • Be specific. Name APIs, libraries, OS versions and limits. Flag anything that may have changed since your knowledge cutoff and explain how to verify it.
  • Never invent library APIs or capabilities. If you are unsure whether a library supports something on a platform, say so and propose a spike to find out.
  • Write production-quality code: strongly typed, tested, documented where the intent is not obvious and with real error handling. Never present placeholder stubs as finished work, and never put secrets in code.
  • Prefer mature, well-maintained dependencies with clear licenses, and check every license against app store distribution.
  • Use Mermaid for diagrams and tables for comparisons. Keep explanations concise and easy to scan.
03

Product scope and legal boundaries

Who it is for
  • Viewers who already have legitimate access to IPTV streams: paid subscriptions, operator IPTV, official broadcaster streams or their own media servers.
  • Households where several people share one device, including children.
  • Power users who manage several providers, very large playlists and external guide sources.
The Player is a neutral player
  • It ships with no channels, playlists or provider recommendations, links to no unlicensed content and never advertises free channels.
  • Users add their own sources. Onboarding, screenshots, store listings and marketing use only content you have the right to show: your own test streams, public test vectors or licensed demo content.
  • Never implement DRM circumvention, ripping of protected streams, or ways to get around provider limits such as maximum connections.
  • Prepare a reviewer demo source with legal content for Apple, Google and Microsoft store reviews, because IPTV players receive extra scrutiny under app store intellectual property rules.
In scope

Everything in sections 7 to 22: interface, playback and protocols, sources, guide, localization, profiles, parental controls, recording and timeshift, search, notifications, performance, offline mode, security, casting and integrations, updates and the data model.

Out of scope for the first release, unless the client asks
  • Selling or bundling content, a provider marketplace, or server-side transcoding.
  • Social features and user-generated content.
  • TV platforms other than Android TV. Design the architecture so that Apple TV (tvOS), Fire TV, Samsung Tizen, LG webOS, Linux desktop and the web can be added later without rewriting the core.
04

Target platforms and devices

Platform Proposed minimum Form factors and input
Windows Windows 11 on x64 and ARM64. Add Windows 10 22H2 only if your audience data justifies it, because it is past the end of support Resizable windows, multiple monitors, fullscreen, touch screens, keyboard, mouse and gamepads
macOS macOS 14 Sonoma or later, as a universal build for Apple silicon and Intel Multiple windows, menu bar commands, keyboard shortcuts and trackpad gestures
iOS and iPadOS iOS and iPadOS 17 or later iPhone in portrait and landscape, iPad split view and Stage Manager, external displays
Android Android 8.0 (API 26) or later, targeting the API level Google Play currently requires Phones, tablets, foldables, Chromebooks, Android TV and Google TV with D-pad remotes
  • Validate these minimums against current OS adoption data and the minimum versions your chosen framework and libraries support before you commit to them.
  • Define a reference device list for testing that runs from low-end Android TV boxes with 1 to 2 GB of RAM to current flagship phones, tablets and computers.
05

Cross-platform challenges to reason through

Analyse each challenge below. For every one, describe how it shows up on Windows, macOS, iOS and iPadOS, and Android (including Android TV), the options available, your recommended mitigation and which architectural boundary isolates it. Start with a summary table, then go into detail.

  1. Playback engine fragmentation. Native engines differ widely. AVPlayer on Apple platforms plays HLS and progressive MP4 but not MPEG-DASH, RTMP or continuous MPEG-TS over HTTP or UDP. Media3 ExoPlayer on Android covers HLS, DASH, RTSP and progressive TS, with RTMP through an extension. Windows Media Foundation handles HLS and DASH through its adaptive streaming APIs but has codec gaps (HEVC needs an optional system extension on many PCs). FFmpeg-based engines such as libmpv and libVLC play almost anything, but cannot play DRM content and integrate less smoothly with AirPlay, Picture in Picture and system media controls.
  2. Codec and audio coverage. MPEG-2 video and MP2 audio from broadcast-derived IPTV, interlaced video that needs deinterlacing, AC-3 and E-AC-3 support that varies by device, HEVC 10-bit and HDR, and AV1 hardware decoding only on recent chips. Decide when to pass surround audio through and when to decode it.
  3. Rendering and UI integration. Embedding a native video surface in a cross-platform UI (texture versus platform view composition), overlay controls, subtitle rendering, HDR output, frame-rate matching on TVs and several simultaneous video views.
  4. Background execution. iOS suspends apps shortly after they leave the foreground. Android applies Doze, App Standby, foreground service type rules and exact alarm permissions. Desktop apps can be closed and computers can sleep. This affects recordings, reminders, guide refresh and downloads. Design what is possible on each platform and be honest in the interface where it is not.
  5. Networking policies. App Transport Security on Apple platforms and cleartext rules on Android versus providers that only offer plain HTTP; local network privacy prompts on iOS and macOS; the multicast networking entitlement Apple requires for UDP multicast and SSDP discovery; multicast locks on Android; IPv6, proxies, VPNs and captive portals; and custom HTTP headers that some providers require.
  6. Storage and file access. App sandboxes and Android scoped storage, where recordings and downloads live, user-visible folders (the Files app on iOS, the Storage Access Framework on Android, any folder on desktop), external drives, quotas and cleanup.
  7. Input paradigms. Touch, mouse and keyboard, D-pad remotes and game controllers. Focus management for a 10-foot interface must be designed from the start, not retrofitted.
  8. Platform conventions. Menus and shortcuts on macOS, windowing and title bars on Windows, navigation and gestures on iOS, Material Design, predictive back and edge-to-edge on Android, multi-window on iPad and Android, and Picture in Picture everywhere.
  9. Secure storage. Keychain, Android Keystore and Windows Credential Locker or DPAPI behave differently, including during backup, restore and device migration.
  10. Notifications and permissions. Different permission models and request timing (the Android 13+ runtime permission, iOS authorization, Windows and macOS notification settings) and different guarantees about exact delivery times.
  11. Casting ecosystems. The Google Cast SDK supports Android, iOS and Chrome but not native desktop apps, AirPlay is Apple-only, and DLNA discovery needs multicast. Receivers fetch streams themselves, so custom headers, credentials in URLs and raw TS streams need special handling.
  12. Store policies and review. The rules of the App Store, Google Play, the Microsoft Store and the Mac App Store on IPTV apps, in-app purchases, background modes and entitlements; and distribution outside the stores, including code signing, notarization and Google's developer verification requirements for Android apps installed outside Google Play.
  13. Licensing. LGPL and GPL obligations of FFmpeg, libVLC and libmpv, especially for iOS and Mac App Store distribution, and codec patent considerations when shipping your own decoders instead of the operating system's. Include a legal review checkpoint.
  14. Low-end hardware. Inexpensive Android TV boxes with weak CPUs and 1 to 2 GB of RAM, older iPhones and Windows laptops with integrated graphics. Large datasets must never be processed on the UI thread.
  15. Time and locale. Guide data in many time zones, daylight saving transitions, provider clock offsets, 12 and 24-hour formats and right-to-left layouts.
  16. Build, signing and testing. Apple builds need macOS, there are four different signing systems, and the device and stream test matrix is large.
06

Architecture and framework evaluation

Options to evaluate

Evaluate at least these options, score them with a weighted matrix and recommend one:

  • A. Flutter for the UI on all four platforms, with a playback layer that routes to native engines (Media3 on Android, AVFoundation on Apple platforms) and to an FFmpeg-based engine (for example media_kit with libmpv) for everything else, including most streams on Windows.
  • B. Kotlin Multiplatform for a shared core (networking, parsing, database and business logic) with Compose Multiplatform for the UI, or SwiftUI on Apple platforms, and native players behind expect/actual interfaces.
  • C. Native UI per platform (SwiftUI with AppKit and UIKit, Jetpack Compose, WinUI 3) over a shared core written in Rust, with bindings generated by a tool such as UniFFI, or in C++.
  • D. .NET MAUI or Avalonia with LibVLCSharp.
  • E. React Native with the Windows and macOS extensions and a native video module.
  • F. Qt 6 with QML and an FFmpeg-based or libVLC-based player.
  • G. A web-technology shell (Tauri, Electron or Capacitor) with hls.js, dash.js and mpegts.js, as a control option. Account for browser codec limits (AC-3, MPEG-2, raw TS), battery cost and the lack of a native feel.
Decision criteria

Use these suggested weights, adjust them if you can justify it, and show your scoring:

Criterion Weight
Playback quality and protocol and codec coverage 20%
Access to native capabilities: hardware decoding, PiP, AirPlay, Cast, background work and DRM 15%
UI fidelity and performance on each platform, including the 10-foot TV interface 15%
Code sharing and team velocity 15%
Maintainability, ecosystem maturity and long-term support 10%
Performance and memory use on low-end devices 10%
Store compliance and licensing risk 10%
Hiring and team skills 5%
Starting hypothesis to test

A layered architecture with a shared, platform-agnostic core and a pluggable playback layer:

  1. Presentation: screens, navigation, the design system and input and focus handling. Shared where the framework allows, with platform-specific shells for desktop windowing, TV focus and mobile gestures.
  2. Application: use cases such as AddSource, RefreshSource, ZapToChannel, ScheduleRecording, SetReminder and SearchCatalog, plus state management and view models.
  3. Domain: pure models and rules (Channel, Programme, Profile, ParentalRule, StreamDescriptor) with no platform imports.
  4. Data: repositories, source providers (M3U, Xtream Codes, Stalker, JSON and XML), guide ingestion, the database, caching and sync.
  5. Platform adapters: playback engines, secure storage, notifications, background scheduling, the file system, casting, networking and system media controls.
Key interfaces

Adapt this pseudocode to the language you choose:

PlaybackEngine
  id, capabilities(): EngineCapabilities
  supportLevel(stream: StreamDescriptor): Native | Fallback | Unsupported
  prepare(stream, options), play(), pause(), seekTo(positionMs), stop(), release()
  selectAudioTrack(id), selectSubtitleTrack(id or none), setQuality(auto or renditionId)
  events: stream of PlaybackEvent (state, buffering, tracks, stats, error)

EngineSelector
  choose(stream, context): PlaybackEngine
  Prefers the native engine for DRM, AirPlay, PiP and battery life.
  Uses the FFmpeg-based engine for formats the native engine cannot play.
  Falls back automatically on unsupported-format errors and remembers what worked per channel.

SourceProvider
  type: m3u | xtream | stalker | json | xml
  validate(config): AccountInfo or a typed error
  fetchCatalog(config): async stream of CatalogChunk (streamed, never fully in memory)
  fetchGuide(config, window): async stream of GuideChunk
  resolveStream(item, options): StreamDescriptor
  resolveCatchup(channel, programme): StreamDescriptor or none

StreamDescriptor
  urls (primary and backups), protocolHint, containerHint, isLive
  httpHeaders (User-Agent, Referer, cookies, authorization)
  drm (scheme, licenseUrl, headers) or none
  catchup (mode, template, days) or none
  preferredEngine or none
Architecture requirements
  • Offline-first: the UI reads from the local database, and network refreshes update it in the background.
  • Stable identity: channels, movies and episodes keep stable ids across playlist refreshes (for example, derived from the source id plus the provider's stream id, or from the tvg-id plus a normalized name). Favorites, history, reminders, recordings and parental locks must survive refreshes and URL changes.
  • Clear boundaries: dependency injection and feature modules, and no feature imports another feature's internals.
  • Responsiveness: everything long-running is cancellable and runs off the UI thread.
  • Operability: feature flags and remote configuration for staged rollouts and kill switches.
  • Scalability: the design scales with data volume (100,000+ channels and millions of programmes), with features (stable extension points for sources, playback engines and integrations), with platforms (tvOS, Fire TV, Tizen and webOS later) and with team size (clear module ownership and independent testing).
  • Maintainability: one code style enforced by linters and formatters, documented public interfaces, decision records and test coverage targets (for example 80% for the domain and data layers).
  • Code sharing: aim for at least 70% shared code across the domain, data and application layers, and justify every platform-specific module.
  • Diagrams to provide: a C4 context and container diagram, a module dependency diagram, the playback engine selection flow, the source refresh and guide ingestion pipeline, and an entity relationship diagram.
07

User interface and experience

Design principles
  • Content first: video and the guide are the heroes. Controls appear when needed and get out of the way.
  • Instant by default: show cached data immediately and never block the interface on the network.
  • Native on each platform: one shared design language, with each platform's own conventions for navigation, menus, gestures, windows and system integration.
  • One design system: tokens for color, typography, spacing, radius, elevation and motion. A dark theme by default for dim rooms, plus light and high-contrast themes and a user-selectable accent color.
Adaptive layouts
  • Compact (phones): bottom navigation, a full-screen player and gesture controls.
  • Medium (tablets, foldables and small windows): a navigation rail, list and detail layouts, and a live preview in the channel list.
  • Expanded (desktop and large tablets): sidebar navigation, resizable panes, the player, channel list and guide visible together, and keyboard-first operation.
  • 10-foot (Android TV and future TV platforms): focus-driven navigation, large type, overscan-safe margins and nothing that depends on hover.
  • Choose layouts by window size class, not device type, and reflow live when a desktop window or iPad split view is resized.
Key screens

Every screen needs designed loading, empty, error and offline states.

  1. Onboarding and add source: pick M3U URL, M3U file, Xtream Codes, Stalker portal, JSON or XML, and validate with clear, actionable errors. On TV, offer "add from your phone" with a QR code or pairing code so nobody types long URLs with a remote.
  2. Home: continue watching, favorite channels with now and next, recently watched, upcoming reminders, recordings and downloads.
  3. Live TV: groups, a channel list with logos, numbers, now and next and progress bars, a live preview on large screens and quick filters.
  4. Guide: the timeline grid described in section 10.
  5. Movies and series: poster grids, detail pages (synopsis, cast and rating), seasons and episodes, resume and next episode.
  6. Player: an auto-hiding overlay with channel and programme info, progress for catch-up and VOD, track and quality menus, mini-guide and channel list overlays, record and reminder actions, cast and PiP buttons, and a control lock on mobile.
  7. Search: unified results as described in section 15.
  8. Recordings and downloads: lists with status, size and actions.
  9. Profiles: "Who's watching", the profile editor and kids profiles.
  10. Settings: sources, guide, playback, parental controls, appearance, language, notifications, storage, backup and restore, diagnostics, and about with open-source licenses.
Input and interaction
  • Touch: tap to show controls; swipe up or down on the video to change channel; swipe sideways to seek in VOD, catch-up and timeshift; vertical swipes on the screen edges for brightness and volume; pinch to change the aspect ratio; double-tap to skip; long-press for context actions; and haptic feedback.
  • Mouse and keyboard: hover previews, right-click context menus, drag and drop for playlist files and reordering, complete keyboard shortcuts (Space to play or pause, F for fullscreen, M to mute, arrow keys to seek and change volume, Page Up and Page Down to change channel, number keys for direct channel entry, G for the guide, Ctrl or Cmd plus F to search), a shortcut cheat sheet and media keys.
  • Remotes and controllers: full D-pad navigation with a clearly visible focus state, predictable focus restoration, number entry, channel up and down keys, long-press menus, and a Back button that never exits playback unexpectedly.
  • System integration: lock screen and system media controls, Picture in Picture, Android predictive back and edge-to-edge, iPad multitasking, macOS menu bar commands, Windows snap layouts, and deep links to channels and programmes.
Accessibility

Target the equivalent of WCAG 2.2 AA on every platform:

  • Screen readers (VoiceOver, TalkBack and Narrator) with meaningful labels on every control, including channel logos, and announcements for important state changes.
  • Text scaling (Dynamic Type, Android font scale and Windows text size) without clipping, reduced motion support, high contrast, and never color alone to signal live, recording or locked states.
  • Touch targets of at least 44 by 44 points on Apple platforms and 48 by 48 dp on Android, and full keyboard operation on desktop.
  • Customizable captions and subtitles as described in section 14.

Deliver a design system specification (tokens and components), layout descriptions or wireframes for each key screen in every size class, and focus maps for the TV interface.

08

Streaming protocols and playback

Protocols and formats
Protocol or format Requirements
HLS Live, event and VOD playlists; TS and fMP4/CMAF segments; Low-Latency HLS where the engine supports it; alternate audio and subtitle renditions; AES-128 and SAMPLE-AES; WebVTT and CEA-608/708 captions; discontinuities
MPEG-DASH Static and dynamic manifests; multi-period; SegmentTemplate, SegmentTimeline and SegmentBase; live time-shift buffers; low-latency DASH where supported; ClearKey, and Widevine or PlayReady through native engines
MPEG-TS Continuous TS over HTTP and HTTPS; UDP and RTP multicast and unicast; program selection in multi-program streams; DVB subtitles and teletext
RTMP and RTMPS Live playback through the FFmpeg-based engine, or the Media3 RTMP data source on Android
Also RTSP; progressive MP4, MKV, MOV and AVI for VOD; audio-only HLS and Icecast or SHOUTcast for radio channels; SRT as an optional extension
Codecs
  • Video: H.264/AVC, H.265/HEVC (8-bit and 10-bit, HDR10 and HLG, and Dolby Vision where the platform supports it), MPEG-2, AV1 and VP9.
  • Audio: AAC-LC, HE-AAC v1 and v2, MP3, MP2, AC-3, E-AC-3 (with Dolby Atmos passthrough where the hardware allows), Opus and FLAC.
  • Subtitles: WebVTT, SRT, TTML/IMSC, SSA/ASS for VOD, CEA-608/708, DVB bitmap subtitles and teletext subtitles.
  • Use hardware decoding first (MediaCodec, VideoToolbox and D3D11VA) with automatic, logged software fallback, plus a per-channel setting to force software decoding.
  • Deinterlace interlaced broadcasts automatically, with a manual override.
  • Pass audio through to AV receivers where the platform allows, with a downmix fallback and an optional night mode that compresses dynamic range.
Playback engine strategy

Implement the PlaybackEngine abstraction from section 6:

  • Android: Media3 ExoPlayer as the primary engine (HLS, DASH, RTSP, TS and the RTMP extension), with the FFmpeg audio decoder extension, built from source, for AC-3, E-AC-3 and MP2 on devices without those decoders. Add an FFmpeg-based engine as a fallback.
  • iOS, iPadOS and macOS: AVPlayer as the primary engine for HLS and MP4, for the best battery life, AirPlay, Picture in Picture and FairPlay. Use an FFmpeg-based engine for raw TS, DASH, RTMP, UDP, MPEG-2 and unsupported audio. When a provider offers both TS and HLS outputs, as Xtream Codes servers usually do, prefer HLS on Apple platforms.
  • Windows: evaluate Media Foundation (adaptive streaming and PlayReady) against libmpv and libVLC. Most IPTV content will need the FFmpeg-based engine, so make sure D3D11 hardware decoding and HDR output work correctly.
  • Probe each device's capabilities at first launch (available decoders, HDR support and maximum resolution), cache the results and feed them to the EngineSelector.
  • If the chosen engine fails with an unsupported-format error, retry with the next engine within the same channel change and remember the engine that worked for that channel.
  • Allow per-channel overrides for the engine, User-Agent, Referer, deinterlacing, aspect ratio and audio delay.
Adaptive bitrate and quality
  • Automatic quality by default, based on bandwidth estimates and buffer health, plus manual selection from the available renditions.
  • Cap quality by player size, data saver mode, cellular networks and battery saver.
  • Start conservatively and ramp up quickly. Target a time to first frame under 1.5 seconds at the median on a 20 Mbps connection for HLS and TS channels.
  • Configure buffers per content type: small for live zapping and larger for VOD. Offer a live edge offset setting, and catch up to the live edge with gentle playback speed changes where the engine supports it.
Network resilience
  • Send per-source and per-channel HTTP headers (User-Agent, Referer, Origin, cookies and authorization), and honour M3U hints such as #EXTVLCOPT:http-user-agent, #EXTVLCOPT:http-referrer, #EXTHTTP and #KODIPROP.
  • Follow redirects, including the HTTPS to HTTP redirects some providers use (with a visible warning); apply timeouts and exponential backoff with jitter; reconnect silently when a stream stalls; and fail over to backup URLs.
  • Show clear, specific errors such as "The provider rejected the login", "Maximum connections reached", "This channel is offline" and "This format is not supported on this device".
  • Never open more simultaneous connections than the account allows, counting live viewing, recordings, previews and multi-view.
Zapping and stream information
  • Fast channel changes, with optional pre-buffering of the next and previous channel only when the account's connection limit allows it.
  • A last-channel toggle and zap history.
  • A stream information overlay: codec, resolution, frame rate, bitrate, buffer level, dropped frames and the active engine.
09

Playlist and source management

Supported source types
  1. M3U and M3U8, from a URL or a local file
    • Parse the #EXTM3U header attributes: url-tvg and x-tvg-url, tvg-shift, catchup, catchup-days and catchup-source.
    • Parse #EXTINF durations and attributes: tvg-id, tvg-name, tvg-logo, tvg-chno, tvg-language, tvg-country, tvg-shift, group-title, radio, catchup, catchup-days, catchup-source and timeshift. Keep unknown attributes rather than dropping them.
    • Support #EXTGRP, #EXTVLCOPT, #EXTHTTP, #KODIPROP and several URLs per channel.
    • Be tolerant of real-world files: UTF-8 with or without a byte order mark, Windows-1252 and Latin-1 fallbacks, mixed line endings, missing quotes, duplicate attributes, blank lines, very long lines and gzip-compressed responses.
    • Parse as a stream in a background worker. Handle 100,000+ entries and files over 50 MB without loading everything into memory.
    • Classify entries as live, movie, series or radio using attributes, URL patterns, file extensions and group names, and let the user correct the result.
  2. Xtream Codes API (server URL, username and password)
    • Authenticate through player_api.php and show the account status, expiry date, active and maximum connections, allowed output formats and server time zone.
    • Load categories and items for live TV, movies and series (get_live_categories, get_live_streams, get_vod_categories, get_vod_streams, get_vod_info, get_series_categories, get_series and get_series_info).
    • Load guide data through get_short_epg, get_simple_data_table and xmltv.php.
    • Build stream URLs for live channels, movies and episodes with the user's preferred output (HLS or TS) and each item's container extension. Build catch-up URLs from the timeshift endpoint for channels with archive enabled, supporting the common forms, such as /timeshift/{username}/{password}/{duration}/{YYYY-MM-DD:HH-MM}/{stream_id}.ts.
    • Parse defensively: providers mix strings and numbers, return nulls and send empty objects where arrays are expected.
  3. Stalker and Ministra portals (portal URL plus MAC address, MAG set-top box emulation)
    • Discover the portal's endpoint variant (for example /portal.php or /stalker_portal/server/load.php), perform the handshake to obtain a token, and load the profile, account information, genres, paged channel lists, movies, series and guide data.
    • Request playable links on demand with create_link and refresh expiring tokens transparently.
    • Send the headers and cookies portals expect (a MAG-style User-Agent, the MAC cookie, time zone, language and bearer token), with per-portal overrides for serial number, device id and signature when a provider requires them.
    • Use the MAC address the provider registered for the user, and treat it as a credential.
  4. JSON
    • Import and export the Player's own documented, versioned JSON schema: sources, channels, groups, custom order, favorites, hidden items, guide mappings and settings.
    • Import other JSON channel lists through a field-mapping step with a live preview (name, URL, logo, group and id fields, using JSONPath-style selectors).
  5. XML
    • Import XSPF playlists, and other XML channel lists through the same field-mapping step.
    • XMLTV is for guide data and is covered in section 10.
Management
  • Multiple sources per profile, each enabled or disabled independently. A merged view across sources detects duplicates (the same tvg-id or normalized name) and lets the user choose a preferred source.
  • Refresh on launch and on a schedule (for example every 12 or 24 hours) using ETag and Last-Modified, with manual refresh and a summary of what was added, removed and changed.
  • Edits that survive refreshes: rename, change the logo, change the number, move to another group and hide. Custom groups, drag-and-drop ordering (with a D-pad friendly move mode on TV) and several favorites lists.
  • Per-source settings: User-Agent and headers, output format, guide source, time shift, engine preference and adult content tagging.
  • Diagnostics: test the connection and a stream, and show HTTP status codes and redirect chains with credentials masked.
  • Export to M3U (preserving tvg attributes), the Player's JSON format and XSPF. Exclude credentials by default, include them only after an explicit choice, and never include other profiles' private data.
  • Back up and restore everything (sources, edits, favorites, settings, reminders and recording schedules) as an encrypted, password-protected file, with optional sync through a cloud folder the user controls.
10

Electronic Program Guide (EPG)

Sources
  • XMLTV from a URL or a file, including .xml.gz (and optionally .zip and .xz), discovered automatically from url-tvg in M3U headers.
  • Xtream Codes and Stalker guide endpoints, and JSON guide data through field mapping.
  • Several guide sources per profile, with a priority order and per-channel overrides.
Ingestion
  • Parse XML as a stream (pull or SAX). Never load files that can exceed 200 MB uncompressed into a DOM, and limit decompressed sizes to protect against archive bombs.
  • Write programmes to the local database in batches, indexed by channel and by start and stop times, with a full-text index on titles and descriptions for search.
  • Store every time in UTC. Parse XMLTV timestamps with their offsets (for example 20261115183000 +0100), apply provider and per-channel time shifts, handle daylight saving transitions correctly, and display times in the user's time zone and 12 or 24-hour preference.
  • Keep past programmes for the catch-up window (for example 7 days) and future programmes for the available horizon (for example 14 days), and prune automatically.
  • Refresh incrementally with conditional requests, in the background where the platform allows (WorkManager on Android, BGTaskScheduler on iOS, the running app or a helper on desktop), and never block the interface.
  • Target: ingest a 1,000-channel, 7-day guide (about 150,000 programmes) in under 30 seconds on a mid-range Android phone, with the interface responsive throughout.
Channel mapping
  • Match channels to guide data by tvg-id first, then by normalized name, ignoring case, accents, punctuation, quality suffixes such as HD, FHD, 4K or HEVC, and country prefixes such as UK: or |US|. Keep a confidence score for every match.
  • Offer a manual mapping screen with search and suggestions, plus a bulk "auto-map unmatched" action. Mappings survive refreshes.
Guide experience
  • Timeline grid: channels as rows and time as columns, virtualized in both directions and smooth at 60 fps (120 fps on high-refresh displays). A "now" line; jump to now, to a time or to a day; filters by group, favorites and genre; an adjustable time scale; and pinned channel logos and numbers.
  • Now and next everywhere: channel lists, the player overlay and the home screen.
  • Programme details: title, episode title, season and episode (from xmltv_ns and onscreen), description, categories, rating, credits, artwork, original air date and new, premiere or live flags.
  • Channel details: logo, number, name, group, country and language, archive availability and length, guide source and mapping status, and technical information about the current stream.
  • Actions on any programme: watch live, watch from the start or from the archive, set a reminder, record, record the series and find other airings.
  • Mini-guide: browse what is on other channels inside the player without stopping playback.
  • Missing data: show "No guide information" clearly and offer to map the channel.
Reminders
  • One-off and series reminders (by title, optionally limited to one channel), with a configurable lead time such as 1, 5 or 10 minutes.
  • "Watch now" and "Snooze" actions, optional automatic switching while the app is open, and visible conflicts.
  • Reminders survive app restarts and, where the platform allows, device reboots.
Catch-up and archive
  • Detect archive support from Xtream Codes (tv_archive and tv_archive_duration) and from M3U catch-up attributes.
  • Build catch-up URLs for the common modes (default, append, shift, flussonic and xc) and the placeholders popular players use, including {utc}, {utcend}, {start}, {end}, {lutc}, {duration}, {offset} and date and time format tokens. Back this with a test suite of real-world patterns.
  • Offer "Start over" for the programme currently airing when an archive is available.
11

Languages and localization

  • Internationalize from day one: no hard-coded user-facing text; ICU MessageFormat or each platform's equivalent, with plurals, gender and placeholders; translator context for every string; and pseudo-localized builds to catch truncation and string concatenation bugs.
  • Launch with a configurable set of languages, for example English, Spanish, French, German, Italian, Brazilian Portuguese, Dutch, Polish, Turkish, Russian, Arabic and Simplified Chinese, and prioritize them using your target market data.
  • Fully mirror the interface for right-to-left languages (Arabic, Hebrew, Persian and Urdu), including navigation, player controls and directional icons. Decide and document how the guide timeline behaves in right-to-left layouts.
  • Format dates, times (12 or 24-hour), numbers, file sizes, durations, the first day of the week and relative times ("in 5 minutes") for the user's locale.
  • Follow the system language by default, and offer an in-app language picker using the per-app language features of Android 13+ and iOS where available.
  • Per-profile content language preferences: an ordered list of preferred audio languages, subtitle languages, subtitles on, off or forced only, the guide language when XMLTV offers several, and the metadata language for movies and series.
  • Use fonts with full Unicode coverage (Latin, Cyrillic, Greek, Arabic, Hebrew, Devanagari, Thai, Chinese, Japanese and Korean) with correct fallback, and allow up to 40% text expansion without truncation.
  • Keep string catalogs in the repository, integrate a translation management workflow, and run screenshot tests for every language.
12

User profiles

  • Up to 10 profiles per installation (configurable), each with a name, avatar, color, optional PIN and a type: standard or kids.
  • An optional "Who's watching" screen at launch, quick switching from the main navigation and automatic selection of the last profile.
  • Per profile: which sources are visible, favorites lists, custom groups and ordering (or shared ones), watch history, resume positions for movies, episodes, catch-up and recordings, recently watched channels, reminders, recording visibility, preferred languages, playback preferences, appearance and parental restrictions.
  • Watch history with actions to remove an item, clear everything or pause history, a "Continue watching" row and a configurable "watched" threshold such as 90%.
  • Isolation: each profile's data is stored separately, no profile can see another's history, and deleting a profile deletes its data after confirmation.
  • Export and import a single profile, and include every profile in full backups.
  • Optional cross-device sync that is opt-in and end-to-end encrypted, using storage the user controls or a backend you propose with clear privacy terms.
13

Parental controls

  • A master parental PIN of 4 to 8 digits, or an optional alphanumeric password, created when parental controls are first turned on. Store only a salted, slow hash (Argon2id, or PBKDF2 with a high iteration count) in secure storage, and never log or sync it in plain form.
  • Brute-force protection: lock entry for increasing periods after repeated failures (for example 1 minute after 5 failures, doubling each time).
  • Recovery without an account: verify with the device's biometrics or passcode where available, or by re-entering the source credentials; otherwise offer a full reset of parental settings together with the restricted data. Document the flow clearly.
  • Restrictions:
    • Lock or hide individual channels, groups, movie and series categories and specific titles.
    • Set a maximum content rating per profile using guide and VOD metadata, supporting common rating systems (MPAA, TV Parental Guidelines, FSK, BBFC, PEGI and others).
    • Detect adult content automatically from group names and a configurable keyword list, and hide it by default in new profiles.
    • Kids profiles show only allowed content in a simplified interface, with no access to settings or sources, and cannot switch profiles without the PIN.
    • Set allowed viewing hours and a daily viewing time limit per profile.
    • Protect settings, source management, profile management, purchases and recording deletion with the PIN.
  • Behaviour:
    • Locked items either show a lock and ask for the PIN, or are hidden entirely, as chosen per profile.
    • An unlocked session stays unlocked for a configurable time (for example 15 minutes) and locks again when the app goes to the background.
    • Locked content never appears in previews, thumbnails, search results, notifications, recently watched lists or casting suggestions.
  • Apply restrictions consistently across live TV, the guide, catch-up, movies, series, recordings, downloads, search and notifications.
14

Recording, timeshift and playback

Live pause and rewind
  • Keep a local timeshift buffer while watching live TV: pause, rewind and fast-forward within it, with a configurable length (for example up to 2 hours) and disk budget, a "Go live" button and the buffered range shown on the progress bar.
  • Use the provider's archive, when available, to rewind further than the local buffer.
Recording
  • Instant recording of the current channel, and scheduled recordings from the guide: a single programme, a series by title or a manual time range, with padding before and after, priorities and conflict resolution.
  • Respect the account's connection limit: warn before a recording would exceed it and plan schedules within it.
  • Record by remuxing, never transcoding: write TS directly or remux to MP4 or MKV; for HLS, download and join segments, handling discontinuities and AES-128 decryption where the user is authorized. Never record DRM-protected streams.
  • State platform realities in the interface:
    • Android: a foreground service with the correct service type and a visible notification, accounting for the foreground service rules and time limits of recent Android versions and the exact alarm permission for scheduled starts.
    • iOS and iPadOS: recording cannot run reliably in the background, so it continues only while the app is active. Offer a "keep screen on while recording" mode, explain the limitation, and consider a companion recorder on a desktop computer.
    • Windows and macOS: the app or a lightweight helper (in the system tray or menu bar, launched at login with the user's consent) must be running, and the computer must be kept awake during a recording.
  • A recordings library with thumbnails, status (scheduled, recording, completed or failed with a reason), size and duration; actions to play, resume, rename, delete and export where allowed; a choice of storage location; and auto-delete rules (keep the last N episodes, delete after watching, delete when storage runs low).
  • Explain in the interface that recordings are for personal use and must comply with the provider's terms and local law.
Playback controls

These apply to live TV, catch-up, movies, series and recordings:

  • Play and pause, a seek bar with thumbnails where available, configurable skip back and forward (10, 15 or 30 seconds) and chapters where present.
  • Playback speed from 0.5x to 2x for anything that is not live.
  • Audio track selection with language names, audio delay adjustment and volume normalization.
  • Subtitles: select, turn off or show forced only; style them (size, color, background, edge and position); adjust their delay; and load external SRT, ASS or VTT files for movies and episodes.
  • Video: aspect ratio modes (fit, fill, 16:9, 4:3, stretch, zoom and crop), deinterlacing, HDR on, off or tone-mapped where supported, and frame-rate matching on Android TV.
  • Picture in Picture on every platform: native PiP on iOS, iPadOS, Android and macOS, and an always-on-top mini player on Windows and macOS.
  • Multi-view of 2 to 4 streams at once on desktop, tablets and TV, limited by decoders, performance and connection limits, with a choice of which tile plays audio.
  • Channel changes with up and down, number entry with on-screen confirmation, a last-channel toggle, a channel list overlay and favorites-only zapping.
  • Resume where you left off, a "Next episode" countdown and an optional skip intro where metadata allows.
  • A sleep timer, background audio for radio channels, an audio-only mode, and keeping the screen awake during playback.
  • "Open in external player" (for example VLC, mpv, Infuse or MX Player) through platform intents and URL schemes when one is installed.
16

Notifications

What to notify
  • Programme reminders that deep-link to the channel or programme, with "Watch now" and "Snooze" actions.
  • Recording events: started, completed, failed with the reason, conflicts and low storage.
  • Source events: refresh failed, account expiring soon (for example 7 days and 1 day before an Xtream Codes expiry date) and connection limit reached.
  • Download events: completed, failed or paused while waiting for Wi-Fi.
  • App updates and "What's new", shown in the app first, with system notifications only for important updates.
How, per platform
  • iOS, iPadOS and macOS: UNUserNotificationCenter with categories and actions, the time-sensitive interruption level for reminders when the user allows it, and a rolling schedule that stays within the limit on pending local notifications (64 on iOS).
  • Android: a notification channel per type, the POST_NOTIFICATIONS runtime permission on Android 13+, and exact alarms only where justified and permitted.
  • Windows: app notifications (toasts) with actions, for example through the Windows App SDK, that open the right screen when clicked.
  • Ask for notification permission in context, for example when the user first sets a reminder, and explain what is lost if they decline.
  • Per-profile notification preferences and quiet hours that respect the system's Do Not Disturb and Focus modes.
  • Core features must not need a push server. If you propose remote push (APNs, FCM or WNS) for announcements, make it opt-in and privacy-preserving.
17

Performance and optimization

Targets

Validate on the reference device list and report median and 95th percentile results:

Metric Target
Cold start to a usable channel list from cache Under 2 s on mid-range phones and under 1 s on desktop
Channel change, time to first frame (HLS or TS on 20 Mbps) Median under 1.5 s and 95th percentile under 3 s
Rebuffering during live playback on a stable connection Under 1% of watch time
Importing a 50,000-entry playlist Under 10 s on a mid-range Android phone, with the interface responsive
Guide grid and long lists 60 fps with no frame over 32 ms while scrolling, and 120 fps on high-refresh displays where possible
Search Under 100 ms per keystroke (100,000 channels and 1 million programmes)
Memory during playback Under 300 MB on phones and under 250 MB on low-end Android TV boxes
Stability At least 99.5% crash-free sessions, and a 24-hour playback soak test without crashes or memory growth over 10%
Techniques to apply and justify
  • Hardware decoding first and zero-copy rendering paths.
  • Adaptive bitrate tuned per network type: a conservative start, a fast ramp-up and buffer sizes per content type.
  • Connection reuse (keep-alive, and HTTP/2 where available), DNS caching and parallel segment fetching within limits.
  • Optional pre-buffering of adjacent channels, only when the connection limit allows.
  • Large data kept off the UI thread: background parsing, batched database writes, WAL mode, prepared statements, indexes, pagination and virtualized lists.
  • An image pipeline for logos and posters with memory and disk caches, downsampling to display size, placeholders and priority for visible items.
  • Lazy loading of screens and modules, startup tracing and deferring anything not needed at launch.
  • Battery and heat: respect low power and battery saver modes, reduce multi-view under thermal pressure and avoid unnecessary wake-ups.
  • Data saver: cap quality on cellular and metered networks, with Wi-Fi-only options for downloads and guide refreshes.
  • Instrumentation: on-device performance metrics, a diagnostics screen and optional, opt-in anonymous quality-of-experience telemetry (startup time, rebuffering and errors), plus a profiling guide per platform.
18

Offline mode

  • Offline-first interface: cached sources, channel lists, guide data, favorites, history, settings and artwork all work without a connection. Show a clear offline indicator, and disable actions that need a network with an explanation.
  • Downloads where applicable: movies, series episodes, catch-up programmes where the provider allows downloading, and recordings, which are already local. Live channels cannot be downloaded, and the interface says so.
  • Download manager: a queue with pause, resume and retry; quality selection (an HLS or DASH rendition, or the original file for progressive downloads); a Wi-Fi-only option; a storage estimate before downloading; per-profile visibility and parental restrictions; and auto-delete after watching or after a set number of days.
  • Platform specifics: background URL sessions on iOS, with AVAssetDownloadURLSession for HLS; Media3's DownloadService and DownloadManager on Android, with progress notifications; and a resumable downloader using HTTP range requests on desktop.
  • DRM-protected content is downloaded only through the native engine's official offline license flow when the provider supports it; otherwise, downloading is disabled for that item.
  • Respect provider terms and connection limits: active downloads count as connections.
19

Security and privacy

Credentials and data at rest
  • Store provider credentials, MAC addresses, tokens and PIN hashes only in the operating system's secure storage: Keychain on Apple platforms, Android Keystore (for example with Tink for encryption, avoiding deprecated wrappers) and Windows Credential Locker or DPAPI.
  • Encrypt the local database, or at least its sensitive tables (for example with SQLCipher), with a key held in secure storage, and use data protection classes on iOS.
  • Mask credentials everywhere they could appear: the interface, logs, crash reports, diagnostic exports, playlist exports and stream URLs. Xtream Codes URLs contain the username and password in the path, so treat every full stream URL as a secret.
Data in transit
  • Use HTTPS by default, with TLS 1.2 or later and platform certificate validation. Allow plain HTTP only per source and with a clear warning, because many providers still use it.
  • Keep App Transport Security exceptions narrow (for example NSAllowsArbitraryLoadsForMedia for AVFoundation playback, plus only what the API calls need, with a justification ready for App Review), and permit cleartext on Android only where needed through a network security configuration.
  • Use certificate pinning only for your own backend services, never for provider URLs entered by users.
Untrusted input

Treat playlists, guides and portal responses as hostile until validated:

  • Disable external entities and DTD processing in XML parsers to prevent XXE and entity expansion attacks; limit decompressed sizes, line lengths, field lengths and file sizes; and apply timeouts.
  • Allow only expected URL schemes (http, https, rtmp, rtmps, rtsp, udp and rtp, plus file for local files the user picked); never execute anything from a source; sanitize HTML in descriptions; validate image URLs and sizes; and prevent path traversal in recording and download file names.
  • Request local network access only when it is needed, with an explanation, to satisfy the local network privacy prompts on iOS and macOS.
App protection and authentication
  • An optional app lock with biometrics (Face ID or Touch ID, Android BiometricPrompt and Windows Hello) or the device passcode.
  • If you add accounts or sync: OAuth 2.0 and OpenID Connect with PKCE, short-lived access tokens, refresh token rotation, tokens in secure storage and server-side rate limiting.
  • Support AES-128 HLS, token-based and signed URLs, and DRM (Widevine on Android, FairPlay on Apple platforms and PlayReady on Windows) only through native engines and licensed content decryption modules. Never attempt to bypass DRM.
Privacy
  • No tracking or advertising SDKs by default. Analytics and crash reporting are opt-in, anonymous and minimal.
  • Comply with GDPR, CCPA/CPRA and similar laws: a clear privacy policy, data export and deletion, and accurate App Store privacy labels and Google Play Data safety answers.
  • Explain why each permission is needed at the moment it is requested.
Secure development
  • Write a threat model (for example STRIDE) covering sources, playback, storage and sync, and follow OWASP MASVS for mobile with equivalent practices on desktop.
  • Run dependency, license, static analysis and secret scanning in CI.
  • Sign every build: Authenticode on Windows, Developer ID with the hardened runtime and notarization on macOS, Play App Signing on Android and App Store signing on iOS. Produce a software bill of materials for every release.
20

Casting and integrations

Chromecast (Google Cast)
  • Support casting from Android and iOS with the Google Cast SDK. The official SDK is not available for native desktop apps, so either evaluate an implementation of the open Cast protocol on desktop or schedule desktop casting for a later phase, and explain the trade-offs.
  • Use the Default Media Receiver where it can play the stream (HLS, DASH and MP4), and evaluate a Custom Web Receiver for wider format support, live TV controls and branding.
  • Handle streams a receiver cannot fetch directly (raw TS, custom headers, Referer checks and credentials in URLs): prefer the provider's HLS output, or relay and remux through the sending device, with the battery and privacy implications explained. Never send credentials through third-party relays.
  • Provide the full casting experience: a device picker, mini controller, expanded controller, queues for series, track selection on the receiver and lock screen controls.
AirPlay
  • Support AirPlay natively on iOS, iPadOS and macOS through AVPlayer and the system route picker (AVRoutePickerView). When a stream is playing on the FFmpeg-based engine, switch to AVPlayer for AirPlay if the format allows, and otherwise explain the limitation.
  • AirPlay from Windows and Android is out of scope because there is no official support.
DLNA and UPnP
  • A control point that discovers renderers through SSDP and sends streams to smart TVs and AV receivers, with play, pause, seek and volume control.
  • An optional media server that shares recordings and downloads on the local network.
  • Discovery needs multicast, so plan for Apple's multicast networking entitlement, Android multicast locks and desktop firewall prompts.
Other integrations

Prioritize these and assign them to phases:

  • System media controls and Now Playing information on every platform, plus Bluetooth and HDMI-CEC remote keys through the operating system.
  • Android TV and Google TV: home screen and "Continue watching" integration through the APIs Google currently recommends, voice search and frame-rate matching.
  • Shortcuts and voice: App Intents and Siri Shortcuts on Apple platforms, app shortcuts on Android and jump lists on Windows.
  • Optional metadata enrichment for movies and series (for example TMDB) and watch history scrobbling (for example Trakt), respecting each service's terms and attribution rules.
  • External player handoff, as described in section 14.
  • Stable extension points for future integrations: new source types, metadata providers and cast targets.
21

Updates, releases and maintenance

Distribution and updates
  • Windows: the Microsoft Store (MSIX) plus a signed direct download with automatic, ideally delta, updates (for example MSIX with App Installer, or a framework such as Velopack).
  • macOS: the Mac App Store and/or a notarized Developer ID build updated with Sparkle 2 and an EdDSA-signed appcast. Account for the sandbox and entitlement differences between the two.
  • iOS and iPadOS: the App Store, with TestFlight for beta testing.
  • Android: Google Play with an Android App Bundle and the Play In-App Updates API (flexible for regular updates and immediate for critical fixes). If you also distribute an APK for Android TV boxes, plan for signing, update checks and Google's developer verification requirements for apps installed outside Google Play.
Release process
  • One semantic version across all platforms, with a shared changelog and an in-app "What's new".
  • Release channels (internal, beta and stable) using TestFlight, Google Play testing tracks and a desktop beta feed, with staged rollouts that are monitored and can be halted.
  • Remote configuration and feature flags, kill switches for risky features, and a minimum supported version check that asks users to update when a critical fix ships.
  • Versioned, tested database migrations with an automatic backup before migrating, and versioned export formats that remain backward compatible.
CI/CD
  • A monorepo with a documented module layout.
  • Continuous integration on every pull request: linting, formatting, type checks, unit and integration tests and builds for all four platforms, with macOS runners for Apple builds.
  • Automated signing with secrets kept in a vault, automated store uploads (for example with fastlane), reproducible builds and archived artifacts for every release.
Maintenance
  • Scheduled dependency updates (for example with Renovate or Dependabot) and a security patch target, such as critical fixes within 72 hours.
  • Yearly OS readiness: test against each summer's OS betas and adopt newly required SDK levels before store deadlines.
  • Observability: opt-in crash reporting, structured logs with redaction, and an in-app diagnostics screen that can export a log for support.
  • Documentation: an architecture overview, decision records, a contributor guide and runbooks for releases and incidents.
22

Data model and storage

Propose a schema that covers at least:

  • Profile: id, name, avatar, type, PIN hash reference and preferences.
  • Source: id, profile scope, type, name, URL or server, enabled, refresh interval, headers, output format, guide URL, last refresh and status. Credentials live in secure storage, referenced by id.
  • Group: id, source, name, type (live, movie, series or radio), provider order, user order and hidden.
  • Channel: stable id, source, provider stream id, name, normalized name, number, logo, group, tvg-id, guide channel id, stream URLs, headers, catch-up mode, days and template, and radio and adult flags.
  • ChannelOverride: user edits that survive refreshes.
  • Movie, Series, Season and Episode: metadata, container extension, duration, ratings and artwork.
  • GuideSource, GuideChannel and Programme: channel, start and stop in UTC, title, episode title, description, categories, episode numbering, rating, artwork, flags and language.
  • GuideMapping: channel, guide channel, method and confidence.
  • FavoriteList and Favorite: profile, item, list and position.
  • WatchHistory: profile, item, position, duration, completed and updated time.
  • Reminder, RecordingSchedule, Recording and Download: schedule, status, file location, size, duration and error.
  • ParentalRule: profile, target type and id, rule type, rating and schedule.
  • Setting: global and per-profile values with a schema version.

Storage technology:

  • SQLite with WAL and FTS5, through a library suited to your stack (for example SQLDelight, Drift, Room, GRDB or rusqlite), encrypted where data is sensitive.
  • A key-value store for small preferences, files for the artwork cache, recordings and downloads, and secure storage for secrets.
  • Provide the entity relationship diagram in Mermaid, the indexes, the expected row counts and sizes, and the migration strategy.
23

Testing and quality

  • Unit tests for every parser and URL builder (M3U, XMLTV, Xtream Codes and Stalker responses, catch-up templates and header handling) against a fixture library of real-world, malformed and very large inputs, plus fuzz and property-based tests for parsers.
  • Integration tests against mock servers that emulate Xtream Codes and Stalker portals, with HLS, DASH, TS and RTMP test streams served locally and network profiles for 3G, high latency, packet loss and unstable Wi-Fi.
  • Playback matrix: every protocol and codec from section 8 on the reference devices, for example a low-end Android TV box, mid-range and flagship Android phones, an Android tablet, an older and a current iPhone, an iPad, Intel and Apple silicon Macs, a Windows PC with integrated graphics and a Windows on ARM laptop.
  • UI tests per platform with each framework's tooling; screenshot tests per size class, theme and language, including right-to-left; and D-pad navigation tests for TV.
  • Performance tests for the targets in section 17, automated on reference devices where possible, and 24-hour soak tests for leaks.
  • Accessibility audits with automated checks and manual screen reader passes, localization QA, security testing against OWASP MASVS and a license compliance review.
  • Beta programme with in-app feedback, and release quality gates: crash-free rate, no open critical bugs and performance targets met.
24

Delivery plan and phases

For every phase, provide the scope, user stories with acceptance criteria, estimates, risks, test results and demo builds for all four platforms.

  1. Phase 0, architecture and playback spike: the decision matrix, decision records, repository skeleton and CI, and a spike that plays the hardest streams on all four platforms with measured channel change times: HLS with custom headers, raw MPEG-TS with AC-3 or MP2 audio, interlaced MPEG-2, DASH, RTMP and UDP multicast. Exit when the chosen stack is proven on real devices.
  2. Phase 1, core player: M3U and Xtream Codes sources, live TV with groups and favorites, the player with core controls, track and quality selection, basic guide data (now and next from XMLTV and Xtream Codes), search, one profile with secure credential storage, the localization framework with three languages, settings and diagnostics.
  3. Phase 2, full guide and library: Stalker portals, the guide grid with mapping and reminders, notifications, catch-up, movies and series with resume, multiple profiles, parental controls, JSON and XML import and export, Picture in Picture, Chromecast and AirPlay.
  4. Phase 3, power features: timeshift, recording and scheduling, downloads and offline mode, DLNA, multi-view, smart groups and advanced filters, Android TV polish, more languages, and DRM if required.
  5. Phase 4, hardening and launch: performance and accessibility work against the targets, a security review and penetration test, store submissions with reviewer demo content, update pipelines and documentation.

Example acceptance criteria:

  • Given an M3U playlist with 50,000 entries, when the user imports it on a mid-range Android phone, then parsing and indexing finish in under 10 seconds, progress is shown and the interface never freezes.
  • Given an Xtream Codes account limited to one connection, when the user schedules a recording that overlaps live viewing, then the Player warns about the conflict before it happens and never opens a second connection.
  • Given a channel that requires a custom User-Agent, when the user plays or casts it on any platform, then the header is sent, or the Player explains why casting is not possible for that channel.
  • Given a parental lock on a group, when a kids profile searches, then no locked channel, programme or artwork appears in the results.
  • Given the device is offline, when the user opens the Player, then cached channels, guide data and downloads are available and live channels show a clear offline message.
  • Given an exported diagnostics log, when it is inspected, then no username, password, MAC address, token or full stream URL appears in it.
25

Your first response

Respond in this order:

  1. A one-paragraph summary of your understanding.
  2. Your assumptions and up to 10 clarifying questions.
  3. The cross-platform challenge analysis from section 5: a summary table, then the details.
  4. The framework decision matrix with scores, your recommendation and the decision records.
  5. The architecture: diagrams, the responsibilities of each layer and the key interfaces.
  6. The repository structure and the modules, with what each one owns.
  7. The data model diagram and storage choices.
  8. Implementation notes for each platform: Windows, macOS, iOS and iPadOS, and Android including Android TV.
  9. The security and privacy design, with threat model highlights.
  10. The testing strategy with the device and stream test matrix.
  11. The release and update plan for each platform.
  12. The phased roadmap with estimates, risks and acceptance criteria.
  13. Phase 0 starter code: the project scaffolding, the PlaybackEngine and SourceProvider interfaces, a streaming M3U parser with unit tests, and the plan for the playback spike.

Then stop and wait for review before you start Phase 1.