Xtream Codes API - Dispatcharr

Overview

Dispatcharr provides Xtream Codes API compatibility, allowing IPTV players and applications that support the Xtream Codes protocol to connect to Dispatcharr as if it were an Xtream Codes server. This enables compatibility with popular IPTV applications like:

TiviMate
IPTV Smarters
Perfect Player
GSE Smart IPTV
Kodi (via Xtream Codes add-ons)
And many more

What is Xtream Codes?

Xtream Codes is a popular IPTV management panel protocol that provides:

User authentication
Channel categorization
EPG data
VOD (Video on Demand) content
Series/TV show management
Standardized API endpoints

Many IPTV applications have built-in Xtream Codes support, making it a de facto standard for IPTV services.

Xtream Codes API Implementation

Dispatcharr implements the Xtream Codes API with the following features: ✅ Live Streams API - Browse and play live TV channels ✅ VOD API - Access movies and video content ✅ Series API - Browse TV shows and episodes ✅ Category Management - Organize content by categories ✅ User Authentication - Secure access using Dispatcharr accounts ✅ EPG Integration - Electronic program guide data ✅ Stream URLs - Compatible stream formats Implementation Reference: core/xtream_codes.py

Connection Setup

To connect an Xtream Codes-compatible player to Dispatcharr:

Get Connection Details

You’ll need:

Server URL: Your Dispatcharr server address
Username: Your Dispatcharr username
Password: Your Dispatcharr password

Server: http://YOUR_SERVER_IP:9191
Username: your_username
Password: your_password

The server URL should NOT include /player_api.php - most apps add this automatically.

Configure Your IPTV App

In your IPTV application:

Select Xtream Codes API or Xtream Codes Login
Enter the server URL (without trailing slash)
Enter your Dispatcharr username
Enter your Dispatcharr password
Save and connect

Verify Connection

After connecting, your app should:

Authenticate successfully
Load channel categories
Display live channels
Show EPG data (if configured)

API Endpoints

Dispatcharr provides these Xtream Codes-compatible endpoints:

Authentication & Account Info

Endpoint: GET /player_api.php Parameters:

username - User’s username
password - User’s password

Response:

{
  "user_info": {
    "username": "your_username",
    "password": "your_password",
    "message": "",
    "auth": 1,
    "status": "Active",
    "exp_date": "1735689600",
    "is_trial": "0",
    "active_cons": "1",
    "created_at": "1609459200",
    "max_connections": "5",
    "allowed_output_formats": ["m3u8", "ts"]
  },
  "server_info": {
    "url": "YOUR_SERVER_IP",
    "port": "9191",
    "https_port": "9191",
    "server_protocol": "http",
    "rtmp_port": "1935",
    "timezone": "UTC",
    "timestamp_now": 1640000000,
    "time_now": "2024-01-01 12:00:00"
  }
}

Implementation: core/xtream_codes.py:authenticate() (line 116-137)

Get Live Categories

Endpoint: GET /player_api.php?username=XXX&password=XXX&action=get_live_categories Returns all live TV channel categories. Response:

[
  {
    "category_id": "1",
    "category_name": "Sports",
    "parent_id": 0
  },
  {
    "category_id": "2",
    "category_name": "News",
    "parent_id": 0
  }
]

Implementation: core/xtream_codes.py:get_live_categories() (line 180-206)

Get Live Streams

Endpoint: GET /player_api.php?username=XXX&password=XXX&action=get_live_streams Optional Parameter: category_id - Filter by category Returns all live channels or channels in a specific category. Response:

[
  {
    "num": 1,
    "name": "ESPN HD",
    "stream_type": "live",
    "stream_id": 123,
    "stream_icon": "http://YOUR_SERVER/logo/espn.png",
    "epg_channel_id": "espn.us",
    "added": "1609459200",
    "category_id": "1",
    "custom_sid": "",
    "tv_archive": 0,
    "direct_source": "",
    "tv_archive_duration": 0
  }
]

Implementation: core/xtream_codes.py:get_all_live_streams() (line 236-262)

Stream URL Format

Live Stream URL: http://YOUR_SERVER:9191/live/{username}/{password}/{channel_id} Example:

http://192.168.1.100:9191/live/myuser/mypass/123

Implementation: core/xtream_codes.py:get_stream_url() (line 264-266)

Get VOD Categories

Endpoint: GET /player_api.php?username=XXX&password=XXX&action=get_vod_categories Returns all VOD (movies) categories. Implementation: core/xtream_codes.py:get_vod_categories() (line 276-301)

Get VOD Streams

Endpoint: GET /player_api.php?username=XXX&password=XXX&action=get_vod_streams Optional Parameter: category_id - Filter by category Returns all VOD content. Response:

[
  {
    "num": 1,
    "name": "Movie Title",
    "stream_type": "movie",
    "stream_id": 456,
    "stream_icon": "http://YOUR_SERVER/poster/movie.jpg",
    "rating": "8.5",
    "rating_5based": 4.25,
    "added": "1609459200",
    "category_id": "10",
    "container_extension": "mp4",
    "custom_sid": "",
    "direct_source": ""
  }
]

