Xtream Codes API: come funziona la connessione

Xtream Codes: un software diventato un protocollo

Xtream Codes era in origine il nome di un software commerciale per la gestione di server di diffusione video: permetteva a un operatore di gestire flussi, account dei clienti, categorie e statistiche da un pannello di amministrazione. Il software ha cessato di essere distribuito nel 2019, ma l'interfaccia di programmazione (API) che esponeva ai lettori è rimasta. Molti software per server l'hanno ripresa identica per restare compatibili con le app esistenti.

Come funziona una connessione Xtream Codes

Oggi «Xtream Codes» indica quindi soprattutto un modo standardizzato di connettersi: un lettore che «parla» questa API può collegarsi a qualsiasi server che la implementi. Non è un servizio, né un fornitore, né un contenuto. Come per una playlist M3U, la legalità dipende interamente dal servizio a cui vi connettete: un operatore che detiene i diritti di diffusione può benissimo usare questa API, mentre un servizio che ritrasmette canali senza autorizzazione resta illegale, quale che sia la tecnica impiegata.

Le tre informazioni di connessione

Un servizio compatibile fornisce al cliente tre elementi:

l'indirizzo del server, spesso accompagnato da una porta, per esempio http://serveur.exemple.fr:8080;
un nome utente (username);
una password.

La porta è il numero della «porta» su cui il server è in ascolto. Senza indicazione, http usa la porta 80 e https la porta 443; molti server di questo tipo usano altre porte come 8080 o 25461. Un errore frequente consiste nel dimenticare la porta o nell'incollare un percorso superfluo dopo l'indirizzo (/get.php, /c/…): l'app costruisce da sola i percorsi e si aspetta il solo indirizzo radice.

Che cosa inserite	Risultato
`http://serveur.exemple.fr:8080`	Corretto
`serveur.exemple.fr:8080`	Accettato dalla maggior parte dei lettori, che aggiungono `http://`
`http://serveur.exemple.fr` (porta dimenticata)	Fallimento se il server non è in ascolto sulla porta 80
`http://serveur.exemple.fr:8080/player_api.php`	Fallimento frequente: percorso aggiunto due volte
`https://` al posto di `http://`	Fallimento se il server non offre la cifratura su quella porta

Nome utente e password sono in genere sensibili alle maiuscole: «Martin» e «martin» sono due account diversi. Basta anche uno spazio copiato per errore alla fine di un campo a far fallire la connessione.

Che cosa accade alla connessione: player_api.php

Quando confermate i dati, il lettore invia una prima richiesta HTTP allo script player_api.php del server, con le vostre credenziali come parametri:

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

Il server risponde con un documento JSON (un formato di dati testuale strutturato) composto da due blocchi. Ecco una risposta semplificata:

{
  "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"
  }
}

Il blocco user_info descrive il vostro account, il blocco server_info descrive il server. Se auth vale 0, le credenziali sono rifiutate e il lettore mostra un errore di connessione. Se il server non risponde affatto, o restituisce una pagina HTML invece di JSON, il problema si colloca prima dell'autenticazione: indirizzo errato, porta chiusa, server offline o rete che blocca la connessione.

Le principali azioni dell'API

Una volta autenticato, il lettore carica il catalogo aggiungendo un parametro action allo stesso indirizzo. Ogni azione restituisce un elenco JSON. Le più usate sono le seguenti.

Azione	Che cosa restituisce
`get_live_categories`	Le categorie dei canali in diretta (identificatore e nome)
`get_live_streams`	I canali, eventualmente filtrati da `&category_id=`, con nome, logo, identificatore EPG
`get_vod_categories`	Le categorie di video on demand
`get_vod_streams`	I film disponibili, con locandina, voto, data di aggiunta ed estensione del file
`get_vod_info`	La scheda dettagliata di un film (`&vod_id=`): trama, durata, tracce
`get_series_categories`	Le categorie di serie
`get_series`	L'elenco delle serie
`get_series_info`	Le stagioni e gli episodi di una serie (`&series_id=`)
`get_short_epg`	I prossimi programmi di un canale (`&stream_id=`)

La guida completa dei programmi è invece disponibile in formato XMLTV tramite lo script xmltv.php, con le stesse credenziali. È uno dei vantaggi dell'API: il lettore non ha bisogno di un indirizzo di guida separato. Il funzionamento di questa guida è illustrato nel nostro articolo su EPG e XMLTV.

Come vengono poi riprodotti i video

Gli elenchi JSON non contengono i video, solo degli identificatori. Per avviare una riproduzione, il lettore costruisce un indirizzo secondo un modello fisso:

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

Per la diretta, l'estensione scelta (.ts per un flusso MPEG-TS continuo, .m3u8 per HLS) deve comparire nell'elenco allowed_output_formats dell'account. Per film ed episodi, l'estensione corrisponde al file effettivamente memorizzato sul server. Questi formati sono presentati in HLS, MPEG-TS e DASH.

Stato, scadenza e connessioni simultanee

Il blocco user_info contiene diversi campi utili per capire un rifiuto o un'interruzione.

