xtream2m3u/README.md

xtream2m3u

Convert Xtream IPTV APIs into customizable M3U playlists with ease

About • Prerequisites • Installation • Usage • License • Disclaimer

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 provides a simple API that fetches live streams from Xtream IPTV services, filters out unwanted channel groups, and generates a customized M3U playlist file.

Why xtream2m3u?

Many IPTV providers use the Xtream API, which isn't directly compatible with media players that accept M3U playlists. xtream2m3u solves this problem by:

1. Connecting to Xtream API-based IPTV services
2. Fetching the list of available live streams
3. Allowing users to filter channels by including only wanted groups or excluding unwanted groups
4. Generating a standard M3U playlist that's compatible with a wide range of media players

Prerequisites

To use xtream2m3u, you'll need:

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

For deployment, you'll need one of the following:

• Docker and Docker Compose
• Python 3.12 or higher

Environment Variables

The application supports the following environment variables:

• PROXY_URL: [Optional] Set a default custom base URL for all proxied content (can be overridden with the proxy_url parameter)

Installation

Using Docker (Recommended)

1. Install Docker and Docker Compose
2. Clone the repository:

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

3. Run the application:

   docker-compose up -d
   

Native Python Installation

1. Install Python (3.9 or higher)
2. Clone the repository:

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

3. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
   

4. Install the required packages:

   pip install -r requirements.txt
   

5. Run the application:

   python run.py
   

Usage

API Endpoints

The application provides several endpoints for generating playlists and proxying media:

M3U Playlist Generation

GET /m3u

Query Parameters

• url (required): The base URL of your IPTV service
• username (required): Your IPTV service username
• password (required): Your IPTV service password
• unwanted_groups (optional): A comma-separated list of group names to exclude
• wanted_groups (optional): A comma-separated list of group names to include (takes precedence over unwanted_groups)
• nostreamproxy (optional): Set to 'true' to disable stream proxying
• proxy_url (optional): Custom base URL for proxied content (overrides auto-detection)
• include_channel_id (optional): Set to 'true' to include epg_channel_id in M3U, useful for Channels
• channel_id_tag (optional): Name of the tag to use for epg_channel_id data in M3U, defaults to channel-id

Note: For unwanted_groups and wanted_groups, you can use wildcard patterns with * and ? characters. For example:

• US* will match all groups starting with "US"
• *Sports* will match any group containing "Sports"
• US| ?/?/? will match groups like "US| 24/7"

Example Request

http://localhost:5000/m3u?url=http://your-iptv-service.com&username=your_username&password=your_password&unwanted_groups=news,sports

Or to only include specific groups:

http://localhost:5000/m3u?url=http://your-iptv-service.com&username=your_username&password=your_password&wanted_groups=movies,series

With a custom proxy URL:

http://localhost:5000/m3u?url=http://your-iptv-service.com&username=your_username&password=your_password&proxy_url=https://your-public-domain.com

XMLTV Guide Generation

GET /xmltv

Query Parameters

• url (required): The base URL of your IPTV service
• username (required): Your IPTV service username
• password (required): Your IPTV service password
• proxy_url (optional): Custom base URL for proxied content (overrides auto-detection)

Example Request

http://localhost:5000/xmltv?url=http://your-iptv-service.com&username=your_username&password=your_password

With a custom proxy URL:

http://localhost:5000/xmltv?url=http://your-iptv-service.com&username=your_username&password=your_password&proxy_url=https://your-public-domain.com

Image Proxy

GET /image-proxy/<encoded_image_url>

Proxies image requests, like channel logos and EPG images.

Stream Proxy

GET /stream-proxy/<encoded_stream_url>

Proxies video streams. Supports the following formats:

• MPEG-TS (.ts)
• HLS (.m3u8)
• Generic video streams

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). This license requires that any modifications to the code must also be made available under the same license, even when the software is run as a service (e.g., over a network). See the LICENSE file for details.

Disclaimer

xtream2m3u is a tool for generating M3U playlists from Xtream API-based IPTV services but does not provide IPTV services itself. A valid subscription to an IPTV service using the Xtream API is required to use this tool.

xtream2m3u does not endorse piracy and requires users to ensure they have the necessary rights and permissions. The developers are not responsible for any misuse of the software or violations of IPTV providers' terms of service.