Skip to content
BranchesTags

Repository files navigation

📺 TelePlay

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

TelePlay Banner

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.

LicensePythonFastAPIReactKotlin

✨ 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

🏗️ 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

RequirementHow to get it
Telegram Bot TokenCreate via @BotFather
API ID & HashRegister at my.telegram.org
Storage ChannelCreate a private channel, add your bot as admin
DockerInstall 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=12345678TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11TELEGRAM_STORAGE_CHANNEL_ID=-100xxxxxxxxxxJWT_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:

ServiceURL
Web Apphttp://localhost
Backend APIhttp://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:

APKBest For
arm64-v8aModern TV boxes, phones, NVIDIA Shield
universalAny 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

VariableRequiredDescription
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

LayerTechnology
BackendPython 3.11+, FastAPI, Uvicorn
TelegramPyroTGFork (MTProto)
DatabasePostgreSQL (prod) / SQLite (dev), SQLAlchemy 2.0
AuthJWT (Access + Refresh Tokens)
WebReact 18, TypeScript, Vite
AndroidKotlin, Jetpack Compose for TV, ExoPlayer
DeployDocker, 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

GuideDescription
Setup & UsageHow the app works, bot commands, login methods, and troubleshooting
DeploymentDocker, VPS, Railway, Render, and CapRover deployment
ArchitectureTechnical deep-dive: streaming engine, API endpoints, database models
ReleasingAPK 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

About

A self-hosted media streaming solution that lets you store, organize, and stream your video files from Telegram Servers. Access your media library from anywhere via a web interface or Android TV app / Mobile App.

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

103 stars

Watchers

1 watching

Forks

52 forks
Report repository

Releases

Contributors

Languages