How Xtream Codes Works — API, Credentials and Catch-up

“Xtream Codes” shows up in provider emails as if it were a brand of television. Technically it is closer to a contract between panels and apps: a base host, a username, a password, and a family of HTTP API actions that return live categories, VOD, series, provider EPG and sometimes TV archive. This guide explains those moving parts in plain language and how GridStreamr’s Xtream player uses them — without pretending GridStreamr is your content provider.

The three secrets in every Xtream email

Apps do not download a mysterious “Xtream file.” They call endpoints under that host using your username/password (or tokenised derivatives) and receive JSON (or similar) lists of categories and streams.

What the API typically exposes

Exact paths vary by panel family, but conceptually you get:

1. Authentication / account info — status, expiry, allowed outputs
2. Live TV — categories → channels → stream URLs
3. Movies (VOD) — categories → titles → info + playback
4. Series — shows → seasons → episodes
5. Provider EPG — now/next (and longer listings when the panel provides them)
6. TV archive / catch-up — optional replay windows per live channel
7. XMLTV helpers — many panels also publish a separate guide URL

GridStreamr maps those structures into Sources, the IPTV player, Smart Collections and Premium TimeShift.

Live TV flow (mental diagram)

Your app
  → GET live categories (auth)
  → GET streams in a category
  → User picks a channel
  → App requests / builds playback URL
  → Player (HLS/MPEG-TS/etc.) starts

If categories load but one channel fails, the failure is often upstream on that stream, not “Xtream is broken globally.”

VOD and series vs live

Live channels are continuous streams with optional archive. Movies/Series are on-demand titles the panel catalogs with metadata of uneven quality. That is why TMDB enrichment exists in GridStreamr — panels frequently ship empty posters and cryptic filenames.

EPG: Xtream provider guide vs XMLTV vs Global EPG

Xtream panels may offer:

• Provider EPG via the Xtream API (convenient, sometimes thin)
• A separate XMLTV URL (fuller schedules when maintained)

GridStreamr can also map channels to Global EPG so you are not stuck when panel guides are empty. Practical how-to: Add EPG to an IPTV playlist.

Catch-up / TV archive

When a panel enables archive on a channel, the API advertises that the channel has a replay window and how to request a past segment. GridStreamr Premium TimeShift turns that into a programme picker + scrubber + Back to Live control.

Details: How IPTV catch-up / TimeShift works.

No archive flag → no honest catch-up button. Apps that fake rewind without archive are guessing.

Xtream vs M3U (short version)

Full comparison: M3U vs Xtream Codes. Many households use both inside Smart Collections.

How GridStreamr uses Xtream specifically

When you tap Add Source → Xtream and save:

1. Credentials are stored for your GridStreamr account (treat the device like it holds secrets)
2. Categories and catalogs import into the Sources UI
3. You play directly or add channels into Smart Collections
4. EPG mapping and AI cleanup can improve presentation
5. Secure shares mint virtual credentials so family never sees the real panel password
6. Premium TimeShift talks to archive endpoints when present

Feature page: Xtream Codes. Setup: Android, iPhone, Android TV.

Multiple Xtream accounts

Premium users often keep complementary lines:

• Sports-heavy panel A
• Movies-heavy panel B

Connect both, merge into collections — combine multiple Xtream providers. Free includes a single Xtream account.

Security basics for Xtream credentials

1. Never post host+user+pass in public forums
2. Prefer virtual shares for family
3. Rotate panel passwords when a leak is suspected — then recreate shares
4. Beware phishing “panel login” pages
5. Remember: your GridStreamr password and Xtream password are different secrets

Panels, resellers and why quality varies

“Xtream-compatible” covers many panel codebases and reseller setups. That is why two “Xtream” emails behave differently:

• One has rich VOD metadata and 3-day archive
• Another has empty EPG and flaky DNS

The API pattern is shared; operations quality is not. GridStreamr can organize and play what the panel returns — it cannot fix an empty bouquet.

Troubleshooting map

What Xtream is not

• Not a legal shortcut around content rights
• Not the same as “a GridStreamr subscription” (pricing is for the app features)
• Not automatically available in every player (needs Xtream support)
• Not Android Automotive / CarPlay / a shipping Apple TV app by itself — those are client concerns on top of the API

Verification checklist (understanding + practice)

• You can explain host vs username vs password
• You know whether your panel includes VOD/series
• You know whether any channels advertise archive
• You have added the account in GridStreamr successfully
• You are not texting the real password to share access

Next reading

• Xtream Codes feature
• M3U vs Xtream Codes
• How IPTV catch-up works
• Combine multiple Xtream providers

Related reading

• Xtream Codes
• M3U player
• Smart Collections
• TimeShift
• Secure playlist sharing
• Documentation