Tgfilestream
A lightweight web server and Telegram client that acts as a proxy between Telegram servers and HTTP clients, allowing direct downloads of Telegram media files via HTTP.
Install / Use
/learn @SpringsFern/TgfilestreamREADME
tgfilestream
This project is released under the GNU AGPL v3 license.
You are free to use, modify, and distribute it — as long as you share your changes under the same license.
tgfilestream is a lightweight web server and Telegram client that acts as a proxy between Telegram servers and HTTP clients, allowing direct downloads of Telegram media files via HTTP.
📌 Check out TODO.md for the latest development progress and planned features.
📝 Notes
- If you want one without database checkout DeekshithSH/tgfilestream or simple branch
⚠ Database Migration
If you encounter the following error:
RuntimeError: Version mismatch detected. Old: X → New: Y
it means your database structure is outdated.
Please follow the migration instructions in:
You must run the migration script before starting the updated version.
🚀 Features
- Download Telegram media via HTTP links
- Fast, concurrent chunked downloading
🛠️ Setup
1. Clone the repository
git clone https://github.com/SpringsFern/tgfilestream.git
cd tgfilestream
2. Install dependencies
pip install -r requirements.txt
3. Create a .env file
Store the required environment variables in a .env file:
API_ID=1234567
API_HASH=1a2b3c4d5e6f7g8h9i0jklmnopqrstuv
BOT_TOKEN=1234567890:AAExampleBotTokenGeneratedHere
BIN_CHANNEL=-1002605638795
HOST=0.0.0.0
PORT=8080
PUBLIC_URL=http://127.0.0.1:8080
DB_BACKEND=mongodb
MONGODB_URI=mongodb://admin:pAswaRd@192.168.27.1
4. Run the server
python3 -m tgfs
⚙️ Environment Variables
| Variable | Required/Default | Description |
| -------------------- | ---------------------- | ---------------------------------------------------------------------------- |
| API_ID | ✅ | App ID from my.telegram.org |
| API_HASH | ✅ | API hash from my.telegram.org |
| BOT_TOKEN | ✅ | Bot token from @BotFather |
| BIN_CHANNEL | ✅ | Channel ID where files sent to the bot are stored |
| DB_BACKEND | mongodb | Which Database server to use. |
| HOST | 0.0.0.0 | Host address to bind the server (default: 0.0.0.0) |
| PORT | 8080 | Port to run the server on (default: 8080) |
| PUBLIC_URL | https://0.0.0.0:8080 | Public-facing URL used to generate download links |
| DEBUG | False | Show Extra Logs |
| CONNECTION_LIMIT | 5 | Number of connections to create per DC for a single client |
| DOWNLOAD_PART_SIZE | 1048576 (1MB) | Number of bytes to request in a single chunk |
| NO_UPDATE | False | Whether to reply to messages sent to the bot (True to disable replies) |
| NO_MAIN | False | Skip main bot and use only worker bots for Telegram file requests |
| SEQUENTIAL_UPDATES | False | Handle telegram updates sequentially |
| FILE_INDEX_LIMIT | 10 | Number of files to display at once with /files command |
| MAX_WARNS | 3 | Maximum number of warns before user get banned |
| ADMIN_IDS | None | User id of users who can use admin commands. Each id is seperated by , |
| ALLOWED_IDS | None | Only users with these IDs can use the bot. Separate multiple IDs with , |
Multi Token Environment Variables
| Variable | Required/Default | Description |
| -------------- | ---------------- | ---------------------------------------------------------------------------- |
| MULTI_TOKENx | ✅ | Use Multiple Telegram Clients when downloading files to avoid flood wait, Replace x with Number |
| | | Example: |
| MULTI_TOKEN1 | | MULTI_TOKEN1=1234567890:AAExampleBotTokenGeneratedHere|
| MULTI_TOKEN2 | | MULTI_TOKEN2=0987654321:AAExampleBotTokenGeneratedHere|
| MULTI_TOKEN3 | | MULTI_TOKEN3=5432167890:AAExampleBotTokenGeneratedHere|
MongoDB Environment Variables
Set the following variables if you choose MongoDB as the database in DB_BACKEND
| Variable | Required/Default | Description |
| ---------------- | ---------------- | --------------------- |
| MONGODB_URI | ✅ | MongoDB Database URI |
| MONGODB_DBNAME | TGFS | MongoDB Database name |
📂 Usage
Once the server is running, you can:
-
Access Telegram media files via HTTP:
-
Or simply send a file to your bot, and it will respond with a download link.
This will stream the file directly from Telegram servers to the client.
🛠️ Contributing & Reporting Issues
Found a bug or have a feature request? Please open an issue on GitHub.
🐞 Reporting Issues
When reporting a bug, please include:
- Steps to reproduce the issue
- Expected behavior vs actual behavior
- Relevant logs, screenshots, or error messages (if any)
- Environment details (OS, Python version, etc.)
Example issue title:
[Bug] Download fails for large files
💡 Requesting Features
When suggesting a new feature, please include:
- A clear and concise description of the feature
- The motivation or use case for it
- Expected behavior (input/output examples if applicable)
- Any alternatives you've considered
Example feature title:
[Feature] Add support for viewing generated links
Contributions are welcome!
Feel free to fork the project and open a pull request.
🔍 Note: Make sure to test your code thoroughly before submitting a PR to help maintain stability and performance.
💡 Credits
- Deekshith SH – Me
- Tulir – Original author of
tgfilestream, whose code inspired this project and is referenced inparalleltransfer.py
