PyIPTV

A Modern Python IPTV Player

Feature-rich IPTV player built with PySide6/Qt6 for streaming live television content from M3U playlists

✨ Features

Core Functionality

• 📺 M3U Playlist Support - Load and manage IPTV playlists in M3U format
• 📡 Xtream Codes API - Native support for Xtream-panel providers with server-side categories and on-device caching
• 🎨 Modern Qt6 Interface - Built with PySide6 for a responsive, native desktop experience
• 📂 Category Organization - Automatically organize channels by categories
• 🔍 Search & Filtering - Quickly find channels with real-time search
• 🎵 Audio Track Selection - Multi-language audio track support

User Experience

• 🌓 Theme Support - System-aware theming with KDE integration
• ⚡ Performance Optimized - Handles large playlists with virtualized lists and smart buffering
• ⚙️ Settings Management - Persistent settings with user-friendly configuration
• 🖥️ High DPI Support - Optimized for high-resolution displays

🚀 Installation

From PyPI (Recommended)

pip install pyiptv

Using uvx (Isolated execution)

uvx pyiptv

From Source

git clone https://github.com/dmarkey/PyIPTV.git
cd PyIPTV
pip install -e .

📖 Usage

Basic Usage

Launch PyIPTV without arguments to open the playlist manager:

pyiptv

Direct Playlist Loading

Launch directly with a playlist file:

pyiptv /path/to/your/playlist.m3u

Command Line Arguments

📋 Requirements

System Dependencies

sudo apt install python3-pip qt6-multimedia-dev

sudo dnf install python3-pip qt6-qtmultimedia-devel

brew install python qt6

⚙️ Configuration

PyIPTV automatically creates configuration files in platform-appropriate locations:

Available Settings

• Theme Mode - System auto-detection, light, or dark themes
• Buffering - Adjustable buffering time for smooth playback
• Performance - Options for handling large playlists
• UI Preferences - Window geometry, splitter sizes, and more

📝 Playlist Format

PyIPTV supports standard M3U playlist format with extended information:

#EXTM3U
#EXTINF:-1 tvg-id="channel1" tvg-name="Channel Name" tvg-logo="logo.png" group-title="Category",Channel Display Name
http://example.com/stream1.m3u8
#EXTINF:-1 tvg-id="channel2" tvg-name="Another Channel" group-title="Movies",Movie Channel
http://example.com/stream2.m3u8

📡 Xtream Codes Sources

PyIPTV talks to Xtream-panel providers natively — no need to hand-build an M3U URL.

Adding a source

1. Open the Playlist Manager (Ctrl+P or the initial launch window).
2. Click Add Playlist and pick Xtream Codes.
3. Enter:
   • Server — http://host:port (or https://)
   • Username
   • Password
4. Save. The dialog authenticates against player_api.php before committing, so invalid credentials are rejected up front.

How it works

Scope & limitations

• Live TV only — VOD and series are not yet surfaced (planned).
• EPG — get_short_epg is wired up and cached in memory, but no guide UI is shown yet (planned).
• Credential storage — username and password are stored in plaintext in ~/.config/PyIPTV/playlists.json, matching the existing settings-file pattern. If that's a concern for your environment, use a dedicated account with low max_connections and a unique password.
• CDN user-agent — Qt's media backend sends its own UA when fetching stream URLs. Some Cloudflare-fronted providers reject non-browser UAs. API calls are unaffected (the client sends a browser UA), but if playback fails with resource/network errors on every channel, the provider is likely UA-gating streams and a local proxy would be required (not implemented yet).

🏗️ Architecture

PyIPTV follows a modular architecture design:

┌─────────────────┐
│ Main Application│
├─────────────────┤
│ UI Components   │
│ Playlist Manager│
│ Media Player    │
│ Settings Manager│
│ Theme Manager   │
└─────────────────┘

Components

• Main Application - Entry point and application lifecycle management
• UI Components - Modular Qt widgets for different functionality
• Playlist Manager - M3U parsing and playlist management
• Media Player - Qt6 multimedia integration
• Settings Manager - Configuration persistence
• Theme Manager - System-aware theming

🛠️ Development

Setting up Development Environment

git clone https://github.com/dmarkey/PyIPTV.git
cd PyIPTV
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black pyiptv/
isort pyiptv/

Linting

flake8 pyiptv/

🔧 Troubleshooting

Common Issues

Debug Mode

Run with debug information:

PYTHONPATH=. python -m pyiptv.main --debug

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Guidelines

• Follow PEP 8 style guidelines
• Add tests for new features
• Update documentation as needed
• Ensure compatibility with supported Python versions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Most of the codebase for PyIPTV was generated by Claude Sonnet 4
• Built with PySide6 - Qt for Python
• Inspired by the need for a modern, cross-platform IPTV player
• Thanks to the open-source community for tools and libraries

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: david@dmarkey.com