📺 TelePlay

Your personal, self-hosted media server — powered by Telegram.

Stream and manage your Telegram files on any device — TV, Mobile, or Browser — without downloading the entire file. TelePlay uses Telegram as unlimited cloud storage and streams content on-demand at high speed using its multi-client parallel download technology. Upload via a Telegram Bot, organize through a Web App, and watch anywhere.

---

✨ Features

🤖 Telegram Bot — Full Command List

• Upload any file type (video, audio, documents, photos)
• Organize files into folders with inline buttons
• Rename, move, and delete files via chat commands
• Search your library with /myfiles
• Get an auto-login web link with /web

🌐 Web App — Login Methods

• Full file browser with folder navigation
• Multi-select, batch delete, rename, and move operations
• Context menu (right-click) on files
• Inline video/audio player with seeking
• Three login methods (direct link, login code, remote authorization)
• Responsive — works on desktop and mobile

📺 Android TV & Mobile App — Installation Guide

• Designed for TV with D-Pad / remote control navigation
• Continue Watching and Recently Added rows on the home screen
• Full-screen ExoPlayer playback with transport controls
• Download files for offline playback (Mobile)
• Picture-in-Picture mode (Mobile)
• Watch progress automatically synced with the server

⚡ Platform — Architecture Overview

• Zero local storage — all files live on Telegram's unlimited cloud
• Multi-user — each Telegram user gets an isolated library
• High-speed streaming — optional multi-bot parallel downloads
• Restricted access — whitelist allowed users with AUTH_USERS
• Public sharing — generate signed, time-limited links
• One-command deploy — Docker Compose, Railway, Render, or CapRover

---

🏗️ How It Works

  You                Telegram Cloud              Your Server              Your Devices
  ───                ──────────────              ───────────              ────────────
   │                                                  │
   │  1. Send file to Bot ──────────────────────────► │
   │                         2. Bot forwards to  ───► │ (Private Channel)
   │                            Storage Channel       │
   │                                                  │ 3. Saves metadata
   │                                                  │    to Database
   │                                                  │
   │  4. Open Web / TV App ◄──────────────────────────│
   │                                                  │
   │  5. Press Play ──────────────────────────────► │
   │                         6. Fetches chunks   ◄──  │ (from Telegram)
   │  7. Streams to you ◄────────────────────────── │
   │                                                  │

Your files are never stored on your server — TelePlay streams them directly from Telegram's cloud on demand.

---

📸 Screenshots

🌐 Web Interface

<p align="center"> <img src="files/web_app_home_screen.png" width="32%" /> <img src="files/web_app_player.png" width="32%" /> <img src="files/web_app_login_screen.png" width="32%" /> </p>

📺 Android TV

<p align="center"> <img src="files/tv_home_screen.png" width="32%" /> <img src="files/tv_player_screen.png" width="32%" /> <img src="files/tv_login_screen.png" width="32%" /> </p>

📱 Mobile App

<p align="center"> <img src="files/mobile_home_screen.png" width="32%" /> <img src="files/mobile_player_screen.png" width="32%" /> <img src="files/mobile_downloads_screen.png" width="32%" /> </p>

---

� Quick Start

Prerequisites — Detailed Steps

| Requirement | How to get it | | :--------------------- | :----------------------------------------------------- | | Telegram Bot Token | Create via @BotFather | | API ID & Hash | Register at my.telegram.org | | Storage Channel | Create a private channel, add your bot as admin | | Docker | Install Docker |

1. Clone & Configure

git clone https://github.com/yourusername/teleplay.git
cd teleplay
cp .env.example .env

Edit .env with your credentials:

TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_STORAGE_CHANNEL_ID=-100xxxxxxxxxx
JWT_SECRET=your-super-secret-key-at-least-32-characters

# Use PostgreSQL (recommended) or SQLite (no setup needed):
DATABASE_URL=sqlite:///./data/teleplay.db
# DATABASE_URL=postgresql://postgres:password@db:5432/teleplay

2. Deploy

docker compose up -d

That's it! Your services are now running:

| Service | URL | | :-------------- | :-------------------- | | Web App | http://localhost | | Backend API | http://localhost:8000 |

3. Start Using

1. Open Telegram and send a video file to your bot.
2. Send /web to get a link to your Web App.
3. Stream your files! 🎬

For detailed setup, usage, and login instructions, see the Setup & Usage Guide.

For VPS, Railway, Render, and CapRover deployments, see the Deployment Guide.

---

📱 Android TV & Mobile App

Download the APK from the Releases page:

| APK | Best For | | :---------- | :------------------------------------- | | arm64-v8a | Modern TV boxes, phones, NVIDIA Shield | | universal | Any device (if unsure, use this one) |

Setup:

1. Install the APK on your device.
2. Enter your Server URL (e.g., http://192.168.1.100).
3. A 6-digit code will appear — send /login CODE to your bot.
4. Done! Browse and stream your library.

For APK signing and release automation, see the Releasing Guide.

---

⚙️ Environment Variables

| Variable | Required | Description | | :---------------------------- | :------: | :--------------------------------------------------------------------------------------------------- | | TELEGRAM_API_ID | ✅ | From my.telegram.org | | TELEGRAM_API_HASH | ✅ | From my.telegram.org | | TELEGRAM_BOT_TOKEN | ✅ | From @BotFather | | TELEGRAM_STORAGE_CHANNEL_ID | ✅ | Private channel ID (starts with -100) | | JWT_SECRET | ✅ | Secret key for JWT signing (min 32 chars) | | DATABASE_URL | ✅ | Database connection URL (see below) | | WEB_BASE_URL | ❌ | Public URL of the web app | | TELEGRAM_HELPER_BOT_TOKENS | ❌ | Extra bot tokens for parallel downloads | | AUTH_USERS | ❌ | Comma-separated Telegram IDs for restricted access |

💡 DATABASE_URL Options:

• PostgreSQL (recommended): postgresql://postgres:password@localhost:5432/teleplay
• SQLite (no setup needed): sqlite:///./data/teleplay.db

Use SQLite if you don't want to set up PostgreSQL — it works out of the box for small deployments.

---

🛠️ Tech Stack

| Layer | Technology | | :----------- | :----------------------------------------------- | | Backend | Python 3.11+, FastAPI, Uvicorn | | Telegram | PyroTGFork (MTProto) | | Database | PostgreSQL (prod) / SQLite (dev), SQLAlchemy 2.0 | | Auth | JWT (Access + Refresh Tokens) | | Web | React 18, TypeScript, Vite | | Android | Kotlin, Jetpack Compose for TV, ExoPlayer | | Deploy | Docker, Docker Compose, Nginx |

---

📁 Project Structure — Full Breakdown

teleplay/
├── backend/                  # Python backend (FastAPI + Bot)
│   ├── app/
│   │   ├── routers/          # API endpoints (auth, files, folders, streaming, tv)
│   │   ├── bot.py            # Telegram bot command handlers
│   │   ├── streaming.py      # Multi-client parallel streaming engine
│   │   ├── models.py         # SQLAlchemy ORM models
│   │   └── main.py           # FastAPI app entry point
│   ├── Dockerfile
│   └── requirements.txt
├── web/                      # React web interface
│   ├── src/
│   │   ├── components