Important

Attention!!! Volunteers are needed for translations. Click here.

UIPTV - A Universal IPTV Player for Windows, Linux & macOS

UIPTV is a versatile IPTV player written in Java, designed to run on Windows, Linux, and macOS. It provides both a desktop experience and a full local-network web experience (SPA/PWA) for Live TV, VOD, and Series.

Core principle: keep the app simple, plain, and practical so everyday playback and account management stay fast and predictable.

Release assets are currently published for Windows (x86_64), Linux (x86_64 and aarch64 where available), macOS (x86_64, aarch64), and Android as a universal APK. GitHub releases are published only from repository-root release.sh, which creates one combined desktop plus mobile release.

Documentation

• User guide: GUIDE.md
• Import format reference: ACCOUNT_IMPORT_GUIDES.md
• Release notes: release_notes.md

Project Layout

UIPTV now builds as a Maven reactor with separated runtime modules:

• core/: shared domain models, SQLite/database layer, application services, cache reloaders, import parsers, migrations, i18n bundles, and release/version resources.
• api-server/: Undertow-based local web server, JSON/playlist endpoints, and bundled SPA/PWA assets under api-server/src/main/resources/web/.
• javafx-app/: JavaFX desktop application, players, widgets, dialogs, desktop CSS, icons, and native packaging configuration.
• website/: static project website published separately to GitHub Pages.

Build from the repository root. Maven resolves the module graph automatically.

What's New

• Parental lock: Keyword filtering can now be password-protected, and Stalker censored categories/channels can require a local parental lock password before opening.
• Remote sync: One-way database sync now supports approval-based remote execution, propagated configuration tables, and clearer completion feedback on both peers.
• Published playlist controls: M3U publishing now supports account/category/channel hierarchy, category modes, and more precise exported playlist sets.
• HLS/VLC playback fixes: Embedded VLC playback now handles redirects, cookies, SSL, and CloudFront-style HLS streams more reliably.
• Series binge-watch: Series playback now supports binge-watch playlist/session handling for episode-to-episode viewing.
• Update experience: The About/update flow now uses a custom GitHub Releases-backed update window.
• Localized UI: Multiple bundled UI languages are available, including RTL support and localized season/episode/tab numbering for supported locales.
• Theme controls: Built-in light/dark themes now support saved zoom scaling, zoom-fill playback mode, and live preview from Configuration -> Theme.

Features:

• Simple by Design: UIPTV prioritizes a plain, low-friction interface and practical defaults over visual clutter or complex workflows.
• Embedded & External Player Support: UIPTV includes embedded playback through VLC and configurable external player support.
  • For the best experience, it is highly recommended to have VLC installed on your system and available in the system's PATH.
  • If VLC is not found, embedded playback is disabled and UIPTV will prompt you to use an external player or install VLC correctly.
  • You can still configure an external player (like MPV, SMPlayer, etc.) for maximum control.
• Watching Now + Series Resume: Track watched series/episodes and continue from where you left off on desktop and web.
• VOD/Series Metadata: Enhanced details for movies/series including richer cards and IMDb-oriented metadata flows.
• Parental Lock & Filtering: Protect blocked keywords and Stalker censored content with a local password, while still supporting category/channel filtering and pause/unpause controls. These restrictions also affect content exposed through the web server.
• Theme Modes & Styling: Built-in light/dark themes are included, and theme zoom can be saved from Settings.
• Web Server: Expose your accounts, bookmarks, watching-now data, and published playlists to any device on your local network through a browser.
  • SPA Routes: Main UI is served from / and /index.html.
  • Extra Endpoints: Includes playlist exports (/iptv.m3u, /iptv.m3u8) and bookmarks playlist (/bookmarks.m3u8).
• DRM-aware Web Playback: Playback payloads now include DRM fields (type/license/clear keys/manifest hints) where available.
• Web Server Headless Support: Run UIPTV in headless mode if you only intend to access channels through a browser.
• Multiple IPTV Protocols: The player supports the following protocols and formats:
  • Stalker Portal: Live Channels, Video On Demand, and Series.
  • M3U Playlists: Supports local and remote M3U files (EPG is not yet supported).
  • Xtreme Codes: Live Channels, Video On Demand, and Series.
• Bulk Account Import: Add multiple accounts at once for Stalker, Xtreme, and M3U, with optional post-import verification.
• Account Tools: MAC verify/manage flows, account pinning, timezone and HTTP method support for Stalker, browser-playback routing, and account-level cache reload.
• Database Synchronization: Synchronize your configuration and accounts between two database files locally or through the approved remote sync flow.
• Tab-Based Interface: The user interface has been updated from expandable panels to a more intuitive tab-based layout for managing accounts and settings.
• About Page & Update Checks: The About page includes a GitHub Releases-backed update check with a custom release-notes dialog.
• Cache Management: UIPTV uses an SQLite database cache with configurable expiry, global clear/reload flows, and account-level reload tools.
• Website: A promotional website is now available at https://xixogo5105.github.io/uiptv/.

Important Installation Note for Windows and Linux (DEB) Users

Before installing a new version or upgrading, you must manually uninstall the previously installed version of UIPTV. The installer does not automatically remove older versions, and failure to do so may result in the upgrade not being applied correctly.

Compiling UIPTV

This application is built using Java 25 and JavaFX, and it is packaged into native installers using jpackage from the javafx-app module.

Before compiling, please ensure you have:

1. A JDK (version 25 or higher) installed, with the JAVA_HOME environment variable correctly set.

