GridStreamr logo

GridStreamr

IPTV OS

GridStreamr logo

GridStreamr

IPTV OS

Documentation

Master your GridStreamr experience.

Become an IPTV power user. Learn how to connect sources, build lightning-fast smart collections, and share your IPTV setup securely with your community.

Step 1

Getting started.

GridStreamr is designed to be cross-platform and intuitive. Follow these three steps to begin your journey.

Download from App Store or Google Play

Get GridStreamr from the App Store for iOS or Google Play for Android. Sign in with Apple, Google, or email to get started.

Choose your Theme

Select between light and dark mode to match your preference. Your theme choice syncs across all your devices automatically.

Configure your @username

Set up your unique username or user tag in the side menu Settings. This identifier is essential for other GridStreamr users to find you and share curated content with you directly.

Add your first playlist

Connect your first playlist by adding an Xtream Codes account or importing an M3U playlist. Free tier includes 1 Xtream account and 1 playlist to get you started.

TV

Sign in on Android TV.

GridStreamr for Android TV uses your phone to complete account sign-in: the TV shows a QR code, and the GridStreamr mobile app on the same account authorizes the TV. Typing passwords with a remote is not required.

qr_code_scanner
01

On your Android TV

  1. Open the GridStreamr app on your Android TV or Google TV device.
  2. From the sign-in screen, note the pairing code and the QR code (they encode the same device ID).
smartphone
02

On your phone

  1. Install GridStreamr on your iPhone or Android phone and sign in with the same GridStreamr account you want on the TV.
  2. Scan the TV's QR code with your phone camera (or open mylists.gridstreamr.com/activate and enter the on-screen code manually).
  3. When the browser redirects into the GridStreamr app, confirm the prompt to authorize this TV. Your TV will create its own session and finish signing in.
info
Phone not signed in yet?
If the link opens the app before you are logged in, sign in on the phone first, then scan the QR code again or revisit the activation page with the same code so the app can complete authorization.
Step 2

Manage your sources.

GridStreamr supports Xtream Codes and M3U URLs. Import your IPTV playlists and keep them all in one beautiful, organized library.

api
01
Free: 1 | Premium: ∞

Xtream Codes API

Connect via Host URL, username, and password. GridStreamr uses the Xtream API to fetch VOD metadata and real-time XMLTV EPG markers.

link
02
Free: 1 | Premium: ∞

Remote M3U Playlists

Paste a remote M3U8 link or upload local .m3u files. Streams are parsed for group-titles and automatically mapped to EPG channels.

public
03
40,000+ Channels

GridStreamr Global EPG

Exclusively for Smart Collections or reconfiguring existing XTREAM lists, access the new Global EPG source featuring 40,000+ integrated providers. Get real-time personalized alerts for live games and favorite shows.

search
04
Instant feedback

Fast Search

Search across all your connected sources simultaneously. Find the movie or channel you want in seconds, no matter which playlist it's in.

Step 3

The power of Smart Collections.

Mix and match entries from multiple sources to build your perfect custom lineup.

add_circle
01

Create your Smart Collection

You can create the Smart Collection first or do that on the go the first time you select entries to add to it.

playlist_add
02

Add entries

Select channels, movies, or series from any connected source to add to your Smart Collection. Use long press on any category, channel, movie, or series to quickly add it. You can add entries from multiple sources into one unified collection.

tune
03

Customize & EPG Sync

Rename and reorder channels and categories, update logos and use the 'Manage EPG' option to assign GridStreamr Global EPG sources to your channels, ensuring you always have the most accurate program information.

ios_share
04

Share your collection

Generated secure GridStreamr XTREAM URLs work in VLC, Kodi, or TiviMate. Your Smart Collection is compatible with any player supporting Xtream formats. You can also share it directly with other GridStreamr users via their @username for one-tap setup.

info
TMDB & OpenSubtitles integrations (Premium)
Connect your own TMDB API key to enrich movies and series in Smart Collections with posters, descriptions and ratings. Connect your OpenSubtitles credentials to search and download subtitles directly inside the player. Both are Premium features. See the Integrations & Player Settings section for full step-by-step instructions.
lightbulb
Pro tip
By swiping left on the list entries, you can rename categories and channels in your Smart Collection to make them uniquely yours. The changes only affect your curated collection, not the original source.
lightbulb
Quick add with long press
Use long press on any category, channel, movie, or series from any source to quickly add it to your Smart Collection. This streamlined workflow makes building your perfect lineup faster and more intuitive.
Step 4

