How an Xtream Codes Connection Works

Xtream Codes: software that became a protocol

Xtream Codes was originally the name of commercial software for managing video streaming servers: it let an operator manage streams, customer accounts, categories and statistics from an admin panel. The software stopped being distributed in 2019, but the programming interface (API) it exposed to players has remained. Many server programs have copied it exactly so as to stay compatible with existing apps.

Today, "Xtream Codes" therefore mostly means a standardized way of connecting: a player that "speaks" this API can connect to any server that implements it. It is not a service, a provider or content. As with an M3U playlist, legality depends entirely on the service you connect to: an operator that holds broadcasting rights can perfectly well use this API, while a service that rebroadcasts channels without permission remains illegal, whatever technique it uses.

The three pieces of connection information

A compatible service gives its customer three things:

• the server address, often with a port, for example http://server.example.com:8080;
• a username;
• a password.

The port is the number of the "door" the server listens on. With no indication, http uses port 80 and https uses port 443; many servers of this type use other ports such as 8080 or 25461. A frequent mistake is to forget the port or to paste a superfluous path after the address (/get.php, /c/...): the app builds the paths itself and expects the root address alone.

Username and password are generally case-sensitive: "John" and "john" are two different accounts. A space copied by mistake at the end of a field is also enough to make the connection fail.

What happens at login: player_api.php

When you confirm your details, the player sends a first HTTP request to the server's player_api.php script, with your credentials as parameters:

http://server.example.com:8080/player_api.php?username=USERNAME&password=PASSWORD

The server replies with a JSON document (a structured text data format) made of two blocks. Here is a simplified response:

{
  "user_info": {
    "auth": 1,
    "status": "Active",
    "exp_date": "1798761600",
    "is_trial": "0",
    "active_cons": "0",
    "max_connections": "1",
    "allowed_output_formats": ["m3u8", "ts"]
  },
  "server_info": {
    "url": "server.example.com",
    "port": "8080",
    "https_port": "8443",
    "server_protocol": "http",
    "timezone": "Europe/Paris"
  }
}

The user_info block describes your account, the server_info block describes the server. If auth is 0, the credentials are rejected and the player shows a connection error. If the server does not answer at all, or returns an HTML page instead of JSON, the problem lies before authentication: wrong address, closed port, server offline or a network blocking the connection.

The main API actions

Once authenticated, the player loads the catalog by adding an action parameter to the same address. Each action returns a JSON list. The most used are the following.

The full program guide is available in XMLTV format through the xmltv.php script, with the same credentials. This is one of the advantages of the API: the player does not need a separate guide address. How this guide works is detailed in our article on EPG and XMLTV.

How videos are then played

The JSON lists do not contain videos, only identifiers. To start playback, the player builds an address following a fixed pattern:

http://server:port/live/USERNAME/PASSWORD/12345.ts
http://server:port/movie/USERNAME/PASSWORD/67890.mkv
http://server:port/series/USERNAME/PASSWORD/24680.mp4

For live, the chosen extension (.ts for a continuous MPEG-TS stream, .m3u8 for HLS) must appear in the account's allowed_output_formats list. For movies and episodes, the extension matches the file actually stored on the server. These formats are presented in HLS, MPEG-TS and DASH.

Status, expiry and simultaneous connections

The user_info block contains several fields that help in understanding a refusal or a dropout.

The status

The status field is generally Active. Other values such as Expired, Banned or Disabled indicate that the account can no longer play content, even if the connection itself succeeds. The is_trial field flags a trial account.

The expiry date

The exp_date field is not a readable date but a Unix timestamp: the number of seconds elapsed since 1 January 1970 at midnight UTC. In the example above, 1798761600 corresponds to 1 January 2027 at 0:00 UTC. Players convert it into a date for display. An empty or null value generally means an account with no end date.

Simultaneous connections

max_connections indicates how many streams can be played at the same time with the same account, and active_cons how many currently are. If the limit is 1 and another device in the household is already watching a channel, the new playback fails or cuts the previous one. Beware of a common trap: when you change channel, the old connection sometimes takes a few seconds to close on the server side. Channel surfing very fast can therefore briefly trigger a "too many connections" refusal, which goes away by itself.

Xtream Codes or M3U playlist: the differences

Most compatible services also offer an M3U playlist generated from the same account. Both methods give access to the same catalog, but not in the same way.

In short, the API is more comfortable when the service offers it, especially for movie and series catalogs; the M3U playlist is more universal. Playlist syntax is explained in the M3U format line by line, and entering both types of account in AICKO IPTV is covered on the Xtream Codes and M3U page.

Security and troubleshooting

One particularity of this API deserves attention: the username and password travel in the address of each request and each stream. On a plain http server, they therefore pass in clear text over the network. A few practical consequences:

• never use for this account a password you use elsewhere (email, bank);
• do not post a screenshot or error log containing a full stream address: it reveals your credentials;
• prefer https when the service offers it (the https_port field says so).

To diagnose a failure, the most effective method is to open the address player_api.php?username=...&password=... in a browser, on the same network:

1. No response or timeout: wrong address or port, server stopped, or a network blocking that port.
2. Response with "auth":0: incorrect username or password.
3. Response with a status other than Active: expired or suspended account, to be sorted out with the service.
4. Correct response: the connection works; if playback still fails, look at the stream format, the network or the device's decoding.

In summary

• Xtream Codes is today a connection API copied by many servers, not a service.
• The connection relies on an address with a port, and a case-sensitive username and password.
• The player_api.php script returns the account state, then the catalog through actions such as get_live_streams or get_series.
• exp_date is a Unix timestamp and max_connections limits simultaneous playback.
• Credentials travel in addresses: use a unique password.

Frequently asked questions

Is Xtream Codes legal?

The technology is neutral: it is a connection interface between a player and a server. What matters is the service you connect to. You must hold the rights to the programs you watch; a service that rebroadcasts paid channels without permission remains illegal.

Why does my connection work on one device and not on another?

First check for a typo, especially letter case or a trailing space. If the entries are identical, the simultaneous connection limit may have been reached, or the second device is on a network that blocks the port the server uses.

How do I find my account's expiry date?

Most players show it in the profile information. Otherwise, the player_api.php response contains the exp_date field, a Unix timestamp that any online converter turns into a readable date.

Do I need to enter a TV guide address with an Xtream Codes connection?

Generally not: the player gets the guide from the same server. An external guide address is only useful if the service's own guide is empty or incomplete.