Lo stato

Il campo status vale in genere Active. Altri valori come Expired, Banned o Disabled indicano che l'account non può più riprodurre contenuti, anche se la connessione stessa riesce. Il campo is_trial segnala un account di prova.

La data di scadenza

Il campo exp_date non è una data leggibile ma un timestamp Unix: il numero di secondi trascorsi dal 1° gennaio 1970 a mezzanotte UTC. Nell'esempio qui sopra, 1798761600 corrisponde al 1° gennaio 2027 alle 0:00 UTC. I lettori lo convertono in data per mostrarlo. Un valore vuoto o null significa in genere un account senza data di fine.

Le connessioni simultanee

max_connections indica quanti flussi possono essere riprodotti nello stesso momento con lo stesso account e active_cons quanti lo sono attualmente. Se il limite è 1 e un altro dispositivo di casa sta già guardando un canale, la nuova riproduzione fallisce o interrompe la precedente. Attenzione a una trappola comune: quando cambiate canale, la vecchia connessione impiega a volte qualche secondo a chiudersi lato server. Cambiare canale molto in fretta può quindi provocare brevemente un rifiuto per «troppe connessioni», che scompare da solo.

Xtream Codes o playlist M3U: le differenze

La maggior parte dei servizi compatibili propone anche una playlist M3U generata a partire dallo stesso account. I due metodi danno accesso allo stesso catalogo, ma non allo stesso modo.

Criterio	Connessione Xtream Codes	Playlist M3U
Caricamento	Per categoria, su richiesta	Un solo file, a volte molto voluminoso
Film e serie	Schede, locandine, stagioni ed episodi strutturati	Elenco piatto, spesso senza stagioni
Guida dei programmi	Fornita automaticamente	Indirizzo `url-tvg` da indicare
Informazioni sull'account	Scadenza e connessioni visibili	Nessuna
Server accettati	Solo quelli che implementano l'API	Qualsiasi fonte, compresi i vostri file

In sintesi, l'API è più comoda quando il servizio la offre, soprattutto per i cataloghi di film e serie; la playlist M3U è più universale. La sintassi delle playlist è spiegata in il formato M3U riga per riga, mentre l'inserimento dei due tipi di account in AICKO IPTV è descritto nella pagina Xtream Codes e M3U.

Sicurezza e diagnosi

Una particolarità di questa API merita di essere conosciuta: nome utente e password viaggiano nell'indirizzo di ogni richiesta e di ogni flusso. Su un server in semplice http transitano quindi in chiaro sulla rete. Alcune conseguenze pratiche:

non usate mai per questo account una password che impiegate altrove (posta, banca);
non pubblicate schermate o registri di errori che contengano un indirizzo di flusso completo: rivela le vostre credenziali;
preferite https quando il servizio lo offre (il campo https_port lo indica).

Per diagnosticare un fallimento, il metodo più efficace consiste nell'aprire l'indirizzo player_api.php?username=…&password=… in un browser, sulla stessa rete:

Nessuna risposta o tempo scaduto: indirizzo o porta errati, server spento o rete che blocca questa porta.
Risposta con "auth":0: nome utente o password errati.
Risposta con uno stato diverso da Active: account scaduto o sospeso, da verificare con il servizio.
Risposta corretta: la connessione funziona; se la riproduzione fallisce comunque, guardate dal lato del formato del flusso, della rete o della decodifica del dispositivo.

In sintesi

Xtream Codes è oggi un'API di connessione ripresa da molti server, non un servizio.
La connessione si basa su un indirizzo con porta, un nome utente e una password sensibili alle maiuscole.
Lo script player_api.php restituisce lo stato dell'account, poi il catalogo tramite azioni come get_live_streams o get_series.
exp_date è un timestamp Unix e max_connections limita le riproduzioni simultanee.
Le credenziali viaggiano negli indirizzi: usate una password unica.

Domande frequenti

Xtream Codes è legale?

La tecnica è neutra: è un'interfaccia di connessione tra un lettore e un server. Conta il servizio a cui vi collegate. Dovete detenere i diritti sui programmi che guardate; un servizio che ritrasmette canali a pagamento senza autorizzazione resta illegale.

Perché la connessione funziona su un dispositivo e non su un altro?

Verificate prima un errore di battitura, in particolare maiuscole o uno spazio finale. Se i dati inseriti sono identici, potrebbe essere stato raggiunto il limite di connessioni simultanee, oppure il secondo dispositivo si trova su una rete che blocca la porta usata dal server.

Come conoscere la data di scadenza del mio account?

La maggior parte dei lettori la mostra nelle informazioni del profilo. In alternativa, la risposta di player_api.php contiene il campo exp_date, un timestamp Unix che qualsiasi convertitore online trasforma in una data leggibile.

Bisogna inserire un indirizzo di guida TV con una connessione Xtream Codes?

In genere no: il lettore recupera la guida dallo stesso server. Un indirizzo di guida esterno serve solo se quella del servizio è vuota o incompleta.

Come funziona una connessione Xtream Codes