🚀 Introduction

A powerful, self-hosted Telegram Stremio Media Server built with FastAPI, MongoDB, and PyroFork — seamlessly integrated with Stremio for automated media streaming and discovery.

🧭 Quick Navigation

🚀 Introduction
- ✨ Key Features
⚙️ How It Works
🤖 Bot Commands
- Command List
- /set Command Usage
🔧 Configuration Guide
🚀 Deployment Guide
📺 Setting up Stremio
- 🌐 Add the Addon
- ⚙️ Optional: Remove Cinemeta
🏅 Contributor

🚀 Introduction

This project is a next-generation Telegram Stremio Media Server that allows you to stream your Telegram files directly through Stremio, without any third-party dependencies or file expiration issues. It’s designed for speed, scalability, and reliability, making it ideal for both personal and community-based media hosting.

✨ Key Features

⚙️ Multiple MongoDB Support
📡 Multiple Channel Support
⚡ Fast Streaming Experience
🔑 Multi Token Load Balancer
🎬 IMDB and TMDB Metadata Integration
♾️ No File Expiration
🧠 Admin Panel Support

⚙️ How It Works

This project acts as a bridge between Telegram storage and Stremio streaming, connecting Telegram, FastAPI, and Stremio to enable seamless movie and TV show streaming directly from Telegram files.

Overview

When you forward Telegram files (movies or TV episodes) to your AUTH CHANNEL, the bot automatically:

🗃️ Stores the message_id and chat_id in the database.
🧠 Processes file captions to extract key metadata (title, year, quality, etc.).
🌐 Generates a streaming URL through the PyroFork module — routed by FastAPI.
🎞️ Provides Stremio Addon APIs:
- /catalog → Lists available media
- /meta → Shows detailed information for each item
- /stream → Streams the file directly via Telegram

Upload Guidelines

To ensure proper metadata extraction and seamless integration with Stremio, all uploaded Telegram media files must include specific details in their captions.

🎥 For Movies

Example Caption:

Ghosted 2023 720p 10bit WEBRip [Org APTV Hindi AAC 2.0CH + English 6CH] x265 HEVC Msub ~ PSA.mkv

Required Fields:

🎞️ Name – Movie title (e.g., Ghosted)
📅 Year – Release year (e.g., 2023)
📺 Quality – Resolution or quality (e.g., 720p, 1080p, 2160p)

✅ Optional: Include codec, audio format, or source (e.g., WEBRip, x265, Dual Audio).

📺 For TV Shows

Example Caption:

Harikatha.Sambhavami.Yuge.Yuge.S01E04.Dark.Hours.1080p.WEB-DL.DUAL.DDP5.1.Atmos.H.264-Spidey.mkv

Required Fields:

🎞️ Name – TV show title (e.g., Harikatha Sambhavami Yuge Yuge)
📆 Season Number – Use S followed by two digits (e.g., S01)
🎬 Episode Number – Use E followed by two digits (e.g., E04)
📺 Quality – Resolution or quality (e.g., 1080p, 720p)

✅ Optional: Include episode title, codec, or audio details (e.g., WEB-DL, DDP5.1, Dual Audio).

🔁 Quality Replacement Logic

When you upload multiple files with the same quality label (like 720p or 1080p), the latest file automatically replaces the old one.

Example: If you already uploaded Ghosted 2023 720p and then upload another 720p version, the bot replaces the old file to keep your catalog clean and organized.

This helps avoid duplicate entries in Stremio and ensures only the most recent file is used.

🆙 Updating CAMRip or Low-Quality Files

If you initially uploaded a CAMRip or low-quality version, you can easily replace it with a better one:

Forward the new, higher-quality file (e.g., 1080p, WEB-DL) to your AUTH CHANNEL.
The bot will automatically detect and replace the old CAMRip file in the database.
The Stremio addon will then update automatically, showing the new stream source.

✅ No manual deletion or command is needed — forwarding the updated file is enough!

Behind The Scenes

Here's how each component interacts:

Component	Role
Telegram Bot	Handles uploads, forwards, and file tracking.
MongoDB	Stores message IDs, chat IDs, and metadata.
PyroFork	Generates Telegram-based streaming URLs.
FastAPI	Hosts REST endpoints for streaming, catalog, and metadata.
Stremio Addon	Consumes FastAPI endpoints for catalog display and playback.

📦 Flow Summary:

Telegram ➜ MongoDB ➜ FastAPI ➜ Stremio ➜ User Stream

🤖 Bot Commands

Below is the list of available bot commands and their usage within the Telegram bot.

Command List

Command	Description
`/start`	Returns your Addon URL for direct installation in Stremio.
`/log`	Sends the latest log file for debugging or monitoring.
`/set`	Used for manual uploads by linking IMDB URLs.
`/restart`	Restarts the bot and pulls any latest updates from the upstream repository.

`/set` Command Usage

The /set command is used to manually upload a specific Movie or TV show to your channel, linking it to its IMDB metadata.

Command:

/set <imdb-url>

Example:

/set https://m.imdb.com/title/tt665723

Steps:

Send the /set command followed by the IMDB URL of the movie or show you want to upload.
Forward the related movie or TV show files to your channel.
Once all files are uploaded, clear the default IMDB link by simply sending the /set command without any URL.

💡 Tip: Use /log if you encounter any upload or parsing issues.

🔧 Configuration Guide

All environment variables for this project are defined in the config.env file. A detailed explanation of each parameter is provided below.

🧩 Startup Config

Variable	Description
`API_ID`	Your Telegram API ID from my.telegram.org. Used for authenticating your Telegram session.
`API_HASH`	Your Telegram API Hash from my.telegram.org.
`BOT_TOKEN`	The main bot’s access token from @BotFather. Handles user requests and media fetching.
`HELPER_BOT_TOKEN`	Secondary bot token used to assist the main bot with tasks like deleting, editing, or managing.
`OWNER_ID`	Your Telegram user ID. This ID has full administrative access.
`REPLACE_MODE`	When `true`, new files replace existing files of the same quality. When `false`, multiple files of the same quality are allowed.

🗄️ Storage

Variable	Description
`AUTH_CHANNEL`	One or more Telegram channel IDs (comma-separated) where the bot is authorized to fetch or stream content. Example: `-1001234567890, -1009876543210`.
`DATABASE`	MongoDB Atlas connection URI(s). You must provide at least two databases, separated by commas (`,`) for load balancing and redundancy. Example: `mongodb+srv://user:pass@cluster0.mongodb.net/db1, mongodb+srv://user:pass@cluster1.mongodb.net/db2`

💡 Tip: Create your MongoDB Atlas cluster here.

🎬 API

Variable	Description
`TMDB_API`	Your TMDB API key from themoviedb.org. Used to fetch movie and TV metadata.

🌐 Server

Variable	Description
`BASE_URL`	The Domain or Heroku app URL (e.g. `https://your-domain.com`). Crucial for Stremio addon setup.
`PORT`	The port number on which your FastAPI server will run. Default: `8000`.

🔄 Update Settings

Variable	Description
`UPSTREAM_REPO`	GitHub repository URL for automatic updates.
`UPSTREAM_BRANCH`	The branch name to track in your upstream repo. Default: `master`.

🔐 Admin Panel

Variable	Description
`ADMIN_USERNAME`	Username for logging into the Admin Panel.
`ADMIN_PASSWORD`	Password for Admin Panel access.
⚠️ Change from default values for security.

🧰 Additional CDN Bots (Multi-Token System)

Variable	Description
`MULTI_TOKEN1`, `MULTI_TOKEN2`, ...	Extra bot tokens used to distribute traffic and prevent Telegram rate-limiting. Add each bot as an Admin in your `AUTH_CHANNEL`(s).

About `MULTI_TOKEN`

If your bot handles a high number of downloads/requests at a time, Telegram may limit your main bot.
To avoid this, you can use MULTI_TOKEN system:

Create multiple bots using @BotFather.
Add each bot as Admin in your AUTH_CHANNEL(s).
Add the tokens in your config.env as MULTI_TOKEN1, MULTI_TOKEN2, MULTI_TOKEN3, and so on.
The system will automatically distribute the load among all these bots!

