prateekrajgautam/telegram-hs-fu repository overview

⁠Telegram Home-Server File-Upload & Media Downloader

A self-hosted Telegram bot that watches your groups or chats for media URLs, downloads them to your server, and forwards them back as native Telegram media — videos play inline, photos show in gallery, audio streams directly. Built for home-server and NAS setups where you want a private, always-on download queue without any cloud dependency.

⁠What it does

Send any public video or audio URL to a Telegram group or chat where the bot is a member. The bot will:

1. Detect the URL automatically (no commands needed)
2. Download the media to a folder you specify on your server
3. Upload it back to the chat as a native Telegram video, audio, or photo
4. Optionally delete the local file after sending (with a configurable countdown and inline Keep / Delete buttons)

It handles multiple URLs at once using a background queue (3 concurrent downloads, up to 50 queued), so you can drop a batch of links and walk away.

⁠Supported sources

Works with any site supported by yt-dlp⁠, which covers several hundred platforms. Well-tested with:

• YouTube (videos and Shorts) — with MP3 audio extraction option
• Instagram (Reels, Posts, carousels/albums)
• Facebook (Reels, videos)
• TikTok
• Twitter / X
• HLS streams (.m3u8)
• Direct video URLs

⁠Use cases

• Jellyfin / Plex library building — download and organise content directly into your media server folders
• Family/group media archive — everyone in a group sends links; bot fetches and stores everything
• NAS automation — runs as a persistent Docker container alongside your other home-server services
• Offline viewing — queue downloads while on Wi-Fi, watch later without re-buffering

⁠Quick start (5 minutes)

⁠1. Create a Telegram bot

Talk to @BotFather⁠ on Telegram:

/newbot

Note down the Bot Token. Also get your API ID and API Hash from my.telegram.org⁠.

⁠2. Get your user ID

Talk to @userinfobot⁠ to find your numeric Telegram user ID.

⁠3. Create your working directory

mkdir telegram-hs-fu && cd telegram-hs-fu

⁠4. Create .env

Copy the template below and fill in your values:

# Telegram credentials — from my.telegram.org and @BotFather
API_ID=your_api_id
API_HASH=your_api_hash
BOT_TOKEN=your_bot_token

# Where downloaded files are saved on the host
BASE_DIR=/your/media/folder/
BASE_FOLDER=/your/media/folder/

# Only respond in this chat/group name (optional — remove to allow all)
ALLOWED_CHAT="your group name"

# Your personal Telegram numeric user ID (owner/admin)
OWNER_ID=your_numeric_user_id

⁠5. Create docker-compose.yml

services:
  HomeServerUploadTG:
    image: prateekrajgautam/telegram-hs-fu:latest
    restart: unless-stopped
    env_file:
      - ./.env
    user: "1000:100"
    volumes:
      - /your/media/folder/:/your/media/folder/   # must match BASE_FOLDER in .env
      - ./config:/src/config:rw                   # persistent state: session, settings, logs
    working_dir: /src
    stdin_open: true
    tty: true
    command: python3 main.py

⁠6. Initialise and start

# Create config directory with correct permissions
mkdir -p config
chmod 775 config
chown 1000:100 config

# Start the bot
docker compose up -d

# Watch startup logs
docker compose logs -f

You should see:

🤖 Telegram Download Bot Starting...
✅ Started download worker 1/3
✅ Started download worker 2/3
✅ Started download worker 3/3
🚀 Bot is ready!

⁠7. Add the bot to your group

Invite your bot to a Telegram group or just message it directly. Send any public video URL — the bot will start downloading immediately.

⁠Directory layout on the host

telegram-hs-fu/
├── .env                  ← your credentials (never commit this)
├── docker-compose.yml
└── config/               ← volume-mapped; survives container updates
    ├── bot.session           Telegram session (auto-created)
    ├── group_configs.json    per-group settings
    ├── uploaded_files.json   upload tracking
    └── bot_config.json       global bot config

⁠Configuration

⁠Interactive panel — /config

Send /config in any chat where the bot is active. You get a live inline-button panel:

⚙️ Group Config

📽 Quality: 720p
📦 Max size: 2000 MB
⏳ Delete countdown: 60s

[ 📽 Quality: 720p → tap to cycle ]
[ ⬇️ Auto DL: ✅ ON  |  🖼 Albums: ✅ ON  ]
[ 📤 As Media: ✅ ON  |  🗑 Auto Del: ✅ ON ]
[ 🔄 Refresh          |  ❌ Close           ]

Tap any button to toggle or cycle the setting instantly. Each group stores its own independent configuration.

⁠Quick config (send as a message)

quality=720p
maxsize=500
media=on
cleanup=on
cleanup_delay=60

⁠Command reference

⁠YouTube — MP3 or video?

When a YouTube link is detected, the bot shows an inline prompt:

🎵 YouTube detected — choose format (6s to auto-select video):
[ 🎵 MP3 audio  |  🎬 Video ]

Tap the button or wait — it auto-downloads as video after the timeout.

⁠Auto-delete with countdown

When Auto Del is on, after every successful send the bot posts:

🗑️ `My Video.mp4` will be deleted from server in 60s
[ ✅ Keep on server  |  🗑️ Delete now ]

• Tap Keep to cancel the deletion
• Tap Delete now to remove it immediately
• Do nothing — it deletes automatically after the countdown

This keeps your server clean without losing the file in Telegram.

⁠Volumes

The config/ directory is the only thing you need to back up to preserve all settings and the bot session.

⁠Updating

docker compose pull
docker compose down
docker compose up -d

Settings in config/ are preserved automatically.

⁠Permissions

The container runs as uid 1000, gid 100 (standard for most NAS systems like Synology and TrueNAS). If your system uses different ids, change user: "1000:100" in docker-compose.yml and adjust ownership of the config/ directory accordingly.

chown -R 1000:100 ./config
chmod -R 775 ./config

⁠Troubleshooting

Bot doesn't respond to URLs

• Check ALLOWED_CHAT in .env — remove it to allow all chats, or set it to the exact group name
• Make sure the bot is a member of the group

Session lost after update

• Check that ./config is correctly volume-mounted and owned by uid 1000

Download fails

• Try quality=best — some sources don't support resolution filtering
• Check that BASE_FOLDER exists and is writable by uid 1000

Files not deleting

• Verify cleanup=on is set for the group (/config)
• Check container logs: docker compose logs -f

⁠Open-source packages used

This image bundles several open-source tools and libraries, each under their own respective licence:

• yt-dlp⁠ — video and audio extraction engine (Unlicense)
• Telethon⁠ — Telegram MTProto client library for Python (MIT)
• FFmpeg⁠ — media processing and format conversion (LGPL / GPL depending on build)
• Python⁠ — runtime (PSF licence)
• python-dotenv⁠ — environment variable loading (BSD)
• aiohttp⁠ — async HTTP (Apache 2.0)
• aiofiles⁠ — async file I/O (Apache 2.0)

The source code for this bot is available at: github.com/prateekrajgautam/telegram-hs-fu⁠

⁠Credits

Built and maintained by prateekrajgautam / mGeek.in⁠

This project does not host, redistribute, or cache any third-party media content. All downloads are performed by the end user on their own hardware, for their own use, subject to the terms of service of each respective platform.

⁠Licence

MIT — see source repository for full licence text.