What if you could build your own Netflix — without any licensing deals, content budgets, or monthly subscription fees? That was the challenge behind **Hypertube.
The Idea
Streaming platforms have conditioned us to expect instant, high-quality video — but that experience is expensive to build and expensive to maintain. What if the same seamless experience could be delivered using peer-to-peer technology that's been around for decades?
Hypertube is a full-stack web application that does exactly that. It's a modern, dark-mode streaming platform — aesthetically inspired by Netflix — that uses BitTorrent to source and stream movies directly inside your browser. No subscriptions. No ads. No waiting for downloads to finish.
What Hypertube Can Do
The application brings together a full cinematic experience:
- 🔍 Advanced Search — Filter thousands of movies by quality, genre, and rating across multiple torrent sources
- ▶️ Instant Streaming — Start watching in seconds with smart buffering. The video plays while it downloads in the background
- 🌐 Multi-language Subtitles — Dozens of subtitle languages, auto-synced to the video
- 💬 Community Features — Comment on films, discuss your favorites, and connect with other cinephiles
- 🔐 Flexible Authentication — Log in with GitHub, Google, GitLab, Discord, or 42 — or just use email
Authentication: Five OAuth Providers and Email
The sign-in flow was built with real-world security in mind. Users can authenticate via five different OAuth2 providers or a classic email/password flow — all handled through Passport.js strategies on the NestJS backend.
Access tokens are short-lived and JWTs are revoked on logout through a dedicated revoked-tokens module, preventing token replay attacks.
Browsing: A Cinematic Movie Grid
The main browsing experience presents movies in a rich poster grid — sorted by popularity, rating, or genre. Each card shows the movie's quality badge, IMDb rating, and release year at a glance. The interface feels instantly familiar thanks to its dark-mode Netflix-like design, built with React, TypeScript, and Tailwind CSS.
Filtering and searching happen in real time, with query results pulled from multiple torrent sources and enriched with metadata from public movie APIs.
Movie Details: Everything at a Glance
Every movie gets its own dedicated page with:
- Full synopsis, cast, and director info
- Available quality options (720p, 1080p, etc.)
- Subtitle language selector
- A one-click Stream Now button
The detail page fetches metadata and torrent magnet links simultaneously, so by the time you hit play, everything is ready.
The Magic: BitTorrent Meets HLS Streaming
This is where Hypertube gets genuinely interesting from an engineering perspective.
Traditional streaming services encode videos into HLS segments and serve them from CDNs. Hypertube does something different: it downloads the torrent file on-demand on the server, pipes the video data through FFmpeg for real-time transcoding, and serves it as an HLS stream to the browser.
Here's the flow:
User clicks "Play"
↓
Backend resolves torrent → starts downloading in-memory
↓
FFmpeg transcodes incoming bytes → .m3u8 + .ts segments
↓
Browser loads HLS playlist → video plays instantly
↓
Download continues in background while you watch
The result is a zero-wait streaming experience backed by the BitTorrent network — no file storage required, no CDN bill.
Community: Comments & Discussions
Hypertube isn't just a player — it's a community. Each movie has a threaded comment section where users can discuss the film, share thoughts, and leave ratings. Comments are tied to authenticated accounts, keeping discussions meaningful.
Watch History: Never Lose Your Place
Every movie you stream is automatically logged to your watch history. You can resume from where you left off, revisit favorites, and track your watching habits — all without any manual bookmarking.
Tech Stack Deep Dive
Hypertube is a modern full-stack application split cleanly into two services:
🖥️ Frontend
| Technology | Purpose |
|---|---|
| React + TypeScript | UI components and type safety |
| Tailwind CSS | Utility-first styling |
| Vite | Lightning-fast dev server and bundler |
| React Router | Client-side routing |
| React Icons | Icon library |
⚙️ Backend
| Technology | Purpose |
|---|---|
| NestJS (TypeScript) | Modular REST API framework |
| Passport.js | OAuth2 + JWT authentication strategies |
| FFmpeg | Real-time video transcoding |
| HLS | Adaptive HTTP video streaming |
| Swagger | Auto-generated API documentation |
🐳 Infrastructure
Both the frontend and backend are fully Dockerized, with separate docker-compose configurations for development and production. This makes the entire stack reproducible with a single command:
docker-compose up --build
Architecture Overview
┌─────────────────────────────────────────┐
│ React Frontend │
│ (Vite + TypeScript + Tailwind) │
└──────────────────┬──────────────────────┘
│ REST API / HLS
┌──────────────────▼──────────────────────┐
│ NestJS Backend │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Auth │ │ Movies │ │ Comments │ │
│ │ Module │ │ Module │ │ Module │ │
│ └─────────┘ └────┬─────┘ └──────────┘ │
│ ┌────▼─────┐ │
│ │ Torrent │ │
│ │ Module │ │
│ └────┬─────┘ │
│ ┌────▼─────┐ │
│ │ FFmpeg │ │
│ │ (HLS out)│ │
│ └──────────┘ │
└─────────────────────────────────────────┘
The backend is cleanly separated into NestJS modules: auth, movies, comments, torrent, users, and mails — making the codebase easy to navigate and extend.
Lessons Learned
Building Hypertube touched on some genuinely tricky engineering problems:
Streaming before the download completes — The hardest part was piping torrent data through FFmpeg fast enough that the HLS playlist stays ahead of the playback position.
OAuth across five providers — Each OAuth provider has subtle differences. Passport.js strategies abstract most of it, but edge cases (like handling missing email fields from some providers) required custom logic.
Token revocation with JWTs — JWTs are stateless by nature. Implementing a revoked-tokens store means the backend must check every request against it — a trade-off between security and performance.
Responsive dark-mode UI — Getting the poster grid, player, and detail pages to feel premium across all screen sizes required careful Tailwind component design.
Try It Yourself
Hypertube is open source. If you want to run it locally:
# Clone the repository
git clone https://github.com/UBA-code/hypertube
# Fill in your OAuth credentials
cp .env.preview .env.dev
# Start everything with Docker
docker-compose up --build
The frontend runs at http://localhost:5173 and the API at http://localhost:3000/api (with Swagger docs included).
Final Thoughts
Hypertube is a proof of concept that modern streaming UX doesn't require a billion-dollar infrastructure budget. By combining BitTorrent's decentralized network with server-side HLS transcoding via FFmpeg, the app delivers a genuinely responsive streaming experience built entirely on open-source technology.
It was a challenging project — touching OAuth, real-time video processing, peer-to-peer networking, and modern frontend design all at once — but the end result is something that actually works and looks great doing it.
If you found this interesting, feel free to ⭐ the repo and share your thoughts in the comments below.
Built with ❤️ using React, NestJS, FFmpeg, and BitTorrent.
© 2025 Hypertube. All rights reserved.
Top comments (0)