Secure & Flexible Sharing.

Share your custom curation with others while keeping your main credentials private.

badge
01

Configure your @username

Set up your unique username or user tag in the side menu Settings. This identifier allows other GridStreamr users to find and share content with you directly. Your username becomes your sharing address for seamless collaboration.

person_add
02

Direct User Sharing

1. Configure your unique @username in Settings (side menu). 2. Go to your Smart Collection → Manage Shares. 3. Type the recipient's @username. 4. They'll receive a real-time notification and automatic configuration!

notifications_active
03

Real-time notifications

When someone shares a Smart Collection with you, you'll receive an instant push notification. Tap the notification to automatically add the shared collection to your list. You can also configure personalized EPG notifications for your favorite programs!

public
04

Universal Reach - External Players

Your curated Smart Collections work with any external media player that supports XTREAM Codes. Share with friends who use VLC, Kodi, TiviMate, or any other compatible player. Your collections are accessible everywhere!

shield
05

Secure by design

Shares use virtual credentials. Your main line username and password are NEVER exposed to the people you share with.

schedule
06

Flexible time limits

Set shares to expire in 24 hours, 7 days, any custom duration, or keep them forever. You can revoke any share instantly with one tap.

Step 5

Your Media Library.

Live TV, Movies, and Series organized for a premium viewing experience.

live_tv
01

Live TV & Guide

Browse categories or use the full-screen player. Free: Current/Next info. Premium: Full timeline view of the day's programming.

movie
02

Movies & Series

Enjoy rich metadata, posters, and season/episode organization. Resume watching any title across all your synced devices.

favorite
03

Favorites

Heart your top picks. Favorites grouped at the top of your list for instant access. Highly optimized for fast channel switching.

settings_suggest
04

Advanced Player (Premium)

Select from multiple audio tracks and subtitle languages. HD playback with automatic quality adjustment for patchy networks.

lightbulb
Account Sync
Your Favorites and Continue Watching lists are synced to the cloud. Start a movie on your iPhone and finish it on your Tablet without missing a beat.
Step 6

EPG Notifications Setup.

Never miss an important match or show again. Premium users can configure personalized alerts directly from the mobile app.

tune
01

Define Preferences

In the mobile app, navigate to EPG settings to add your favorite sports teams or specific program titles to your notification preferences.

notifications_active
02

Real-Time Alerts

GridStreamr monitors your customized global EPG catalog and will send you a push notification when a matching program is about to start.

lightbulb
Premium Feature
EPG Notification Alerts require an active Premium subscription. The notifications are powered by our massive 40,000+ channel Global EPG catalog to guarantee accuracy.
Step 7

Integrations & Player Settings.

Connect your own TMDB and OpenSubtitles accounts to unlock rich metadata and on-demand subtitles, and fine-tune the player to suit your viewing preferences.

movieTMDB, Movie & Series Metadata

key
01

Get your TMDB API key

  1. Create a free account at themoviedb.org
  2. Go to your profile → Settings → API
  3. Request a Developer API key (free)
  4. Copy the API Read Access Token or API Key (v3)
settings
02

Add the key in GridStreamr

  1. Open GridStreamr and tap the side menu
  2. Go to Settings → General
  3. Tap TMDB API Key and paste your key
  4. Your key syncs securely across all your signed-in devices
auto_awesome
03

Enrich your VOD library with TMDB

Once your API key is saved, GridStreamr automatically enriches movies and series in your Smart Collections with TMDB data, posters, backdrops, descriptions, ratings, cast and crew, and release year. Here is how it works:

  1. Open your Smart Collection and navigate to Movies or Series
  2. GridStreamr matches titles from your playlist against the TMDB database automatically
  3. Matched items show rich posters, descriptions and metadata in the detail view
  4. If a title is not matched automatically, tap the item and use Search on TMDB to manually select the correct match
info
Premium feature
TMDB enrichment requires an active Premium subscription. GridStreamr is not affiliated with TMDB and does not issue API keys. You are responsible for your key and for complying with TMDB's terms of use.

subtitlesOpenSubtitles, Subtitle Search & Download

key
01

Create an OpenSubtitles account

  1. Create a free account at opensubtitles.com
  2. Note your username and password, that is all you need
settings
02

Add credentials in GridStreamr

  1. Open GridStreamr and tap the side menu
  2. Go to Settings → General
  3. Tap OpenSubtitles and enter your Username and Password
  4. Your credentials sync securely across all your signed-in devices