Implementation: core/xtream_codes.py:get_vod_streams() (line 303-331)

VOD Stream URL Format

VOD Stream URL: http://YOUR_SERVER:9191/movie/{username}/{password}/{stream_id}.{ext} Example:

http://192.168.1.100:9191/movie/myuser/mypass/456.mp4

Implementation: core/xtream_codes.py:get_vod_stream_url() (line 272-274)

Get Series Categories

Endpoint: GET /player_api.php?username=XXX&password=XXX&action=get_series_categories Returns all TV series categories. Implementation: core/xtream_codes.py:get_series_categories() (line 361-386)

Get Series

Endpoint: GET /player_api.php?username=XXX&password=XXX&action=get_series Optional Parameter: category_id - Filter by category Returns all TV series. Implementation: core/xtream_codes.py:get_series() (line 388-416)

Get Series Info

Endpoint: GET /player_api.php?username=XXX&password=XXX&action=get_series_info&series_id=XXX Returns detailed information about a series including all episodes. Response:

{
  "info": {
    "name": "Series Name",
    "cover": "http://YOUR_SERVER/cover.jpg",
    "plot": "Series description",
    "cast": "Actor 1, Actor 2",
    "director": "Director Name",
    "genre": "Drama",
    "releaseDate": "2020-01-01",
    "rating": "8.5",
    "category_id": "5"
  },
  "episodes": {
    "1": [
      {
        "id": "789",
        "episode_num": 1,
        "title": "Episode 1",
        "container_extension": "mp4",
        "info": {
          "duration": "3600",
          "plot": "Episode description"
        }
      }
    ]
  }
}

Implementation: core/xtream_codes.py:get_series_info() (line 418-444)

Episode Stream URL Format

Episode URL: http://YOUR_SERVER:9191/series/{username}/{password}/{episode_id}.{ext} Example:

http://192.168.1.100:9191/series/myuser/mypass/789.mp4

Implementation: core/xtream_codes.py:get_episode_stream_url() (line 268-270)

XMLTV EPG

Endpoint: GET /xmltv.php?username=XXX&password=XXX Returns EPG data in XMLTV format for authenticated users. Implementation: apps/output/views.py:generate_m3u() (line 186-191)

Application-Specific Setup

TiviMate

Add Playlist

Open TiviMate
Go to Settings → Playlists
Click Add Playlist
Select Xtream Codes API

Enter Details

Name: Dispatcharr (or any name)
Server URL: http://YOUR_SERVER_IP:9191
Username: Your Dispatcharr username
Password: Your Dispatcharr password

Configure EPG

TiviMate will automatically fetch EPG from:

http://YOUR_SERVER_IP:9191/xmltv.php?username=XXX&password=XXX

IPTV Smarters Pro

Select Login Type

Open IPTV Smarters Pro
Select Login with Xtream Codes API

Enter Credentials

Server URL: http://YOUR_SERVER_IP:9191
Username: Your username
Password: Your password
Name: Dispatcharr

Load Content

App will load:

Live TV channels
VOD movies
TV series
EPG data

Perfect Player IPTV

Add Playlist

Open Perfect Player
Settings → Playlists
Add Playlist → Xtream Codes

Configure

Server: http://YOUR_SERVER_IP:9191
User: Your username
Password: Your password

GSE Smart IPTV

Add Source

Open GSE Smart IPTV
Go to Remote Playlists
Click + to add new source

Select Xtream Codes

Select Xtream Codes API
Name: Dispatcharr
URL: http://YOUR_SERVER_IP:9191
Username: Your username
Password: Your password

M3U vs Xtream Codes

Feature	M3U Playlist	Xtream Codes API
Authentication	URL-based	Username/Password
Categories	Group titles	Native category support
VOD	Limited	Full support with metadata
Series	Not supported	Native support
EPG	Separate XMLTV	Integrated
Updates	Manual refresh	Dynamic
User Management	URL-based	User accounts
App Support	Universal	Xtream-compatible apps

User Management

Xtream Codes API uses Dispatcharr’s user authentication system:

Creating API Users

Create User Account

In Dispatcharr:

Go to Settings → Users
Click Add User
Set username and password
Configure permissions
Assign channel profiles (optional)

Set Access Permissions

Configure what the user can access:

Live TV channels
VOD content
Series content
Channel profiles
User level restrictions

Provide Credentials

Give the user:

Server: http://YOUR_SERVER:9191
Username: [created_username]
Password: [created_password]

User-Specific Content

Xtream Codes API respects Dispatcharr’s user permissions:

Channel Profiles: Users only see channels from assigned profiles
User Levels: Content filtered by user access level
Adult Content: Can be hidden per user preference
Concurrent Streams: Controlled by max connections setting

Implementation: apps/output/views.py:generate_m3u() (line 130-156)

