Hypertube

A modern web application for streaming movies via BitTorrent with real-time subtitle support and a beautiful, responsive interface.

Overview

Hypertube is a full-stack streaming platform that allows users to browse, search, and watch public domain and copyright-free movies directly through BitTorrent technology. The application downloads content on-demand, transcodes it for web playback, and provides multi-language subtitle support, all within a sleek interface.

Important

Hypertube exclusively sources content from legitimate public domain archives, ensuring all streamed content is legally available and copyright-free.

Key Features

• On-Demand Streaming: Stream movies directly via BitTorrent without waiting for full downloads
• Advanced Search: Browse and search movies with rich metadata from TMDB
• Multi-Language Subtitles: Automatic subtitle fetching from OpenSubtitles in multiple languages
• User Authentication: Support for OAuth providers (42, GitHub, Google) and traditional email/password
• Comments & Interaction: Comment on movies and interact with other users

Getting Started

Prerequisites

• Docker and Docker Compose
• Doppler CLI (for environment variable management)
• API keys for:
  • TMDB (movie metadata)
  • OpenSubtitles (subtitles)

Installation

1. Clone the repository

   git clone https://github.com/lucas-ht/hypertube.git
   cd hypertube

2. Set up environment variables

   cp .env.example .env
   # Edit .env with your API keys and configuration

3. Configure OAuth providers (optional)

   Add your OAuth credentials to .env:

   • 42 OAuth
   • GitHub OAuth
   • Google OAuth

4. Start the application

   docker compose up --build

5. Access the application

   • Web Interface: http://localhost:8000
   • API Documentation: http://localhost:8000/api/docs

How It Works

1. Movie Discovery

Users browse or search for movies using the TMDB integration, which provides rich metadata including posters, ratings, descriptions, and more.

2. Movie Catalog & Torrent Sources

Hypertube maintains a curated catalog of copyright-free movies sourced from two trusted providers:

• Archive.org: Public domain movies with verified license information, filtered for English language content with high download counts
• PublicDomainTorrents.info: Curated collection of classic public domain films

These providers are periodically ingested to keep the catalog fresh and up-to-date.

3. Movie Ingest Process

The application periodically ingests and enriches movie metadata through a multi-stage pipeline:

Torrent Providers (Archive.org + PublicDomainTorrents)
    ↓
Extract Movie Metadata (title, year, language)
    ↓
Enrich with TMDB (posters, ratings, descriptions, genres)
    ↓
Generate Thumbnails & Store in MinIO
    ↓
Cache in Redis for Fast Access
    ↓
Index in RediSearch for Full-Text Search

This process runs as a scheduled Celery Beat task, ensuring the movie catalog stays current with new additions to the public domain archives.

4. Streaming Pipeline

Torrent Download (Transmission)
    ↓
Sequential Download (Prioritize first/last pieces)
    ↓
Video Transcoding (FFmpeg → HLS format)
    ↓
Adaptive Streaming (HLS.js in browser)

5. Subtitle Integration

• Subtitles are automatically fetched from OpenSubtitles based on movie metadata
• Users can select from available languages

6. Background Processing

Celery workers handle:

• Torrent downloads and management
• Video transcoding and optimization
• Subtitle fetching and processing
• Cleanup of old or unwatched content
• Search index updates (RediSearch)

Development

Project Structure

hypertube/
├── api/              # FastAPI backend
│   ├── app/
│   │   ├── api/      # API endpoints
│   │   ├── core/     # Core functionality (auth, config, etc.)
│   │   ├── features/ # Business logic
│   │   ├── tasks/    # Celery tasks
│   │   └── ws/       # WebSocket handlers
│   └── alembic/      # Database migrations
├── web/              # React frontend
│   └── src/
│       ├── components/
│       ├── routes/
│       ├── hooks/
│       └── lib/
├── configs/          # Service configurations
├── torrentlab/       # Torrent testing environment
└── seed/             # Database and storage seeding

Configuration

Key environment variables:

Variable	Description	Required
TMDB_API_KEY	TMDB API key for movie metadata	Yes
OPENSUBTITLES_API_KEY	OpenSubtitles API key	Yes
JWT_SECRET	Secret for JWT token generation	Yes
POSTGRES_URL	PostgreSQL connection string	Yes
REDIS_URL	Redis connection string	Yes
MINIO_ROOT_USER	MinIO admin username	Yes
MINIO_ROOT_PASSWORD	MinIO admin password	Yes
FORTYTWO_CLIENT_ID	42 OAuth client ID	No
GITHUB_CLIENT_ID	GitHub OAuth client ID	No
GOOGLE_CLIENT_ID	Google OAuth client ID	No

See .env.example for a complete list.

API Documentation

Interactive API documentation is available at /api/docs when running the application. The API provides:

• Authentication: Registration, login, OAuth flows, password reset
• Movies: Search, details, streaming endpoints
• Users: Profile management, watch history
• Comments: Create, read, update, delete comments
• Health: Service health checks

License

This project is part of the 42 School curriculum.

Acknowledgments

• TMDB for movie metadata and images
• OpenSubtitles for subtitle data
• 42 School for the project specifications
• All open-source libraries and tools used in this project