search
03

Search and download subtitles while playing

  1. Start playing any movie or series episode in the GridStreamr player
  2. Tap the subtitles icon in the player controls
  3. Select Search OpenSubtitles, GridStreamr queries the database using the title and episode info automatically
  4. Pick the subtitle track you want from the results list (language, number of downloads, and rating are shown)
  5. The subtitle downloads and loads instantly without interrupting playback
info
Premium feature
OpenSubtitles subtitle search requires an active Premium subscription. A free OpenSubtitles account is all you need, just your username and password. You are responsible for complying with OpenSubtitles' terms of use.

format_sizeSubtitle Appearance

tune
01

Set your subtitle size in Settings

  1. Open the side menu and go to Settings → Subtitles
  2. Tap Subtitle Size
  3. Choose your preferred size, Small, Medium, Large, or Extra Large
  4. This becomes the default size applied to all subtitle tracks across every playback session
Step 8

AI Live Channels Enrichment.

From app version 2.0.4, enrichment uses GridStreamr-hosted AI and in-app AI credit packs, you no longer connect your own OpenAI or Gemini API key for this feature (that legacy path is documented below for older versions).

GridStreamr can automatically improve your Live TV channel information using AI. Standardise channel names, detect language, identify stream quality (SD, HD, FHD, 4K), classify content type, sports, news, movies, entertainment, music and more, and discover missing channel logos. Cleaner playlists, smarter search, no manual work required.

paymentsPremium & AI credits (2.0.4+)

workspace_premium
01

Get Premium and buy AI credit packs

  1. AI Live Channels Enrichment requires an active Premium subscription
  2. Purchase AI credit packs as in-app add-ons. Entry pricing starts at $0.99 USD for 500 credits (regional and store pricing may vary)
  3. When you run out of credits, the app will prompt you to top up, or you can open the paywall or store entry from the app, follow the on-screen purchase flow in the iOS or Google Play build
  4. Each enrichment run draws down your credit balance on our servers; you do not need an OpenAI or Google AI Studio account for the current flow

auto_awesomeRun channel enrichment

play_circle
02

Enrich your channels with AI

  1. Open any Smart Collection and go to the Live TV channel list
  2. Tap the ⋮ menu (top-right) and select Enrich with AI
  3. GridStreamr sends your channel metadata to GridStreamr-hosted AI; the run uses your AI credits
  4. The model returns standardised names, detected language, stream quality, content type, and discovered logos for each channel
  5. Review the suggestions, approve all at once or cherry-pick individual changes
  6. Confirmed changes apply to your Smart Collection only, your original source is never modified
info
Premium + credits
AI Live Channels Enrichment requires Premium. Usage is paid with in-app AI credit packs (e.g. from $0.99 for 500 credits); you are not asked to add third-party API keys in Settings for the 2.0.4+ flow. Pricing may vary by region and store.
lightbulb
Non-destructive by design
Enrichment suggestions are always shown for your review before anything is saved. Your original source playlist is never touched, all changes apply only to your Smart Collection copy.
Legacy: app 2.0.3 and earlier (bring your own OpenAI or Gemini API key)

The following was the setup through v2.0.3: you obtained API keys from Google AI Studio or OpenAI and saved them in GridStreamr. It remains here for users on old builds or for reference. v2.0.4 and later do not use this path for the hosted enrichment flow.

keyAI provider & API key setup (legacy)

smart_toy
01

Get a Gemini API key

1. Visit aistudio.google.com and sign in with your Google account. 2. Click Get API key → Create API key in new project. 3. Copy the generated key, you will paste it into GridStreamr.

psychology
02

Get an OpenAI API key

1. Visit platform.openai.com and sign in (or create a free account). 2. Go to Dashboard → API Keys → Create new secret key. 3. Give it a name (e.g. GridStreamr), copy the key immediately, it is only shown once.

settingsConfigure in GridStreamr (legacy)

tune
03

Add your API key in Settings

  1. Open GridStreamr and tap the side menu
  2. Go to Settings → General
  3. Tap AI Live Channels Enrichment
  4. Select your preferred AI provider: Gemini or OpenAI
  5. Paste your API key into the corresponding field and save
  6. Your key was stored securely and synced across signed-in devices
info
Legacy disclaimer
On versions that used this flow, you supplied your own keys and were responsible for compliance with your provider's terms. The current 2.0.4+ product uses hosted AI and in-app credit packs instead.
HowTo

