Skip to content

README.md

Latest commit

 

History

History
326 lines (244 loc) · 13.5 KB

README.md

File metadata and controls

326 lines (244 loc) · 13.5 KB

📺 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.

License Python FastAPI React Kotlin

✨ 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

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