2. Apache Maven installed.

3. Windows only: The WiX Toolset build tools must be installed and available on PATH when building Windows installers. jpackage requires candle.exe and light.exe for .exe/.msi packaging.

   Install WiX Toolset with winget (PowerShell):

   winget install --id WiXToolset.WiXToolset -e --source winget

   Verify both tools are available:

   where.exe candle
   where.exe light

   If either command is not found, add the WiX bin directory to PATH (then open a new terminal), for example:

   • C:\Program Files (x86)\WiX Toolset v3.14\bin

4. Linux DEB packaging (Debian/Ubuntu): fakeroot must be installed for .deb builds.

To compile the project, use Maven profiles from the repository root to target specific operating systems and package formats. Native packaging output is generated in javafx-app/target/dist. Each module also writes its own intermediate build output under its local target/ directory.

Build Commands

Here are some examples of how to build the application for different targets.

Windows

• Windows (x86_64):

  mvn clean package -P windows-x86_64

• Windows (ARM64/aarch64):

  mvn clean package -P windows-aarch64

  **JavaFX does not publish `win-aarch64` artifacts on Maven Central (as of 25.0.2), so this profile fails dependency resolution. On Windows ARM devices, use the x86_64 build under emulation instead.**

macOS

• macOS (Intel/x86_64):

  mvn clean package -P mac-x86_64

• macOS (Apple Silicon/aarch64):

  mvn clean package -P mac-aarch64

Linux

For Linux, you combine an OS/architecture profile with a packaging profile.

• Linux (x86_64):

  • DEB Package: (Requires fakeroot to be installed on Debian/Ubuntu)

    mvn clean package -P linux-x86_64,pkg-deb

  • RPM Package: (Requires rpm to be installed)

    mvn clean package -P linux-x86_64,pkg-rpm

  • Portable app bundle archive:

    mvn clean package -P linux-x86_64,pkg-app-image

• Linux (ARM64/aarch64):

  • DEB Package: (Requires fakeroot to be installed on Debian/Ubuntu)

    mvn clean package -P linux-aarch64,pkg-deb

  • RPM Package: (Requires rpm to be installed)

    mvn clean package -P linux-aarch64,pkg-rpm

  • Portable app bundle archive:

    mvn clean package -P linux-aarch64,pkg-app-image

Misc

When providing an external video player, you can also use the flatpak. Just use the direct binary address. For example, a standard VLC flatpak address is _ /var/lib/flatpak/app/org.videolan.VLC/current/active/export/bin/org.videolan.VLC_ which can be provided to run IPTV streams directly.

If you are using native MPV (e.g. _ /usr/bin/mpv_) and the streams stop/freeze after a little while then create an executable sh file with the contents below and point the executable sh file (e.g. _ ~/apps/mpv/mpv.sh_) as an external player.

The contents of _ mpv.sh_ file:

#!/bin/sh
/usr/local/bin/mpv "$@"&

You can also use below (Mac OSX) sh script to play streams on KODI as external player. The script will act as player to UIPTV. It will open the kodi with the stream url or (and if remote access is enabled) send remote request to open the stream if the KODI is already working.

#!/bin/bash

STREAM_URL="$1"
KODI_HOST="localhost"
KODI_PORT="8080"
KODI_USER=""
KODI_PASS=""

if [ -z "$STREAM_URL" ]; then
    exit 1
fi

if [ -z "$KODI_USER" ] || [ -z "$KODI_PASS" ]; then
    curl -s -X POST -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "Player.Stop", "params": {"playerid": 1}, "id": 1}' "http://$KODI_HOST:$KODI_PORT/jsonrpc"
    curl -s -X POST -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "Application.SetVolume", "params": {"volume": 0}, "id": 3}' "http://$KODI_HOST:$KODI_PORT/jsonrpc"
    curl -s -X POST -H 'Content-Type: application/json' -d "{\"jsonrpc\": \"2.0\", \"method\": \"Player.Open\", \"params\": {\"item\": {\"file\": \"$STREAM_URL\"}}, \"id\": 2}" "http://$KODI_HOST:$KODI_PORT/jsonrpc"
else
    curl -s -X POST -H 'Content-Type: application/json' -u "$KODI_USER:$KODI_PASS" -d '{"jsonrpc": "2.0", "method": "Player.Stop", "params": {"playerid": 1}, "id": 1}' "http://$KODI_HOST:$KODI_PORT/jsonrpc"
    curl -s -X POST -H 'Content-Type: application/json' -u "$KODI_USER:$KODI_PASS" -d '{"jsonrpc": "2.0", "method": "Application.SetVolume", "params": {"volume": 0}, "id": 3}' "http://$KODI_HOST:$KODI_PORT/jsonrpc"
    curl -s -X POST -H 'Content-Type: application/json' -u "$KODI_USER:$KODI_PASS" -d "{\"jsonrpc\": \"2.0\", \"method\": \"Player.Open\", \"params\": {\"item\": {\"file\": \"$STREAM_URL\"}}, \"id\": 2}" "http://$KODI_HOST:$KODI_PORT/jsonrpc"
fi

open -a Kodi --args "$STREAM_URL"

Disclaimer

This is a personal project developed for fun. EPG support is not yet implemented.

Merge requests for bug fixes or new features are always welcome.

Donations are neither needed nor accepted. If you wish to contribute, please consider donating to one of your favorite open-source projects, such as Linux Mint or Ubuntu.