HowTo Videos.

Watch our step-by-step guides to master GridStreamr's most powerful features.

Smart Collection Creation and Editplay_arrow

Smart Collection Creation and Edit

Learn how to build and customize your perfect IPTV lineup using GridStreamr's Smart Collection feature.

Watch on dedicated pagearrow_forward
Configure Smart Collection Sharesplay_arrow

Configure Smart Collection Shares

Master the art of sharing your curated playlists securely with other GridStreamr users and any other apps like TiviMate or IBOPlayer without sharing your main account credentials.

Watch on dedicated pagearrow_forward
FAQ

Frequently Asked Questions

01

Do my friends need GridStreamr to view shared playlists?

No! While sharing with GridStreamr users via @username is the fastest and easiest way (one-tap setup), you can also generate universal M3U links or configure similar to XTREAM credentials using your Smart Collection share token. These links work in any third-party player like VLC, Kodi, or TiviMate. Your friends get the same curated experience without needing to install our app.

02

Is sharing my playlist secure?

Completely. When you share a playlist, GridStreamr creates 'virtual credentials' (a unique Share Code and a secure Token) for the recipient. These act as an Xtream Codes username and password, masking your actual IPTV service details. Your original host, username, and password are NEVER shared or exposed. You also have total control: set expiration dates, limit access to specific content, or revoke shares instantly at any time.

03

How do I configure EPG for my Smart Collection?

In your Smart Collection settings, go to 'Manage EPG'. From there, you can select the new 'GridStreamr Global EPG' source, which provides data for hundreds of channels worldwide. This ensures your curated list always has a complete and accurate program guide, separate from your original source.

04

How do I use TMDB with Smart Collections?

GridStreamr supports integration with The Movie Database (TMDB) as a Premium feature for movies and series in Smart Collections. Create a free TMDB account, generate an API key in your TMDB account settings (profile → Settings → API), then open GridStreamr Settings → General and paste your key. GridStreamr automatically matches your playlist titles against TMDB to pull posters, descriptions and ratings. If a title is not matched automatically, tap the item and use Search on TMDB to pick the correct entry manually. GridStreamr does not supply TMDB API keys; you are responsible for your key and for compliance with TMDB’s terms.

05

How do I search and download subtitles?

GridStreamr integrates with OpenSubtitles as a Premium feature. Create a free account at opensubtitles.com, then open GridStreamr Settings → General, tap OpenSubtitles and enter your username and password. While a video is playing, tap the subtitles icon in the player controls and select Search OpenSubtitles. Pick your preferred language and track from the results, it downloads and loads instantly without interrupting playback. You are responsible for your account and for compliance with OpenSubtitles’ terms.

06

How do I use AI Live Channels Enrichment?

As of v2.0.4, AI Live Channels Enrichment is a Premium feature powered by GridStreamr-hosted AI. Purchase AI credit packs in the app (add-on packs from $0.99 for 500 credits; regional pricing may vary). You no longer add your own Gemini or OpenAI API key for this feature. Open any Smart Collection, go to the Live TV channel list, tap the ⋮ menu and select Enrich with AI. Enrichment uses credits and returns standardised names, detected language, stream quality, content type, and channel logos. You review suggestions before anything is applied, your original source playlist is never modified. (On app versions 2.0.3 and earlier, the app used a bring-your-own API key; see the AI Enrichment documentation for that legacy path.)

07

What is the difference between free and premium?

Free tier is perfect for getting started, allowing 1 Xtream account, 1 regular playlist, and 1 Smart Collection with current/next EPG info. Premium unlocks unlimited sources, full day EPG timelines, M3U file exports, Custom EPG Configuration, TMDB enrichment for Smart Collections, OpenSubtitles subtitle search, AI Live Channels Enrichment (including channel logo discovery; usage via optional in-app AI credit packs on current versions), and professional playback controls like audio track selection and subtitle size adjustment.

08

How does 'Continue Watching' work?

The app maintains a 'Resume' list across all your devices. When you stop a movie or series on one device, it appears at the top of your list on your others. The list helps you quickly find and restart your recent media.

09

Can I use GridStreamr on my TV?

Yes! The GridStreamr Android TV app signs in by linking your phone: scan the QR code on the TV with your phone to finish activation (see the Android TV login section on this page). You can also share Smart Collections to another IPTV player on your TV using secure M3U export or XTREAM-compatible credentials. A native tvOS app is in development.