🎬 KV-Tube

Your personal YouTube · Self-hosted, private, lightweight

Features • Quick Start • Why KV-Tube? • Deployment • Development • Contributing

---

Watch, search, and subscribe — just like YouTube, but fully under your control.

✨ Features

🎞️ Video Playback HLS streaming with adaptive quality — from 144p to 4K.	📜 Watch History Automatically tracked. Always in sync. Never lose your place.
🔔 Subscriptions Follow any YouTube channel. Get updates instantly.	🔍 Search Full-text search across videos, channels, and history.
🎵 Background Audio Keep listening with the screen locked — perfect for music.	📱 PWA Install as a native app. Works offline. Full-screen experience.
🌍 Region Tuning Tailor content and recommendations to any region.	🌓 Themes Light, dark, and system-following themes out of the box.
📺 Rich Channel Pages Banner, avatar, description, subscriber & view counts, and infinite-scrolling videos.	⚡ Fast & Resilient Aggressive caching, multi-client yt-dlp fallback, and lazy metadata hydration.
📥 Server-side Downloads Download any video straight to your device as an MP4. The server fetches it with yt-dlp and streams a live progress bar — no ads, no client-side hacks. Pick from three quality tiers: Low (≤360p), Recommended (≤1080p), or Best.	🧹 Self-cleaning Cache Downloaded files live in a temp server cache (30-minute TTL) and are purged automatically — nothing piles up on your disk.
📱 Android App Native Android client built with Kotlin & Jetpack Compose. Material 3 design, ExoPlayer video playback, on-device NewPipeExtractor downloads, share to any app, download progress with badge indicator, dark/light themes, and auto-updates via GitHub/Forgejo releases.	⬇️ On-device Downloads Download videos directly on your Android device using NewPipeExtractor stream extraction. Three quality tiers (Low 360p, Recommended 1080p, Best) with background download via WorkManager. Search, rename, sort, and delete downloaded files from the Downloads tab.

🚀 Quick Start

Pull the pre-built image and run it — no local build needed:

mkdir -p kv-tube/data && cd kv-tube
curl -O https://raw.githubusercontent.com/vndangkhoa/kv-tube/main/docker-compose.yml
docker compose up -d

Prefer building from source?

git clone https://github.com/vndangkhoa/kv-tube.git
cd kv-tube
mkdir -p data
docker build -t kv-tube:latest .
docker compose up -d

Frontend: http://localhost:5011  •  API: http://localhost:8981

📥 Container Images

Pre-built images are published to three registries:

Registry	Image
Docker Hub	vndangkhoa/kv-tube:latest
GitHub Container Registry	ghcr.io/vndangkhoa/kv-tube:latest
Forgejo	git.khoavo.myds.me/vndangkhoa/kv-tube:latest

🌐 Source Repositories

The project is mirrored on GitHub and Forgejo — both stay in sync:

• GitHub: https://github.com/vndangkhoa/kv-tube
• Forgejo: https://git.khoavo.myds.me/vndangkhoa/kv-tube

---

🤔 Why KV-Tube?

YouTube is incredible — but it's also ad-ridden, tracks everything, and sometimes removes the videos you love.

KV-Tube gives you:

• Privacy — No tracking, no algorithms manipulating you. Your watch history stays on your machine.
• Permanence — Videos you subscribe to stay available. No takedowns, no region blocks.
• Ownership — Run it on your NAS, your VPS, or a Raspberry Pi. It's yours.
• Simplicity — One container. One command. Zero configuration.

📖 Backstory

I built KV-Tube because I wanted a way to watch YouTube content without the YouTube baggage — ads, recommendation rabbit holes, and the feeling that the product was me, not the video player.

What started as a simple Go API to proxy video streams evolved into a full-featured frontend with subscriptions, search, PWA support, and a clean, YouTube-like interface. It runs on my Synology NAS at home, and I use it daily.

If that resonates, give it a star ⭐ — it helps others find the project.

---

🏗️ Architecture

KV-Tube ships as a single Docker image. Everything runs in one container, managed by supervisord.

Layer	Tech	Port	Role
Backend	Go + Gin	8080	REST API, video fetching, yt-dlp orchestration
Frontend	Next.js 16	3000	SSR, PWA, responsive UI
Process Manager	supervisord	—	Keeps backend + frontend alive
Storage	SQLite	—	Watch history, subscriptions, metadata

📦 Deployment

🐳 Docker Compose (Recommended)

Using the pre-built image from Docker Hub:

services:
  kv-tube:
    image: vndangkhoa/kv-tube:latest
    container_name: kv-tube
    platform: linux/amd64
    ports:
      - "5011:3000"
      - "8981:8080"
    volumes:
      - ./data:/app/data
    environment:
      - KVTUBE_DATA_DIR=/app/data
      - GIN_MODE=release
      - NODE_ENV=production
      - CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5011
    restart: unless-stopped

Or pull from another registry — swap the image line:

    image: ghcr.io/vndangkhoa/kv-tube:latest
    # image: git.khoavo.myds.me/vndangkhoa/kv-tube:latest

Prefer building locally? Replace image: with build: ..

🖥️ Synology NAS (DSM 7.2+)

1. Create folder /volume1/docker/kv-tube/data
2. Upload docker-compose.yml, Dockerfile, supervisord.conf
3. In Container Manager → Project → Create, select the folder
4. Done. The container builds and starts automatically.

🛠️ Multi-arch Build

docker buildx build --platform linux/amd64 -t kv-tube:latest --push .

---

⚙️ Configuration

Variable	Default	Description
KVTUBE_DATA_DIR	/app/data	Path for SQLite DB and data
GIN_MODE	release	Gin framework log mode
NODE_ENV	production	Node.js environment
CORS_ALLOWED_ORIGINS	""	Comma-separated allowed origins
PORT	8080	Backend API listen port

---

💻 Development

# Frontend
cd frontend
npm install
npm run dev

# Backend
cd backend
go run main.go

# Android App
cd android
# Ensure JAVA_HOME points to JDK 17
./gradlew assembleDebug
# Install on emulator/device
adb install app/build/outputs/apk/debug/app-debug.apk

---

🤝 Contributing

Contributions are welcome! Here's how to help:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push (git push origin feature/amazing)
5. Open a Pull Request

Please make sure to follow existing code style and add tests when possible.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

_{If you find this project useful, please ⭐ star it on GitHub.
Built with ❤️ by Khoa Vo}