Telegram-Stremio: turning Telegram channels into a Stremio library

Forward a file, get a permanent stream

The core idea is short enough to state in one sentence: you forward a movie or episode to your channel, and it instantly becomes a permanent, no-expiry streaming link, with posters, descriptions, seasons and episodes, just like a real streaming app.

Everything is managed from a web panel, with no coding and almost no bot commands, and the readme's framing is that this is a self-hosted media server that streams your Telegram files straight into Stremio or Nuvio.

The permanent link is the part that matters technically. A link that points directly at a file in a Telegram channel expires, because Telegram issues a temporary URL for the file and the client has to refresh it. A Stremio addon, by contrast, is asked for a stream URL at playback time and expects it to work. So something has to sit between the two, hold the channel credentials, and mint a fresh URL on demand, and that is what this service is. The readme lists ultra-fast permanent streaming links with no expiry as the first key feature.

The metadata is filled in from outside. Posters and details come automatically from IMDb and TMDb, and the dependency list confirms it, with themoviedb as an explicit dependency and guessit and parse-torrent-title for working out what a file actually is from its name. rapidfuzz is there for fuzzy matching, which is the same problem: a forwarded file called something like a season pack needs to be matched against a catalogue entry, and a fuzzy matcher is how you avoid a wrong confident match.

The licence is GPL-3.0, the language is Python, and the recent releases are v1.0.7 from 2026-10-09, v1.0.6 from 2026-09-24 and v1.0.4 from 2026-08-11, with the last push on 2026-10-15.

The server and the phone app solve different problems

There are two ways to run this, and the readme is careful to distinguish them, because they make different trade-offs.

The TeleStremio Android app runs the whole idea on your phone. No VPS, no Docker and no MongoDB. It logs into your Telegram, hosts a local Stremio addon, and streams your channels on demand. The APK is published on the GitHub releases page, and the setup is described as install the APK, log in with phone or QR, add your channels, turn the server on, and paste the addon URL into Stremio. For watching outside your home network, the app supports remote access through Tailscale.

The comparison table in the readme lays out the differences precisely. Hosting is your phone with zero setup against a VPS or Docker with MongoDB. Users are a single user, you, against multi-user with access tokens. The library is on-demand live search against a full indexed database. Catalogs are Cinemeta, giving Popular and Top Rated, against auto and custom catalogs with requests. Access control is absent in the app against subscriptions, tokens and an admin panel. Extras are absent against analytics, backups, announcements, a MediaFlow proxy and RPDB or Fanart support. Uptime is while the phone is on against 24/7. Remote access is via Tailscale against a public URL out of the box.

The readme's own summary is that the app suits watching your own Telegram files without hosting anything, and the full server suits multi-user sharing, subscriptions and always-on reliability.

That distinction is the important one for a decision. The app is a personal convenience with a real constraint attached to it, since a phone that sleeps is a library that stops answering. The server is infrastructure, and the cost of infrastructure is what the rest of the readme is about.

File naming is the interface, and the readme documents the rules

Because files arrive by being forwarded into a channel, the filename is the only metadata the system gets for free, and the readme spends a lot of space on the naming rules as a result.

Movies and TV shows are detected from the filename, with separate sections for each, and there are rules for split files with .001, .002 extensions and for combined or season-pack files. Those two cases are why parse-torrent-title is a dependency: a multi-part archive is a set of files that has to be recognised as one item and then joined and streamed as a single stream, and the readme lists split-file and multi-part playback as one stream, including .zip.001 split archives.

Subtitles follow the same logic, with filename rules and a manual add path, a list of supported subtitle filenames, and language name and code support. A subtitle is only useful if the player can select the right track, so the language handling is part of the media model rather than an afterthought.

There is also a manual path for files that do not follow any convention, described in the readme with examples like a trip, lectures and One Piece, which is the case of a recording rather than a release.

The naming rules are the real API of this project. If you rename a file when you forward it, the metadata lookup changes, and the readme has a section on fixing wrong metadata, which confirms that mismatches are common enough to need their own guidance. A separate section covers organizing your channels, which is the same problem one level up, since the channel a file sits in is part of how the catalogue is built.

Catalogues, special channels and the access model

The catalogue system is what turns a pile of forwarded files into something browsable.

Auto catalogues are generated, and custom catalogues are yours, with the readme explaining that you can organise by language, by platform or by your own lists. Then there are private and exclusive catalogues for premium content, and a section explaining how private, exclusive and searchable catalogues differ. That is the difference between a public list of everything and a list only your subscribers can see.

Four special channels have their own behaviour. The anime channel handles anime-aware metadata, which is a separate metadata path for a set of catalogues that the generic IMDb and TMDb lookups do not cover well. The global search channel searches across extra channels, and the readme notes it now also streams split and .zip archives. The announcement channel is for broadcasting to subscribers, and the skip channel is for excluding files from the index, which is the mechanism for the wrong metadata case and for content you do not want in a public catalogue.

Access control is the other half. The readme lists subscriptions and access control as a built-in feature, with each user token able to pick its own settings: quality sort order, filters for quality, and the ability to hide or reorder entries. Per-user settings on a shared library is a small detail that matters once more than one person uses the server.

The in-app Telegram login is worth calling out because it removes the usual first-run blocker. The readme describes connecting your user session from the settings page with phone, then code, then 2FA, with no manual session string to paste. Session strings are the classic way a Telegram client credential gets shared around, and the fact that this project does it through the settings page rather than asking you to paste a string into a config file is a meaningful difference in how likely it is to end up in a log or a screenshot.

Deployment, dependencies and the packaging

The packaging is a Docker image with a compose file, and the dependency set tells you what the project is made of.

The compose file builds the image locally and runs one service on port 8000, with the config.env file mounted into the container at /app/config.env, a restart policy of unless-stopped and json-file logging capped at one megabyte with three files kept. That logging cap is a small sign of care: a media server that indexes and streams will log a lot, and an unbounded log file on a small VPS is a common way to fill a disk.

The Dockerfile is built on the uv image, a Debian slim base, with build-essential, git, curl, ca-certificates and locales installed, and the app copied in and installed with uv lock followed by uv sync --locked. The start script is made executable and run as the command. Using uv means the lock file governs what actually gets installed, which is the right call for a service people run on their own machines.

The Python dependencies are worth reading as a description of the work. FastAPI and uvicorn for the HTTP layer, with uvloop and httptools for the event loop and the protocol parser. motor for the async MongoDB driver, which matches the MongoDB choice in the compose and deployment guides. pyrofork for Telegram, with tgcrypto for the client side crypto, and aiofiles for the file handling. themoviedb and pytz for metadata and time zones. jinja2 for templating, python-dotenv for the config file, itsdangerous for signing, python-multipart for form handling, zstandard for compression, and httpx and requests for outbound calls.

The deployment guides in the readme cover Heroku, a VPS which is marked as the recommended option, the free hosted options Koyeb, Render and orkestr, and optional Cloudflare streaming. There is also a heroku.yml and a render.yaml for the platform as a service routes, and the pyproject requires Python 3.11 or newer with a uv.lock committed.

Editorial conclusion

Adopt Telegram-Stremio if you keep your media in Telegram channels and want to watch it in Stremio or Nuvio without re-hosting files or juggling expiring links, and you are willing to run MongoDB and hold a Telegram user session. Do not adopt it if the files in your channels are not yours to stream, and think carefully about the session and token model before you put it in front of other people. Before you commit, read the first-time setup page for config.env, decide between the full server and the Android app, and check that the metadata sources it uses, IMDb and TMDb, cover the titles you actually watch.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. weebzone/Telegram-Stremio on GitHub