index: 01 status: Active updated: 2026-10-11 size: 737 MB

LocalFlix

Self-hosted media server for personal movie and series collections — TMDB-guided metadata, automatic subtitle fetching, GPU-accelerated transcoding, and a native Android app with offline downloads.

Overview

LocalFlix is a self-hosted media platform that lets you run your own streaming server. Upload movies and series through a TMDB-guided workflow, and the application handles title/episode detection, metadata import, transcoding, and streaming via HTTP range requests. Everything stays on your own hardware — no cloud, no tracking, no subscription.

Features

Upload and metadata:

  • Guided upload: video → identify → details → subtitles → artwork → confirm → processing, with automatic title/episode detection
  • TMDB integration: imports overview, release dates, runtime, genres, cast, studios, and IMDb IDs
  • Automatic subtitles: fetches matching subtitles from OpenSubtitles.com, preferring trusted uploaders and the most-downloaded result, with audio-based sync and a download-quota-aware retry
  • FFprobe analysis: video tracks are analyzed on upload for audio/subtitle track selection

Playback and personalization:

  • Seekable streaming with HTTP range requests, GPU-accelerated transcoding (NVENC, Quick Sync, VAAPI), and playback speed control (0.5×–2×)
  • Picture-in-picture, previous/next episode navigation with auto-advance countdown
  • Multi-profile accounts with isolated watch history, "Like / Not for me" ratings, My List, and per-profile recommendations
  • Library scanner for automated imports from local folders, plus a DLNA server for TV playback

Implementation

The stack:

  • Backend: Node.js + Express 5 serving a REST API
  • Database: MySQL 8.3 for content metadata, across 13 incremental migrations
  • Video processing: FFmpeg (via fluent-ffmpeg) for GPU-accelerated transcoding and thumbnail generation
  • Frontend: Vanilla HTML/CSS/JS — zero framework
  • Mobile: Native Android app (Kotlin) with offline downloads
  • Packaging: Docker + Docker Compose for one-command deployment

Dark/light mode with system preference detection, responsive grid layouts (5 to 2 columns), admin-only activity logging with privacy controls, and proper accessibility (focus rings, semantic HTML, contrast). Includes unit and integration tests that run in throwaway Docker containers against mock TMDB and OpenSubtitles servers.

Technologies

JavaScript Node.js Express MySQL FFmpeg Kotlin Docker partially vibe coded

Interesting Details

  • Automatic thumbnails generated from a duration-aware timestamp with first-frame fallback for short clips
  • Bitmap subtitles are automatically filtered out on upload (only text-based subs kept); sidecar .srt files are converted to WebVTT
  • Series autocomplete: type-to-search when adding episodes to existing series
  • Media files persist via Docker bind mounts to a host directory
  • Integration tests run in throwaway Docker containers against mock TMDB and OpenSubtitles servers, covering the full upload pipeline, streaming, metadata, and library scanning