🚀 Deployment Guide

This guide will help you deploy your Telegram Stremio Media Server using either Heroku or a VPS with Docker.

✅ Recommended Prerequisites

Supported Servers:

🟣 Heroku
🟢 VPS

Before you begin, ensure you have:

✅ A VPS with a public IP (e.g., Ubuntu on DigitalOcean, AWS, Vultr, etc.)
✅ A Domain name

🐙 Heroku Guide

Follow the instructions provided in the Google Colab Tool to deploy on Heroku.

🐳 VPS Guide

This section explains how to deploy your Telegram Stremio Media Server on a VPS using Docker Compose (recommended) or Docker.

1️⃣ Step 1: Clone & Configure the Project

git clone https://github.com/weebzone/Telegram-Stremio
cd Telegram-Stremio
mv sample_config.env config.env
nano config.env

Fill in all required variables in config.env.
Press Ctrl + O, then Enter, then Ctrl + X to save and exit.

⚙️ Step 2: Choose Your Deployment Method

You can deploy the server using either Docker Compose (recommended) or plain Docker.

🟢 Option 1: Deploy with Docker Compose (Recommended)

Docker Compose provides an easier and more maintainable setup, environment mounting, and restart policies.

🚀 Start the Container

docker compose up -d

Your server will now be running at: ➡️ http://<your-vps-ip>:8000

🛠️ Update `config.env` While Running

If you need to modify environment values (like BASE_URL, AUTH_CHANNEL, etc.):

Edit the file:
```
nano config.env
```
Save your changes: (Ctrl + O, Enter, Ctrl + X)
Restart the container to apply updates:
```
docker compose restart
```

⚡ Since the config file is mounted, you don’t need to rebuild the image — changes apply automatically on restart.

🔵 Option 2: Deploy with Docker (Manual Method)

If you prefer not to use Docker Compose, you can manually build and run the container.

🧩 Build the Image

docker build -t telegram-stremio .

🚀 Run the Container

docker run -d -p 8000:8000 telegram-stremio

Your server should now be running at: ➡️ http://<your-vps-ip>:8000

🌐 Step 3: Add Domain (Required)

🅰️ Set Up DNS Records

Go to your domain registrar and add an A record pointing to your VPS IP:

Type	Name	Value
A	@	`195.xxx.xxx.xxx`

🧱 Install Caddy (for HTTPS + Reverse Proxy)

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

⚙️ Configure Caddy

Edit the Caddyfile:
```
sudo nano /etc/caddy/Caddyfile
```
Replace contents with:
```
your-domain.com {
    reverse_proxy localhost:8000
}
```
- Replace your-domain.com with your actual domain name.
- Adjust the port if you changed it in config.env.
Save and reload Caddy:
```
sudo systemctl reload caddy
```

✅ Your API will now be available securely at: ➡️ https://your-domain.com

📺 Setting up Stremio

Follow these steps to connect your deployed addon to the Stremio app.

📥 Step 1: Download Stremio

Download Stremio for your device: 👉 https://www.stremio.com/downloads

👤 Step 2: Sign In

Create or log in to your Stremio account.

🌐 Step 3: Add the Addon

Open the Stremio App.
Go to the Addon Section (usually represented by a puzzle piece icon 🧩).
In the search bar, paste the appropriate addon URL:

Deployment Method	Addon URL
Heroku	`https://<your-heroku-app>.herokuapp.com/stremio/manifest.json`
Custom Domain	`https://<your-domain>/stremio/manifest.json`

⚙️ Optional: Remove Cinemeta

If you want to use only your Telegram Stremio Media Server addon for metadata and streaming, follow this guide to remove the default Cinemeta addon.

1️⃣ Step 1: Uninstall Other Addons

Go to the Addon Section in the Stremio App.
Uninstall all addons except your Telegram Stremio Media Server.
Attempt to remove Cinemeta. If Stremio prevents it, proceed to Step 2.

