HomeTube

🏡 Universal Video Downloader for Your Media Server

Download, process, and organize ads-free best-quality videos at Home.

🎬 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:

• 🚫 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: 1. 🥇 Best Available → Highest resolution with most modern codec (e.g., 4K AV1 + Opus) 2. 🥈 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

🚀 Benefits: - ✅ Always gets the best quality actually available for each video - ✅ No generic fallbacks - uses real format analysis - ✅ Fast downloads with minimal retries (max 2 attempts) - ✅ Supports all modern codecs: AV1, VP9, H.264, Opus, AAC

👉 Full details on quality detection & strategies

🎯 Smart Download Management

Intelligent download system that adapts to your needs:

• 📁 Auto-Organization: Videos organized by channel/creator automatically
• ⚡ Resume Support: Interrupted downloads automatically resume
• 💾 Storage Optimization: Duplicate detection and space management

Learn more about download features.

📋 Intelligent Playlist Management

Powerful playlist synchronization with resilient tracking and perfect source fidelity:

🔄 Smart Synchronization: - 📡 Source of Truth: YouTube playlist is always the reference - local library stays perfectly synchronized - 🔄 Auto-Refresh: Playlist metadata automatically refreshed on each load for accurate status - 📊 Instant Status: See exactly which videos are downloaded, pending, or new at a glance - 🎯 Incremental Downloads: Only download new videos - existing ones are preserved and tracked

📁 Resilient Video Tracking: - 🆔 ID-Based Tracking: Videos tracked by unique ID - survives title changes on YouTube - 📝 Pattern-Based Naming: Flexible filename patterns with placeholders ({idx}, {title}, {channel}, etc.) - 🔄 Smart Rename Detection: Finds renamed files in destination folder automatically - 📂 Index Preservation: Maintains playlist order even when videos are reordered upstream

🛡️ Robust Change Detection: - ➕ New Videos: Automatically detected and queued for download - 🔢 Reordering: Detect and apply index changes with smart renaming - 📂 Relocation: Move entire playlist to new folder while preserving files - 📦 Archive Mode: Removed videos can be archived instead of deleted - 🗑️ Clean Removal: Optional deletion of videos removed from source playlist

🎨 Customizable Title Patterns:

{idx} - {pretty(title)}.{ext}           → 01 - My Video Title.mkv
{pretty(title)} - {channel}.{ext}       → My Video - Creator Name.mkv  
{i:03d} - {slug(title)} [{id}].{ext}    → 001 - my-video-title [abc123].mkv

Supported placeholders: - {idx} - Smart zero-padded index (01, 02... or 001, 002... based on total) - {title} / {pretty(title)} / {slug(title)} - Video title variants - {channel} / {pretty(channel)} / {slug(channel)} - Channel name variants - {id} - Video ID • {ext} - File extension

📈 Progress Tracking: - Real-time download progress with visual indicators - Detailed sync plan preview before applying changes - Full logging of all operations for transparency

Set PLAYLIST_KEEP_OLD_VIDEOS=true (or enable Keep videos removed from playlist in the UI) to move removed entries into an Archives/ folder instead of deleting them.

🌐 Universal Platform Support

1800+ supported platforms - way beyond just YouTube:

• 📺 Major Platforms: YouTube, Twitch, Vimeo, Dailymotion, TikTok
• 🎭 Social Media: Instagram, Facebook, Twitter, Reddit
• 🎓 Educational: Coursera, Khan Academy, edX
• 🏢 Professional: LinkedIn Learning, Udemy, Skillshare
• 📺 Streaming: Netflix previews, Hulu trailers, Disney+ clips

See complete platform list.

🚀 Quick Start

⚙️ Essential Configuration

📋 HomeTube uses environment variables for all configurations: videos download paths, temporary download folder, authentication, languages, quality profiles, and more.

Depending of the setup, Docker, Docker compose, Portainer, local run, environment variables can be passed to the application in different ways.

.env file from .env.sample can be practical for rapid setup:

```bash

1. Clone repository (if