birdxs/teleplay repository overview

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

⁠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:

⁠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! 🎬

⁠📱 Android TV & Mobile App

Download the APK from the Releases⁠ page:

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.

⁠⚙️ Environment Variables

⁠🛠️ Tech Stack

⁠📁 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

⁠🤝 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