HomeHub

A self-hosted video and image library with a YouTube-like interface and HLS streaming.

Note: This is a personal pet project designed for home use on a local network. It is not optimized for production server deployment, high availability, or multi-user environments.

AI-Generated Frontend

The entire frontend codebase (React, TypeScript, Tailwind CSS) and UI/UX design were written by Claude Opus 4.6 (Anthropic). The backend (Rust) was developed collaboratively with AI assistance.

Features

• HLS adaptive video streaming with on-demand segmentation
• NVIDIA GPU acceleration (CUDA/NVENC) with automatic CPU fallback
• Automatic thumbnail and scene preview sprite generation
• RAM and disk caching with TTL-based eviction
• Real-time progress notifications via WebSocket
• Playlist navigation based on folder structure
• Image gallery support

Prerequisites

• Rust toolchain (stable)
• Node.js and npm
• FFmpeg and FFprobe
• Optional: NVIDIA GPU with CUDA drivers for hardware acceleration

Build

Backend

cargo build --release

Frontend

cd client
npm install
npm run build

Configuration

Copy the example environment file and edit it:

cp .env.example .env

Variable	Default	Description
MEDIA_ROOT	—	Root directory containing your videos and images
PORT	3000	HTTP server port
FFMPEG_PATH	/usr/bin/ffmpeg	Path to ffmpeg binary
FFPROBE_PATH	/usr/bin/ffprobe	Path to ffprobe binary
CACHE_DIR	/tmp/homehub-rs	Directory for HLS segments and cache
GPU_ACCEL	nvidia	GPU acceleration: nvidia or none
RAM_CACHE_GB	48	RAM cache limit for HLS segments (GB)
MAX_PARALLEL_FFMPEG	6	Max parallel FFmpeg segmentation tasks
MAX_PARALLEL_THUMBNAILS	4	Max parallel FFmpeg thumbnail tasks
SEGMENT_DURATION	4	HLS segment duration (seconds)
SCENE_INTERVAL	120	Seconds between scene preview captures
PRELOAD_ADJACENT_VIDEOS	3	Number of adjacent videos to pre-segment

Run

cargo run --release

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

The server will scan your media library, start generating thumbnails in the background, and begin serving content immediately.

Recommendations

• Cache directory on tmpfs: Set CACHE_DIR to a path on a tmpfs mount (e.g., /tmp/homehub-rs) to avoid unnecessary disk writes for temporary HLS segments.
• RAM cache sizing: If your machine has 64GB+ RAM, allocating 24–48GB to RAM_CACHE_GB provides a good balance. For 16GB systems, 4–8GB is reasonable.
• GPU acceleration: With an NVIDIA GPU, segmentation and thumbnail generation are significantly faster. Set GPU_ACCEL=nvidia. Without a GPU, set GPU_ACCEL=none — CPU fallback works but is slower.
• Parallel tasks: Keep MAX_PARALLEL_FFMPEG at 4–6 and MAX_PARALLEL_THUMBNAILS at 2–4 to avoid overloading your system. Higher values may cause UI freezes.
• Large video files (20GB+): The server automatically adjusts segment duration for large files. No manual tuning needed.
• Network access: To access from other devices on your LAN, bind to 0.0.0.0 and ensure your firewall allows the configured port.

Tech Stack

Backend: Rust, Axum, Tokio, DashMap, tower-http

Frontend: React, TypeScript, Vite, Tailwind CSS, HLS.js, Zustand, TanStack Query, Framer Motion