Comment fonctionne une connexion Xtream Codes (API expliquée)

Xtream Codes : un logiciel devenu un protocole

Xtream Codes était à l'origine le nom d'un logiciel commercial de gestion de serveurs de diffusion vidéo : il permettait à un opérateur de gérer des flux, des comptes clients, des catégories et des statistiques depuis un panneau d'administration. Le logiciel a cessé d'être distribué en 2019, mais l'interface de programmation (API) qu'il exposait aux lecteurs est restée. De nombreux logiciels de serveur l'ont reprise à l'identique afin de rester compatibles avec les applications existantes.

Aujourd'hui, « Xtream Codes » désigne donc surtout une manière standardisée de se connecter : un lecteur qui « parle » cette API peut se connecter à tout serveur qui l'implémente. Ce n'est ni un service, ni un fournisseur, ni un contenu. Comme pour une playlist M3U, la légalité dépend entièrement du service auquel vous vous connectez : un opérateur qui détient les droits de diffusion peut parfaitement utiliser cette API, tandis qu'un service qui rediffuse des chaînes sans autorisation reste illégal, quelle que soit la technique employée.

Les trois informations de connexion

Un service compatible fournit à son client trois éléments :

l'adresse du serveur, souvent accompagnée d'un port, par exemple http://serveur.exemple.fr:8080 ;
un identifiant (username) ;
un mot de passe (password).

Le port est le numéro de « porte » sur laquelle le serveur écoute. Sans indication, http utilise le port 80 et https le port 443 ; beaucoup de serveurs de ce type utilisent d'autres ports comme 8080 ou 25461. Une erreur fréquente consiste à oublier le port ou à coller un chemin superflu après l'adresse (/get.php, /c/…) : l'application construit elle-même les chemins et attend l'adresse racine seule.

Ce que vous saisissez	Résultat
`http://serveur.exemple.fr:8080`	Correct
`serveur.exemple.fr:8080`	Accepté par la plupart des lecteurs, qui ajoutent `http://`
`http://serveur.exemple.fr` (port oublié)	Échec si le serveur n'écoute pas sur le port 80
`http://serveur.exemple.fr:8080/player_api.php`	Échec fréquent : chemin ajouté deux fois
`https://` au lieu de `http://`	Échec si le serveur ne propose pas de chiffrement sur ce port

Identifiant et mot de passe sont en général sensibles à la casse : « Martin » et « martin » sont deux comptes différents. Un espace copié par erreur à la fin d'un champ suffit aussi à faire échouer la connexion.

Ce qui se passe à la connexion : player_api.php

Lorsque vous validez vos informations, le lecteur envoie une première requête HTTP au script player_api.php du serveur, avec vos identifiants en paramètres :

http://serveur.exemple.fr:8080/player_api.php?username=IDENTIFIANT&password=MOTDEPASSE

Le serveur répond par un document JSON (un format de données texte structuré) composé de deux blocs. Voici une réponse simplifiée :

{
  "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": "serveur.exemple.fr",
    "port": "8080",
    "https_port": "8443",
    "server_protocol": "http",
    "timezone": "Europe/Paris"
  }
}

Le bloc user_info décrit votre compte, le bloc server_info décrit le serveur. Si auth vaut 0, les identifiants sont refusés et le lecteur affiche une erreur de connexion. Si le serveur ne répond pas du tout, ou renvoie une page HTML au lieu de JSON, le problème se situe avant l'authentification : adresse erronée, port fermé, serveur hors ligne ou réseau qui bloque la connexion.

Les principales actions de l'API

Une fois authentifié, le lecteur charge le catalogue en ajoutant un paramètre action à la même adresse. Chaque action renvoie une liste JSON. Les plus utilisées sont les suivantes.

Action	Ce qu'elle renvoie
`get_live_categories`	Les catégories de chaînes en direct (identifiant et nom)
`get_live_streams`	Les chaînes, éventuellement filtrées par `&category_id=`, avec nom, logo, identifiant EPG
`get_vod_categories`	Les catégories de vidéos à la demande
`get_vod_streams`	Les films disponibles, avec affiche, note, date d'ajout et extension du fichier
`get_vod_info`	La fiche détaillée d'un film (`&vod_id=`) : résumé, durée, pistes
`get_series_categories`	Les catégories de séries
`get_series`	La liste des séries
`get_series_info`	Les saisons et épisodes d'une série (`&series_id=`)
`get_short_epg`	Les prochains programmes d'une chaîne (`&stream_id=`)

Le guide complet des programmes est, lui, disponible au format XMLTV via le script xmltv.php, avec les mêmes identifiants. C'est l'un des avantages de l'API : le lecteur n'a pas besoin d'une adresse de guide séparée. Le fonctionnement de ce guide est détaillé dans notre article sur l'EPG et XMLTV.

Comment les vidéos sont ensuite lues

Les listes JSON ne contiennent pas les vidéos, seulement des identifiants. Pour lancer une lecture, le lecteur construit une adresse selon un modèle fixe :

http://serveur:port/live/IDENTIFIANT/MOTDEPASSE/12345.ts
http://serveur:port/movie/IDENTIFIANT/MOTDEPASSE/67890.mkv
http://serveur:port/series/IDENTIFIANT/MOTDEPASSE/24680.mp4

