KV-Netflix

The self-hosted movie streaming platform and media portal with native Android TV support.
Stream thousands of movies with HLS proxying, cross-device watch history, and 6-digit TV pairing.
Powered by a Go (Chi + GORM) proxy backend, React 19 + Tailwind v4 PWA, and Kotlin Jetpack Compose TV app.

Quick Start • Why KV-Netflix? • Comparison • Features • Device Pairing • Star History

---

⚡ Why KV-Netflix?

Setting up self-hosted media usually means hoarding hundreds of gigabytes of disk space on Jellyfin or Plex, setting up complex Radarr/Sonarr downloaders, or fighting ISP bandwidth caps.

KV-Netflix gives you an instant, cloud-grade streaming catalog on your home server without using a single byte of disk storage for media files:

• 🌐 Zero-Storage On-Demand Streaming: Scrapes and indexes content across multiple CDN sources (Ophim, PhimMoiChill, NguonPhim) and streams HLS chunks via a lightweight Go reverse proxy.
• 📺 Native Android TV App: Enjoy true couch navigation with D-pad focus control, 10-second skip, auto-countdown next episode, and audio switcher built with Jetpack Compose.
• 🔢 Seamless 6-Digit Device Pairing: Pair your living room smart TV, iPad, or mobile phone by simply typing a 6-digit code—no tedious TV keyboard password typing.
• ⏱️ Instant Cross-Device Resume: Watch history and timestamp progress (within a 20-second intelligent buffer) sync seamlessly across your phone, desktop browser, and smart TV.
• 🐳 1-Container Synology Deployment: Packaged into a single multi-arch container (vndangkhoa/kv-netflix:latest) with embedded SQLite storage and minimal RAM usage.

---

📊 Competitive Comparison

Capability	🎬 KV-Netflix	🍿 Stremio	🦁 Jellyfin / Plex
Server Storage Required	Zero GB (Stream on demand)	Zero GB	Hundreds of GBs / TBs
Self-Hosted Controller	✅ 1-Container Docker	❌ Centralized Cloud	✅ Self-hosted
Vietnamese & Asian Catalog	✅ Multi-Provider Aggregation	⚠️ Community Addons	❌ Manual Downloads
6-Digit TV Login Pairing	✅ Yes (Instant QR / Code)	❌ QR only	⚠️ Plex PIN only
HLS Stream CORS Proxy	✅ Built-in Go Reverse Proxy	⚠️ Torrent / Debrid	N/A
Native Android TV Client	✅ Kotlin Jetpack Compose	✅ Android TV	✅ Android TV

---

📸 Interface Preview

┌────────────────────────────────────────────────────────────────────────────────────────┐
│ [🔴 KV-NETFLIX]   Home   Movies   Series   Anime   My List       [🔍 Search] [👤 Khoa] │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│   🎬 FEATURED STREAM: DUNE: PART TWO                                                   │
│   ⭐⭐⭐⭐⭐ 2024 • 2h 46m • 4K UHD • Vietsub / Thuyết minh                             │
│   Paul Atreides unites with Chani and the Fremen while seeking revenge against...      │
│   [ ▶ Play Now ]   [ + My List ]   [ ℹ️ More Info ]                                     │
│                                                                                        │
│ ────────────────────────────────────────────────────────────────────────────────────── │
│ ⏱️ CONTINUE WATCHING FOR KHOA                                                           │
│  ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ ┌─────────────┐  │
│  │ 🎥 Shōgun          │ │ 🎥 Interstellar    │ │ 🎥 Arcane          │ │ 🎥 Breaking │  │
│  │ Ep 4 • 38:12 / 59m │ │ 1h 42m / 2h 49m    │ │ S2: Ep 1 • 15:20   │ │ S5: Ep 14   │  │
│  └────────────────────┘ └────────────────────┘ └────────────────────┘ └─────────────┘  │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘

---

🎯 Killer Features

1. 🎞️ High-Throughput HLS Stream Proxy

Bypasses cross-origin resource sharing (CORS) blocks and CDN geo-restrictions. Streams fragmented .m3u8 playlists and .ts transport segments through an asynchronous Go pipeline with zero buffering.

2. 📺 Android TV with D-Pad Experience

A dedicated Kotlin client designed specifically for television remotes:

• Seamless D-pad navigation with glowing focus borders
• One-click 10-second seek forward/backward
• Overlay countdown for the next episode with thumbnail preview

3. 🔢 6-Digit Device Pairing

Logging in on a TV remote is painful. KV-Netflix generates a temporary 6-digit code on the TV screen. Simply open http://<your-server>/pair on your phone or PC, enter the code, and your TV is logged in instantly.

4. 🌓 Dual-Theme & Bilingual

Includes automatic Dark/Light mode detection and instant English & Vietnamese internationalization (vi / en).

---

🚀 Quick Start (30 Seconds)

Option A: Run Prebuilt Docker Container

Launch KV-Netflix immediately on port 8088:

docker run -d \
  --name kv-netflix \
  -p 8088:8088 \
  -v ./data:/app/data \
  -e JWT_SECRET=change_to_a_secure_random_key \
  --restart unless-stopped \
  vndangkhoa/kv-netflix:latest

Open http://localhost:8088 in your browser.

---

Option B: Docker Compose

services:
  kv-netflix:
    image: vndangkhoa/kv-netflix:latest
    container_name: kv-netflix
    restart: unless-stopped
    ports:
      - "8088:8088"
    environment:
      - PORT=8088
      - JWT_SECRET=your-random-jwt-secret-key
    volumes:
      # Persistent SQLite database & device sessions
      - ./data:/app/data

Start the stack:

docker compose up -d

---

🌟 Support & Community

If KV-Netflix upgrades your home entertainment setup:

• Give the project a Star ⭐ on GitHub!
• Share your setup on Reddit r/selfhosted
• Submit bug reports or source provider scrapers on GitHub Issues

---

📄 License

Distributed under the MIT License. See LICENSE for details.

Developed with ❤️ by Khoa Vo (@vndangkhoa).