Authentication Flow

The Xtream Codes client connects to Dispatcharr:

def authenticate(self):
    """Authenticate and validate server response"""
    endpoint = "player_api.php"
    params = {
        'username': self.username,
        'password': self.password
    }
    
    self.server_info = self._make_request(endpoint, params)
    
    if not self.server_info or not self.server_info.get('user_info'):
        raise ValueError("Authentication failed: Invalid response")
    
    return self.server_info

Troubleshooting

Authentication Failed

Ensure you’re using your Dispatcharr username and password, not the original IPTV provider credentials.

Check:

Username and password are correct
User account is active in Dispatcharr
User has necessary permissions
Server URL is correct (no trailing slash)

Test:

curl "http://YOUR_SERVER:9191/player_api.php?username=USER&password=PASS"

No Channels Showing

Verify:

User has assigned channel profiles OR has access to all channels
Channels are enabled in Dispatcharr
User level permits access to channels
Categories are properly configured

Test Categories:

curl "http://YOUR_SERVER:9191/player_api.php?username=USER&password=PASS&action=get_live_categories"

Streams Won’t Play

Check:

Stream URL format is correct
Source stream is accessible
Stream profile is configured properly
Network connectivity between client and server

Test Stream URL:

curl "http://YOUR_SERVER:9191/live/USER/PASS/CHANNEL_ID" -I

EPG Not Loading

Verify:

EPG sources configured in Dispatcharr
EPG data has been fetched
Channels are mapped to EPG data
XMLTV endpoint is accessible

Test EPG:

curl "http://YOUR_SERVER:9191/xmltv.php?username=USER&password=PASS" | head -n 50

Connection Timeout

Common Causes:

Firewall blocking port 9191
Docker network misconfiguration
Wrong server IP/hostname
Reverse proxy issues

Verify Connectivity:

telnet YOUR_SERVER 9191
# or
nc -zv YOUR_SERVER 9191

Security Considerations

Authentication Security

Credentials are passed in URL parameters (HTTP)
Use HTTPS/reverse proxy for encrypted transmission
Implement network-based access controls
Use strong passwords
Limit concurrent connections per user

Reverse Proxy with SSL

server {
    listen 443 ssl;
    server_name dispatcharr.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://dispatcharr:9191;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Then use: https://dispatcharr.yourdomain.com as server URL.

Advanced Features

Custom User Agent

The Xtream Codes client supports custom user agents:

client = Client(
    server_url="http://YOUR_SERVER:9191",
    username="user",
    password="pass",
    user_agent="CustomApp/1.0"
)

Implementation: core/xtream_codes.py:Client.__init__() (line 11-31)

Session Management

Dispatcharr uses persistent HTTP sessions for efficiency:

self.session = requests.Session()
self.session.headers.update({'User-Agent': user_agent_string})

adapter = requests.adapters.HTTPAdapter(
    pool_connections=1,
    pool_maxsize=2,
    max_retries=3,
    pool_block=False
)
self.session.mount('http://', adapter)
self.session.mount('https://', adapter)

Implementation: core/xtream_codes.py (line 29-41)

Getting Started

Core Features

Integrations

Configuration

Advanced

Deployment

​Overview

​What is Xtream Codes?

​Xtream Codes API Implementation

​Connection Setup

​API Endpoints

​Authentication & Account Info

​Get Live Categories

​Get Live Streams

​Stream URL Format

​Get VOD Categories

​Get VOD Streams

​VOD Stream URL Format

​Get Series Categories

​Get Series

​Get Series Info

​Episode Stream URL Format

​XMLTV EPG

​Application-Specific Setup

​TiviMate

​IPTV Smarters Pro

​Perfect Player IPTV

​GSE Smart IPTV

​M3U vs Xtream Codes

​User Management

​Creating API Users

​User-Specific Content

​Authentication Flow

​Troubleshooting

​Authentication Failed

​No Channels Showing

​Streams Won’t Play

​EPG Not Loading

​Connection Timeout

​Security Considerations

​Authentication Security

​Reverse Proxy with SSL

​Advanced Features

​Custom User Agent

​Session Management

​Related Resources

Overview

What is Xtream Codes?

Xtream Codes API Implementation

Connection Setup

API Endpoints

Authentication & Account Info

Get Live Categories

Get Live Streams

Stream URL Format

Get VOD Categories

Get VOD Streams

VOD Stream URL Format

Get Series Categories

Get Series

Get Series Info

Episode Stream URL Format

XMLTV EPG

Application-Specific Setup

TiviMate

IPTV Smarters Pro

Perfect Player IPTV

GSE Smart IPTV

M3U vs Xtream Codes

User Management

Creating API Users

User-Specific Content

Authentication Flow

Troubleshooting

Authentication Failed

No Channels Showing

Streams Won’t Play

EPG Not Loading

Connection Timeout

Security Considerations

Authentication Security

Reverse Proxy with SSL

Advanced Features

Custom User Agent

Session Management

Related Resources