2️⃣ Step 2: Remove “Cinemeta” Protection

Log in to your Stremio account using Chrome or Chromium-based browser : 👉 https://web.stremio.com/
Once logged in, open your browser console (Ctrl + Shift + J on Windows/Linux or Cmd + Option + J on macOS).
Copy and paste the code below into the console and press Enter:

(function() {

	const token = JSON.parse(localStorage.getItem("profile")).auth.key;

    const requestData = {
        type: "AddonCollectionGet",
        authKey: token,
        update: true
    };

    fetch('https://api.strem.io/api/addonCollectionGet', {
        method: 'POST',
        body: JSON.stringify(requestData)
    })
    .then(response => response.json())
    .then(data => {

    if (data && data.result) {

        let result = JSON.stringify(data.result).substring(1).replace(/"protected":true/g, '"protected":false').replace('"idPrefixes":["tmdb:"]', '"idPrefixes":["tmdb:","tt"]');
            
        const index = result.indexOf("}}],");
            
        if (index !== -1) {
            result = result.substring(0, index + 3) + "}";
        }

		let addons = '{"type":"AddonCollectionSet","authKey":"' + token + '",' + result;

		fetch('https://api.strem.io/api/addonCollectionSet', {
    		method: 'POST',
			body: addons 
		})
      	.then(response => response.text())
      	.then(data => {
      		console.log('Success:', data);
      	})
      	.catch((error) => {
      		console.error('Error:', error);
      	});

        } else {
            console.error('Error:', error);
        }
    })
    .catch((error) => {
        console.error('Erro:', error);
    });
})();

3️⃣ Step 3: Confirm Success

Wait until you see this message in the console:
```
Success: {"result":{"success":true}}
```
Refresh the page (F5). You will now be able to remove Cinemeta from your addons list.

🏅 Contributor


`Karan`	`Stremio`	`ChatGPT`
Author	Stremio SDK	Refactor

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
Backend		Backend
.gitignore		.gitignore
.python-version		.python-version
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bump-version.py		bump-version.py
docker-compose.yaml		docker-compose.yaml
heroku.yml		heroku.yml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
sample_config.env		sample_config.env
start.sh		start.sh
update.py		update.py
uv.lock		uv.lock

License

weebzone/Telegram-Stremio

Folders and files

Latest commit

History

Repository files navigation

🧭 Quick Navigation

🚀 Introduction

✨ Key Features

⚙️ How It Works

Overview

Upload Guidelines

🎥 For Movies

📺 For TV Shows

🔁 Quality Replacement Logic

🆙 Updating CAMRip or Low-Quality Files

Behind The Scenes

🤖 Bot Commands

Command List

/set Command Usage

🔧 Configuration Guide

🧩 Startup Config

🗄️ Storage

🎬 API

🌐 Server

🔄 Update Settings

🔐 Admin Panel

🧰 Additional CDN Bots (Multi-Token System)

About MULTI_TOKEN

🚀 Deployment Guide

✅ Recommended Prerequisites

🐙 Heroku Guide

🐳 VPS Guide

1️⃣ Step 1: Clone & Configure the Project

⚙️ Step 2: Choose Your Deployment Method

🟢 Option 1: Deploy with Docker Compose (Recommended)

🚀 Start the Container

🛠️ Update config.env While Running

🔵 Option 2: Deploy with Docker (Manual Method)

🧩 Build the Image

🚀 Run the Container

🌐 Step 3: Add Domain (Required)

🅰️ Set Up DNS Records

🧱 Install Caddy (for HTTPS + Reverse Proxy)

⚙️ Configure Caddy

📺 Setting up Stremio

📥 Step 1: Download Stremio

👤 Step 2: Sign In

🌐 Step 3: Add the Addon

⚙️ Optional: Remove Cinemeta

1️⃣ Step 1: Uninstall Other Addons

2️⃣ Step 2: Remove “Cinemeta” Protection

3️⃣ Step 3: Confirm Success

🏅 Contributor

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages

`/set` Command Usage

About `MULTI_TOKEN`

🛠️ Update `config.env` While Running