Real-Debrid Direct Streaming Platform
Linkarr is a lightweight alternative to traditional media server setups (Jellyfin/Plex + Riven). Instead of proxying streams through your VPS and consuming bandwidth, Linkarr stores only metadata and Real-Debrid URLs, allowing clients to stream directly from Real-Debrid's CDN.
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Overseerr │────────>│ Linkarr │<────────│ Android TV │
│ (Requests) │ Webhook │ Backend │ REST │ Client │
└─────────────────┘ │ │ API │ │
│ • Metadata │ │ • ExoPlayer │
│ • RD URLs │ │ • Compose TV │
│ • Auth │ │ • Direct CDN │
│ │ │ Streaming │
└──────┬───────┘ └─────────────────┘
│
v
┌──────────────┐
│ Real-Debrid │
│ API │
└──────────────┘
- Zero Bandwidth Usage: Clients stream directly from Real-Debrid CDN
- Minimal Storage: Only metadata and URLs stored (no media files)
- Overseerr Integration: Automatic content addition via webhooks
- Real-Debrid Integration: Torrent caching and direct streaming links
- Android TV Native: Optimized for 10-foot UI experience
- Multi-User Support: Each user brings their own Real-Debrid account
- Auto Link Refresh: Background tasks keep streaming URLs valid
- FastAPI - Modern Python web framework
- PostgreSQL - Metadata and user database
- Redis - Caching and task queue
- Celery - Background task processing
- SQLAlchemy - ORM for database operations
- Docker - Containerized deployment
- Kotlin - Primary programming language
- Jetpack Compose for TV - Modern declarative UI
- ExoPlayer - Advanced media playback
- Retrofit - REST API client
- Coil - Image loading
linkarr/
├── linkarr-backend/ # FastAPI backend server
│ ├── app/
│ │ ├── api/ # REST API endpoints
│ │ ├── models/ # Database models
│ │ ├── services/ # Business logic
│ │ └── tasks/ # Celery background tasks
│ ├── docker-compose.yml
│ ├── Dockerfile
│ └── requirements.txt
├── linkarr-android/ # Android TV client
│ ├── app/
│ │ └── src/main/
│ │ ├── java/com/linkarr/
│ │ │ ├── data/ # API clients, repositories
│ │ │ ├── domain/ # Business models
│ │ │ └── ui/ # Compose screens
│ │ └── res/ # Resources
│ └── build.gradle.kts
└── docs/ # Documentation
cd linkarr-backend
docker-compose up -dThe backend will be available at http://localhost:8000
- Build the APK:
cd linkarr-android
./gradlew assembleRelease- Install on Android TV:
adb install -r app/build/outputs/apk/release/app-release.apk- Configure backend URL in app settings
# Database
DATABASE_URL=postgresql://linkarr:password@postgres:5432/linkarr
# Redis
REDIS_URL=redis://redis:6379/0
# Real-Debrid
RD_API_BASE_URL=https://api.real-debrid.com/rest/1.0
# TMDb
TMDB_API_KEY=your_tmdb_api_key
# Security
SECRET_KEY=your-secret-key-here- Overseerr - Content request management
- Real-Debrid Account - Each user needs their own account
- TMDb API Key - For metadata enrichment
- Content Request: User requests content via Overseerr
- Webhook Trigger: Overseerr sends webhook to Linkarr on approval
- Torrent Search: Linkarr searches for best torrent via indexers
- RD Caching: Torrent added to Real-Debrid for caching
- Metadata Fetch: TMDb metadata fetched and stored
- URL Generation: Direct streaming URLs generated via RD API
- Client Streaming: Android TV client fetches URL and streams directly from RD CDN
- users - User accounts with RD API tokens
- media_items - Movies/Shows metadata
- seasons - TV season information
- episodes - Individual episode data
- rd_torrents - Real-Debrid torrent tracking
- rd_links - Cached streaming URLs with expiration
POST /api/auth/register- Register new userPOST /api/auth/login- User loginPOST /api/auth/rd-token- Save Real-Debrid API token
GET /api/media- List all mediaGET /api/media/{id}- Get media detailsGET /api/media/{id}/play- Get streaming URL
GET /api/library/movies- User's movie libraryGET /api/library/shows- User's TV shows library
POST /api/webhooks/overseerr- Overseerr webhook handler
- Link Refresh: Refresh expiring RD URLs (every 4 hours)
- Torrent Status Check: Monitor torrent caching progress
- Metadata Update: Sync latest metadata from TMDb
- Project structure
- Backend API implementation (Authentication, Media, Library, Webhooks)
- Database models and migrations
- Real-Debrid client integration
- TMDb metadata manager
- Overseerr webhook handler
- Content manager service layer
- Link cache manager with auto-refresh
- Celery background tasks (link refresh, torrent monitoring)
- Android TV project structure
- Android TV data layer (API client, repositories, ViewModels)
- Android TV UI screens (Login, Home, Detail)
- Android TV Player screen
- ExoPlayer integration
- Search functionality
- Continue watching
- Watchlist management
- Multiple quality options
- Subtitle support
- Intro/outro skip detection
- Multiple user profiles
- Watch together feature
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
MIT License - See LICENSE file for details
- Automation Avenue - Initial inspiration and setup guidance
- Overseerr - Content request management
- Real-Debrid - Torrent caching and CDN infrastructure
- TMDb - Movie and TV show metadata
Current Build: v0.1.0-build.3 Last Updated: 2025-10-14
Implementation Status:
- ✅ Backend Core: Complete
- ✅ API Endpoints: Complete
- ✅ Service Layer: Complete
- ✅ Background Tasks: Complete
- ✅ Database Migrations: Setup Complete
- ✅ Android TV Client: Data Layer Complete
- 🚧 Android TV Client: Video Player In Progress