📺 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

📺 Android TV

📱 Mobile App

---

� 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/       # UI components
│   │   ├── lib/api.ts        # API client & hooks
│   │   └── App.tsx           # Main app with routing
│   └── Dockerfile
├── android/                  # Android TV & Mobile app
│   └── app/src/main/java/    # Kotlin (Compose + ExoPlayer)
├── docs/                     # Documentation
│   ├── ARCHITECTURE.md       # Technical deep-dive
│   ├── DEPLOYMENT.md         # Deployment guide
│   ├── SETUP.md              # Setup & usage guide
│   └── RELEASING.md          # APK release process
├── docker-compose.yml
└── .env.example

---

🔧 Development

Backend

cd backend
python -m venv venv
venv\Scripts\activate        # Linux/Mac: source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env         # Edit with your credentials
uvicorn app.main:app --reload

Web App

cd web
npm install
npm run dev

Android

Open the android/ folder in Android Studio and build.

---

🔒 Security — Details

• JWT Authentication — Short-lived access tokens with refresh token rotation
• User Authorization — Optional AUTH_USERS whitelist
• Rate Limiting — SlowAPI middleware on all endpoints
• CORS Protection — Restricted to configured origins
• Input Validation — Pydantic schemas prevent injection attacks
• Security Headers — Standard headers on all responses

---

📚 Documentation

Guide	Description
Setup & Usage	How the app works, bot commands, login methods, and troubleshooting
Deployment	Docker, VPS, Railway, Render, and CapRover deployment
Architecture	Technical deep-dive: streaming engine, API endpoints, database models
Releasing	APK build automation and signing via GitHub Actions

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

• PyroTGFork — Telegram MTProto library
• FastAPI — Modern Python web framework
• React — Frontend library
• Jetpack Compose for TV — Android TV UI toolkit
• ExoPlayer — Android media player