xtream2m3u/README.md

xtream2m3u

Convert Xtream IPTV APIs into customizable M3U playlists with ease

About • Features • Prerequisites • Installation • Usage • API • License

About

xtream2m3u is a powerful and flexible tool designed to bridge the gap between Xtream API-based IPTV services and M3U playlist-compatible media players. It offers a user-friendly web interface and a comprehensive API to generate customized playlists.

Many IPTV providers use the Xtream API, which isn't directly compatible with all players. xtream2m3u allows you to:

1. Connect to your Xtream IPTV provider.
2. Select exactly which channel groups (Live TV) or VOD categories (Movies/Series) you want.
3. Generate a standard M3U playlist compatible with almost any player (VLC, TiviMate, Televizo, etc.).

Features

• Web Interface: Easy-to-use UI for managing credentials and selecting categories.
• Custom Playlists: Filter channels by including or excluding specific groups.
• VOD Support: Optionally include Movies and Series in your playlist.
• Stream Proxying: built-in proxy to handle CORS issues or hide upstream URLs.
• Custom DNS: Uses reliable DNS resolvers (Cloudflare, Google) to ensure connection stability.
• XMLTV EPG: Generates a compatible XMLTV guide for your playlist.
• Docker Ready: Simple deployment with Docker and Docker Compose.

Prerequisites

To use xtream2m3u, you'll need:

• An active subscription to an IPTV service that uses the Xtream API.

For deployment:

• Docker & Docker Compose (Recommended)
• OR Python 3.9+

Installation

Using Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/ovosimpatico/xtream2m3u.git
   cd xtream2m3u
   

2. Run the application:

   docker-compose up -d
   

3. Open your browser and navigate to http://localhost:5000.

Native Python Installation

1. Clone the repository and enter the directory:

   git clone https://github.com/ovosimpatico/xtream2m3u.git
   cd xtream2m3u
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the server:

   python run.py
   

5. Open your browser and navigate to http://localhost:5000.

Usage

Web Interface

The easiest way to use xtream2m3u is via the web interface at http://localhost:5000.

1. Enter Credentials: Input your IPTV provider's URL, username, and password.
2. Select Content: Choose whether to include VOD (Movies & Series).
3. Filter Categories: Load categories and select which ones to include or exclude.
4. Generate: Click "Generate Playlist" to download your custom M3U file.

Environment Variables

• PROXY_URL: [Optional] Set a custom base URL for proxied content (useful if running behind a reverse proxy).
• PORT: [Optional] Port to run the server on (default: 5000).

API Documentation

For advanced users or automation, you can use the API endpoints directly.

1. Generate M3U Playlist

GET /m3u or POST /m3u

Parameter	Type	Required	Description
url	string	Yes	IPTV Service URL
username	string	Yes	IPTV Username
password	string	Yes	IPTV Password
unwanted_groups	string	No	Comma-separated list of groups to exclude
wanted_groups	string	No	Comma-separated list of groups to include (takes precedence)
include_vod	boolean	No	Set true to include Movies & Series (default: false)
nostreamproxy	boolean	No	Set true to disable stream proxying (direct links)
proxy_url	string	No	Custom base URL for proxied streams
include_channel_id	boolean	No	Set true to include epg_channel_id tag
channel_id_tag	string	No	Custom tag name for channel ID (default: channel-id)

Wildcard Support: unwanted_groups and wanted_groups support * (wildcard) and ? (single char).

• Example: *Sports* matches "Sky Sports", "BeIN Sports", etc.

Example:

http://localhost:5000/m3u?url=http://iptv.com&username=user&password=pass&wanted_groups=Sports*,News&include_vod=true

2. Generate XMLTV Guide

GET /xmltv

Parameter	Type	Required	Description
url	string	Yes	IPTV Service URL
username	string	Yes	IPTV Username
password	string	Yes	IPTV Password
proxy_url	string	No	Custom base URL for proxied images

3. Get Categories

GET /categories

Returns a JSON list of all available categories.

Parameter	Type	Required	Description
url	string	Yes	IPTV Service URL
username	string	Yes	IPTV Username
password	string	Yes	IPTV Password
include_vod	boolean	No	Set true to include VOD categories

4. Proxy Endpoints

• GET /image-proxy/<encoded_url>: Proxies images (logos, covers).
• GET /stream-proxy/<encoded_url>: Proxies video streams.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See the LICENSE file for details.

Disclaimer

xtream2m3u is a tool for managing your own legal IPTV subscriptions. It does not provide any content, channels, or streams. The developers are not responsible for how this tool is used.