Pour le direct, l'extension choisie (.ts pour un flux MPEG-TS continu, .m3u8 pour du HLS) doit figurer dans la liste allowed_output_formats du compte. Pour les films et épisodes, l'extension correspond au fichier réellement stocké sur le serveur. Ces formats sont présentés dans HLS, MPEG-TS et DASH.

Statut, expiration et connexions simultanées

Le bloc user_info contient plusieurs champs utiles pour comprendre un refus ou une coupure.

Le statut

Le champ status vaut généralement Active. D'autres valeurs comme Expired, Banned ou Disabled indiquent que le compte ne peut plus lire de contenu, même si la connexion elle-même aboutit. Le champ is_trial signale un compte d'essai.

La date d'expiration

Le champ exp_date n'est pas une date lisible mais un horodatage Unix : le nombre de secondes écoulées depuis le 1^er janvier 1970 à minuit UTC. Dans l'exemple ci-dessus, 1798761600 correspond au 1^er janvier 2027 à 0 h UTC. Les lecteurs le convertissent en date pour l'afficher. Une valeur vide ou null signifie en général un compte sans date de fin.

Les connexions simultanées

max_connections indique combien de flux peuvent être lus en même temps avec le même compte, et active_cons combien le sont actuellement. Si la limite est de 1 et qu'un autre appareil du foyer regarde déjà une chaîne, la nouvelle lecture échoue ou coupe la précédente. Attention à un piège courant : quand vous changez de chaîne, l'ancienne connexion met parfois quelques secondes à se fermer côté serveur. Zapper très vite peut donc déclencher brièvement un refus pour « trop de connexions », qui disparaît de lui-même.

Xtream Codes ou playlist M3U : les différences

La plupart des services compatibles proposent aussi une playlist M3U générée à partir du même compte. Les deux méthodes donnent accès au même catalogue, mais pas de la même manière.

Critère	Connexion Xtream Codes	Playlist M3U
Chargement	Par catégorie, à la demande	Un seul fichier, parfois très volumineux
Films et séries	Fiches, affiches, saisons et épisodes structurés	Liste plate, souvent sans saisons
Guide des programmes	Fourni automatiquement	Adresse `url-tvg` à renseigner
Informations du compte	Expiration et connexions visibles	Aucune
Serveurs acceptés	Uniquement ceux qui implémentent l'API	N'importe quelle source, y compris vos fichiers

En résumé, l'API est plus confortable quand le service la propose, surtout pour les catalogues de films et de séries ; la playlist M3U est plus universelle. La syntaxe des playlists est expliquée dans le format M3U ligne par ligne, et la saisie des deux types de comptes dans AICKO IPTV sur la page Xtream Codes et M3U.

Sécurité et diagnostic

Une particularité de cette API mérite d'être connue : l'identifiant et le mot de passe circulent dans l'adresse de chaque requête et de chaque flux. Sur un serveur en http simple, ils transitent donc en clair sur le réseau. Quelques conséquences pratiques :

n'utilisez jamais pour ce compte un mot de passe que vous employez ailleurs (messagerie, banque) ;
ne publiez pas de capture d'écran ou de journal d'erreurs contenant une adresse de flux complète : elle révèle vos identifiants ;
préférez https lorsque le service le propose (le champ https_port l'indique).

Pour diagnostiquer un échec, la méthode la plus efficace consiste à ouvrir l'adresse player_api.php?username=…&password=… dans un navigateur, sur le même réseau :

Aucune réponse ou délai dépassé : adresse ou port erronés, serveur arrêté, ou réseau qui bloque ce port.
Réponse avec "auth":0 : identifiant ou mot de passe incorrects.
Réponse avec un statut autre qu'Active : compte expiré ou suspendu, à voir avec le service.
Réponse correcte : la connexion fonctionne ; si la lecture échoue quand même, regardez du côté du format du flux, du réseau ou du décodage de l'appareil.

En résumé

Xtream Codes est aujourd'hui une API de connexion reprise par de nombreux serveurs, pas un service.
La connexion repose sur une adresse avec port, un identifiant et un mot de passe sensibles à la casse.
Le script player_api.php renvoie l'état du compte, puis le catalogue via des actions comme get_live_streams ou get_series.
exp_date est un horodatage Unix et max_connections limite les lectures simultanées.
Les identifiants circulent dans les adresses : utilisez un mot de passe unique.

Questions fréquentes

Xtream Codes est-il légal ?

La technique est neutre : c'est une interface de connexion entre un lecteur et un serveur. Ce qui compte est le service auquel vous vous connectez. Vous devez détenir les droits sur les programmes que vous regardez ; un service qui rediffuse des chaînes payantes sans autorisation reste illégal.

Pourquoi ma connexion fonctionne-t-elle sur un appareil et pas sur un autre ?

Vérifiez d'abord une faute de frappe, notamment la casse ou un espace final. Si les saisies sont identiques, la limite de connexions simultanées peut être atteinte, ou le second appareil est sur un réseau qui bloque le port utilisé par le serveur.

Comment connaître la date d'expiration de mon compte ?

La plupart des lecteurs l'affichent dans les informations du profil. Sinon, la réponse de player_api.php contient le champ exp_date, un horodatage Unix que n'importe quel convertisseur en ligne transforme en date lisible.

Faut-il saisir une adresse de guide TV avec une connexion Xtream Codes ?

En général non : le lecteur récupère le guide auprès du même serveur. Une adresse de guide externe n'est utile que si celui du service est vide ou incomplet.

Comment fonctionne une connexion Xtream Codes