Hometube
HomeTube is a friendly video downloader managing single video URL into organized content structure for automatic home media server experience.
Install / Use
/learn @EgalitarianMonkey/HometubeREADME
<img src="docs/icons/favicon.svg" alt="" width="28" height="28" style="vertical-align: -0.18em;"> HomeTube
<br/>
🏡 Universal Video Downloader for Your Media Server
Download, process, and organize ads-free best-quality videos at Home.
<br/> </div> <br/> <br/> <!-- --- --> <!-- ## 🎯 What is HomeTube? -->🎬 HomeTube is a simple web UI for downloading single videos and playlists from the internet with the highest quality available and moving them to specific local locations automatically managed and integrated by media server such as Plex or Jellyfin.
A simple friendly solution for easily integrating preferred videos from Youtube and others platforms to local media server:
<br/> <!-- ## 🏠 **HomeLab Integration** -->- 🚫 Ad-Free Content: Block natively all videos' ads and sponsors
- 🏆 Best Quality Control: Advanced best videos quality download strategy or manual override
- 🎬 Media Server Ready: Download best quality videos with explicit name and location directly in your HomeLab media server structure and get automatic watch experience on Plex, Jellyfin, Emby or even on your PC
- 📋 Intelligent Playlist Sync: Download and synchronize playlists with resilient tracking - local library stays perfectly in sync with source
- 📱 Network Access: Web interface videos download accessible from any device on your network
- 🎯 One-Click Downloads: Paste URL → Get perfectly organized video
- 🔐 Cookies Authentication: Essential for reliable downloads - unlocks restricted content and prevents signature errors
- 🎬 Advanced Processing: Cut clips, embed subtitles, convert formats
- ⚙️ Advanced Configurations: Organized advanced options including any custom yt-dlp arguments (proxy, max-filesize, etc.)
- 🎥 Video Sources: YouTube, Reddit, Vimeo, Dailymotion, TikTok, Twitch, Facebook, Instagram, etc. See complete list (1800+)
🛠️ HomeTube Options
🏠 HomeLab Integration
Automatic integration with self-hosted setup:
- 🐳 Docker Ready: One-command deployment with Docker Compose
- 🎬 Media Server Integration: Direct integration with media server thanks to well named video files automatically moved to chosen locations watched by media server such as Plex, Jellyfin, or Emby.
- 🆕 Create new folder from the UI: Create organized new folder structures when necessary from the "🆕 Create New Folder" option at the bottom of the "Destination folder" field listing menu (e.g.,
Tech/Python/Advanced) - 📱 Network Access: Web interface accessible from any device on your network
- 🔐 Secure: No cloud dependencies, everything runs locally
- ⚙️ Configurable: Extensive customization through environment variables
Setup your HomeLab integration.
🚫 Block all ads and sponsors
Automatically skip sponsors, ads, and promotional content with built-in SponsorBlock support. Just download your video and sponsors segments are automatically detected and marked.
- ✅ Auto-detection: Sponsors segments automatically identified
- ✅ Manage sponsors to block: Sponsors segments to block or mark can be managed in the UI
- ✅ Community-driven: Powered by SponsorBlock's crowd-sourced database
- ✅ Zero configuration: Works out of the box for YouTube videos
Learn more about SponsorBlock features.
🍪 Cookies Authentication (Highly Recommended)
Cookies authentication should be setup for optimal video downloading experience and to avoid common download failures.
🚨 Why Cookies Are Essential
Even for public YouTube videos, cookies are increasingly necessary because of modern protections.
They ensure higher quality, reliability, and access to all formats:
- 🏆 Access the best quality (AV1/Opus, high-res video, premium audio)
- 🔓 Unlock restricted content (age-gated, member-only, region-locked)
- 🔐 Handle encrypted signatures (n-sig) required for many video/audio streams
- 🛡️ Bypass anti-bot measures that block automated downloaders
- 📺 Ensure stream availability (audio/video may be signature-protected even for public videos)
- ⚡ Improve reliability (fewer "format unavailable" or extraction errors)
- 🎵 Get high-quality audio tracks (Opus, AAC) without failures
- 🚀 Reduce throttling for faster, more stable downloads
👉 In short: cookies are not just for private content — they’re the key to consistent, best-quality downloads.
🛠️ Setup Options
We can use Browser cookies if on a machine sharing a browser, otherwise Cookies File in HomeLab setup.
More details about Cookies authentication setup.
✂️ Advanced Video Processing
Transform your downloads with powerful built-in video processing tools:
- 🎬 Clip Extraction: Cut specific segments from videos with precision timing
- 📝 Subtitle Embedding: Automatically embed subtitles in multiple languages
- 🔄 Format Conversion: Convert between video formats (MP4, MKV, WebM, etc.)
- 🎵 Audio Extraction: Extract audio-only versions in high quality
- 📱 Mobile Optimization: Optimize videos for mobile devices
Explore all processing options.
🔧 Advanced configurations
Custom yt-dlp arguments support offers full flexibility for advanced users to tailor downloads to specific needs.
- 📱 Network configuration:
--proxy http://proxy.company.com:8080 --retries 5 - 📂 File size limits:
--max-filesize 500M --min-filesize 100M - 📋 Enhanced metadata:
--write-info-json --write-description --write-thumbnail - 🛜 Bandwidth control:
--limit-rate 1M --fragment-retries 10 - ➕ More options:
yt-dlp --options variable
Custom yt-dlp arguments can be added directly from the UI or set by default for any download with the YTDLP_CUSTOM_ARGS environment variable.
🔀 Smart Conflict Resolution: HomeTube automatically detects and resolves conflicts between base settings and custom arguments, giving priority to your custom preferences while maintaining system stability.
🎯 Smart Quality System
HomeTube uses intelligent quality detection that analyzes each video and automatically selects the best available formats with a simple 2-profile strategy:
🔍 How It Works:
- 📊 Real-time Analysis → Detects all available video formats and codecs
- 🏆 Smart Ranking → Prioritizes modern codecs (AV1 > VP9 > H.264) and audio quality (Opus > AAC)
- 🎯 Optimal Selection → Generates up to 2 best profiles from actual available formats
- 🔄 Intelligent Fallback → Tries best quality first, then second-best if needed
Quality Profiles Generated:
- 🥇 Best Available → Highest resolution with most modern codec (e.g., 4K AV1 + Opus)
- 🥈 Fallback Option → Next best combination (e.g., 4K VP9 + Opus)
Download Strategies:
- 🔄 Auto Best (Default) → Tries up to 2 optimal profiles automatically until success
- 🏆 Best Only → Only attempts highest quality, no fallback (stops if unavailable)
- 🎯 Choose Profile → Manually select from detected optimal profiles
- 📋 Choose Format → Advanced: select specific format IDs from all available formats
