diff --git a/README.md b/README.md index 5079a1c..6dd29c8 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,83 @@ -

- Go - Next.js - Docker - SQLite - License -

-

๐ŸŽฌ KV-Tube

- Self-hosted video streaming platform
- Go backend + Next.js frontend โ€” single Docker container + Your personal YouTube ยท Self-hosted, private, lightweight

- Quick Start โ€ข - Features โ€ข - Architecture โ€ข - Deployment โ€ข - Development + + License + + Go + Next.js + Docker + SQLite + PWA +

+ +

+ Features โ€ข + Quick Start โ€ข + Why KV-Tube? โ€ข + Deployment โ€ข + Development โ€ข + Contributing

--- -

๐Ÿš€ Quick Start

+

+ 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. +
+ +## ๐Ÿš€ Quick Start ```bash git clone https://github.com/vndangkhoa/kv-tube.git @@ -34,69 +88,57 @@ docker compose up -d ```

- Frontend: http://localhost:5011  โ€ข  - API: http://localhost:8981 + Frontend: http://localhost:5011  โ€ข  + API: http://localhost:8981

--- -

โœจ Features

+## ๐Ÿค” Why KV-Tube? - - - - - - - - - - - - - - - - - - - - - - - - - -
๐ŸŽž๏ธVideo Playback
HLS streaming with quality selection		๐Ÿ“œWatch History
Track what you've watched
๐Ÿ””Subscriptions
Follow YouTube channels		๐Ÿ”Search
Find videos instantly
๐ŸŽตBackground Audio
Play with screen locked		๐Ÿ“ฑPWA
Install as native app
๐ŸŒRegion Selection
Tailor content by region		๐ŸŒ“Themes
Light & dark mode
+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

+## ๐Ÿ—๏ธ Architecture + +KV-Tube ships as a single Docker image. Everything runs in one container, managed by supervisord.

- - - - - - - + + + + + + +

-Single unified Docker container running: +| 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 | -| Component | Tech | Port | Role | -|-----------|------|------|------| -| **Backend** | Go + Gin | `8080` | REST API, video processing, yt-dlp | -| **Frontend** | Next.js 16 | `3000` | SSR, PWA, UI | -| **Process Manager** | supervisord | โ€” | Manages both processes | -| **Storage** | SQLite | โ€” | Watch history & metadata | +## ๐Ÿ“ฆ Deployment ---- - -

๐Ÿ“ฆ Deployment

- -

๐Ÿณ Docker Compose

+### ๐Ÿณ Docker Compose (Recommended) ```yaml services: @@ -116,16 +158,14 @@ services: restart: unless-stopped ``` -

๐Ÿ–ฅ๏ธ Synology NAS (DSM 7.2+)

+### ๐Ÿ–ฅ๏ธ Synology NAS (DSM 7.2+) -
    -
  1. Create /volume1/docker/kv-tube/data
    2. -
  2. Upload docker-compose.yml, Dockerfile, supervisord.conf
    3. -
  3. Open Container Manager > Project > Create
    4. -
  4. Select path /volume1/docker/kv-tube, click Done
    5. -
+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

+### ๐Ÿ› ๏ธ Multi-arch Build ```bash docker buildx build --platform linux/amd64 -t kv-tube:latest --push . @@ -133,19 +173,19 @@ docker buildx build --platform linux/amd64 -t kv-tube:latest --push . --- -

โš™๏ธ Environment Variables

+## โš™๏ธ Configuration | Variable | Default | Description | |----------|---------|-------------| -| `KVTUBE_DATA_DIR` | `/app/data` | Data storage path | -| `GIN_MODE` | `release` | Gin framework mode | -| `NODE_ENV` | `production` | Node environment | -| `CORS_ALLOWED_ORIGINS` | โ€” | Comma-separated allowed CORS origins | -| `PORT` | `8080` | Backend API port | +| `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

+## ๐Ÿ’ป Development ```bash # Frontend @@ -160,21 +200,27 @@ go run main.go --- -

๐Ÿ”„ Updating

+## ๐Ÿค Contributing -```bash -docker compose pull -docker compose up -d -``` +Contributions are welcome! Here's how to help: -Or enable auto-updates with Watchtower. +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

+## ๐Ÿ“„ License -

- License +Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information. + +

+
+ If you find this project useful, please โญ star it on GitHub. +
+ Built with โค๏ธ by Khoa Vo

- -MIT License โ€” see LICENSE for details.