📖 Usage Guide

Complete guide to using HomeTube.

� Quick Start

Enter URL: Paste any supported video URL.
Choose Destination: Pick or create a folder for the download.
Start Download: Follow progress directly in the web interface.

🏆 Quality System & Download Strategies

HomeTube analyses the available video/audio formats for every URL and keeps things simple: it builds at most two quality profiles per video.

Profile 1 → Best format actually available (highest resolution + modern codecs).
Profile 2 → Fallback profile using the next-best format when a download fails or a device is less compatible.

This approach avoids the old 4-profile matrix. The app now focuses on real formats detected on the video, so you always download what the platform truly exposes.

🔍 How It Works

Scan formats with yt-dlp to list all video and audio tracks.
Rank the available codecs (AV1 > VP9 > H.264, Opus > AAC) and resolutions.
Build up to two profiles that pair the best video/audio combinations available for that video.
Download using the first profile; if that fails and fallback is allowed, try the second profile.

Some videos expose only one good combination. In that case the system just uses that single profile.

📦 Output Containers

MKV (default): full codec support, ideal for Plex/Jellyfin and archival.
MP4: choose when you need maximum device compatibility; limited to AAC audio.
WebM: only used internally when needed, not recommended as final output.

🎯 Download Modes

Auto Best (default) → Tries Profile 1, then Profile 2 if needed. Balanced quality and success rate.
Best Only → Only uses Profile 1. Stops immediately if the best combination is unavailable.
Choose Profile → Lets you force Profile 1 or Profile 2 manually.
Choose Formats → Advanced mode; pick exact yt-dlp format IDs and bypass the profile builder.

💡 Choosing a Mode

Pick Auto Best when you just want the best possible quality with automatic fallback.
Pick Best Only when you prefer to fail rather than download a fallback profile.
Pick Choose Profile for deterministic behaviour (e.g. always VP9 fallback).
Pick Choose Formats when you already know the format IDs you want.

🛠️ Manual Override (Advanced)

If you want complete control, you can inspect all formats, pick any combination manually, and download without the profile system. This is useful for troubleshooting or niche devices.

✅ Summary: HomeTube now relies on a 2-profile maximum strategy driven by real format detection. The default behaviour gives you the best quality available with a single fallback attempt.

🌐 Supported Video Sources

This application supports 1800+ video platforms through yt-dlp integration:

🎥 Major Video Platforms

YouTube - Individual videos (with SponsorBlock)
Vimeo - Standard and premium videos
Dailymotion - Individual videos
Twitch - VODs, clips, live streams
TikTok - Individual videos, user profiles
Facebook - Videos, reels (authentication required)
Instagram - Videos, stories (authentication may be required)

📺 TV & Streaming

Arte - European cultural content
France TV - French public television
BBC iPlayer - UK content (geo-restricted)
ZDF - German public television
RAI - Italian public television

🎵 Audio Platforms

SoundCloud - Individual tracks
Bandcamp - Albums and individual tracks
Mixcloud - DJ sets and radio shows

🎮 Gaming & Tech

Kick - Live streams and VODs
Odysee - Decentralized video platform
PeerTube - Federated video instances

🔗 Other Sources

Reddit - Video posts
Archive.org - Historical video content
Bitchute - Alternative video platform
And 1790+ more platforms...

💡 Quick Test: Paste any video URL to check compatibility. Most video sites are supported automatically.

🎯 Getting Started

Once installed, access the web interface at:

Local: http://localhost:8501
Network: http://your-server-ip:8501

3. File Organization

Smart Folder Structure:

downloads/
├── Tech/                    # Auto-categorized
│   ├── Python Tutorial.mp4
│   └── Docker Guide.mp4
├── Music/                   # Manual organization
│   └── My Downloads/
└── Documentaries/           # Custom folders
    └── Nature Series/

Naming Options:

Keep original video title
Custom filename with sanitization
Automatic duplicate handling

🔒 Authentication & Private Content

🚨 Cookies are essential for reliable video downloads, not just for restricted videos. Modern platforms like YouTube use sophisticated protection mechanisms:

Why Cookies Are Critical

🔐 Encrypted Signatures: Video streams use encrypted signatures (n-sig) requiring authentication
🛡️ Anti-Bot Measures: Platforms detect and block automated access without proper authentication
📺 Stream Protection: Even public videos may have signature-protected audio/video streams
⚡ Error Prevention: Prevents "signature extraction failed" and "format unavailable" errors

What You Can Access With Cookies

✅ Public Videos: Reliable access to all quality formats and streams
🔓 Restricted Content: Age-restricted, member-only, and region-locked videos
🎵 High-Quality Audio: Signature-protected audio formats
🚀 Better Performance: Reduced throttling and connection issues

YouTube expects updated cookies and will raise errors when cookies are expired.

There are several methods to setup cookies, depending on your HomeTube service configuration.

Browser Cookie Method

Browser Cookie Method is recommended on a machine sharing directly a browser like a personal computer.

Select Browser: Choose from Chrome, Firefox, Safari, Edge, etc.
Login Verification: Ensure you're logged into YouTube in that browser
Automatic Extraction: Cookies are extracted securely
Download: Access age-restricted and private content

Supported Browsers:

Google Chrome / Chromium
Mozilla Firefox
Safari (macOS)
Microsoft Edge
Opera
Brave

Cookie File Method

Cookie File Method is recommended on machines without a browser such as a HomeLab.

Install Extension: Use Get cookies.txt
Export Cookies: Visit YouTube and export cookies
Upload File: Place in configured cookies directory
Automatic Detection: Application loads cookies automatically

Update HomeLab Cookies

For HomeLab setups not having a browser, we want to easily update cookies file. We can do it easily, manually, when it's necessary, from personal computer with :

Extract cookies on your personal computer using "Get cookies.txt"
Sync on HomeLab via rsync when necessary

# From your personal computer, sync cookies to your HomeLab
rsync -avz ~/Downloads/cookies.txt user@homelab-ip:/path/to/hometube/cookies/

With specific permissions:

# From your personal computer, sync cookies to your HomeLab with specific remote permissions
rsync -avz --chown=100000:100996 --chmod=ug=rwX,o=r ~/Downloads/cookies.txt user@homelab-ip:/path/to/hometube/cookies/

What Requires Authentication?

YouTube: Age-restricted, private/unlisted, premium content
Facebook/Instagram: Most content requires login
Twitch: Some VODs and subscriber content
Platform-specific: Member-only or geo-restricted content
General: Live streams and premium features

🛠️ Technical: How the 2-Profile Builder Works

The quality selector keeps the implementation simple while staying robust:

Collect formats: yt-dlp returns the exact list of video/audio tracks available for the URL.
Filter noise: unusable entries (missing codecs, DRM protected, audio-only for video jobs) are ignored.
Score combinations: resolutions and codecs are ranked so that modern formats win.
Build up to two profiles:

profile-1 → best score.
profile-2 → next best score (optional, only if clearly different).

Download logic:

Auto Best tries profile-1, then profile-2 if allowed.
Best Only tries profile-1 only.
Refuse Downgrade stops after the first failure.

Because the list is derived from a real probe, there is no static matrix to maintain—each download reflects the exact formats exposed by the platform.

🎵 Audio & Subtitles

Subtitle Options

Download Types:

Embedded: Burned into video (cannot be disabled)
Separate Files: .srt/.vtt files alongside video
Both: Maximum compatibility

Language Selection:

Automatic detection of available languages
Multiple subtitle tracks supported
Auto-generated captions when available
Manual language override

Subtitle Sources:

Original creator subtitles (highest quality)
Community contributions
YouTube auto-generated
Translated versions

⚠️ Auto-Generated Subtitles Limitations

Important considerations for auto-generated subtitles:

Auto-generated subtitles have significant limitations that users should be aware of:

Poor Formatting: Auto-generated subtitles often lack proper sentence breaks and punctuation
Readability Issues: Text tends to stick together and chain in an illegible way
Display Problems: Most video players cannot properly format these subtitles for optimal reading
YouTube Client Exception: Only the official YouTube client can display auto-generated subtitles correctly

Our Approach:

We keep the write-auto-subs option enabled by default
Rationale: Having imperfect subtitles is better than having no subtitles at all
Recommendation: Use manual or community-contributed subtitles when available for better quality

Best Practices:

Check for manual subtitles first - Look for creator-provided or community subtitles
Use auto-generated as fallback - Only when no other options are available
Consider post-processing - You may want to edit auto-generated subtitles for better readability
Test playback - Verify subtitle quality in your preferred video player

Audio Processing

Quality Options:

Best available audio quality
Specific bitrate selection
Audio-only downloads
Audio format conversion

🚫 SponsorBlock Integration (YouTube)

Note: SponsorBlock is specifically for YouTube videos. Other platforms don't have this feature.

Automatic Sponsor Detection

What Gets Detected:

Sponsor segments
Self-promotion
Interaction reminders (like/subscribe)
Intro/outro sections
Music/off-topic segments
Filler content

Sponsor Handling Options

Removal Methods:

Skip: Remove segments entirely (default)
Mark: Add chapter markers for manual skipping
Keep: Download complete video with timestamps

Processing Modes:

Aggressive: Remove all detected segments
Conservative: Only remove clear sponsorships
Custom: Choose specific segment types
Disabled: No sponsor processing

Manual Review

Preview Segments: Review detected sponsors before processing
Custom Selection: Choose which segments to remove
Time Adjustment: Fine-tune segment boundaries
Save Preferences: Remember settings for future downloads

✂️ Video Cutting & Editing

Time Range Selection

Flexible Time Formats:

30          # 30 seconds
1:30        # 1 minute 30 seconds
12:45:30    # 12 hours 45 minutes 30 seconds
2h15m       # 2 hours 15 minutes
90s         # 90 seconds

Selection Methods:

Manual time input
Chapter-based selection
Sponsor-segment boundaries
Custom ranges

Cutting Modes

Keyframe Mode (Fast):

No re-encoding required
Instant processing
May not be frame-accurate
Preserves original quality

Precise Mode (Accurate):

Frame-accurate cutting
Re-encoding required
Slower processing
Customizable quality settings

Batch Cutting:

Multiple time ranges
Automatic segment joining
Consistent quality settings

Video Processing Options

Quality Settings:

Maintain original quality
Custom resolution/bitrate
Compression level adjustment
Format conversion

📁 Advanced Features

Custom Output Settings

File Naming:

Template-based naming
Variable substitution (title, date, quality)
Sanitization for filesystem compatibility
Duplicate handling strategies

Format Options:

Video format selection (MP4, WebM, MKV)
Audio format preference
Subtitle format choice
Metadata preservation

Progress Monitoring

Real-time Information:

Download speed and ETA
Fragment progress for segmented downloads
Post-processing status
Error notifications

Detailed Logging:

Download history
Error diagnostics
Performance metrics
Debug information

🏠 HomeLab Integration

Media Server Compatibility

Plex Integration:

Optimized folder structure
Metadata preservation
Automatic library scanning
Subtitle compatibility

Jellyfin/Emby Support:

Open-source media server compatibility
Chapter preservation
Multiple audio tracks
Thumbnail generation

Network Access

Multi-device Usage:

Access from any device on your network
Mobile-friendly interface
Concurrent downloads
Shared download queue

Remote Access:

VPN-compatible
Reverse proxy support
SSL/HTTPS configuration
Authentication options

🌐 Platform-Specific Tips

YouTube

SponsorBlock: Full integration for ad/sponsor removal
Cookies: Required for age-restricted and private content
Live Streams: Can download ongoing streams

Vimeo

Quality: Often provides high-quality originals
Privacy: Respect password-protected videos
Embeds: Can extract from embedded players

TikTok

Watermarks: May include TikTok watermarks
Quality: Usually mobile-optimized formats
Trending: Popular videos may have higher success rates

Twitch

VODs: Past broadcasts with chat replay
Clips: Short highlights and moments
Authentication: Required for subscriber-only content

Facebook/Instagram

Authentication: Most content requires login cookies
Stories: Time-limited content may expire
Quality: Variable based on original upload

Dailymotion/Vimeo

European Content: Good alternative sources
Professional: Often higher production quality
Geo-restrictions: Some content may be region-locked

💡 Testing New Sites: Try any video URL! The application will automatically detect if the platform is supported.

⚙️ Advanced Options

Custom yt-dlp Arguments

For power users who need specific functionality, HomeTube supports custom yt-dlp arguments through the Advanced Options section.

🔧 How to Use

Expand Advanced Options: Click the expander in the main interface
Enter Arguments: Add custom yt-dlp arguments in the text field
Apply: Arguments are automatically applied to all downloads

📝 Common Use Cases

Network Configuration:

--proxy http://your-proxy-server:8080
--proxy socks5://127.0.0.1:1080

File Size Management:

--max-filesize 500M
--min-filesize 10M

Download Control:

--retries 10
--fragment-retries 10
--retry-sleep 5

Authentication:

--cookies /path/to/cookies.txt
--username your_username --password your_password

Output Control:

--write-info-json
--write-description
--write-thumbnail

Quality Override:

--format-sort "res:720,fps:30"
--max-downloads 5

🌍 Environment Variables Configuration

HomeTube supports comprehensive environment variable configuration for all its features, including custom yt-dlp arguments and system defaults:

📊 Quality & Download Preferences

Variable	Default	Description	Options
`VIDEO_QUALITY_MAX`	`max`	Maximum video resolution limit	`max`, `2160`, `1440`, `1080`, `720`, `480`, `360`
`QUALITY_DOWNGRADE`	`true`	Allow fallback to second-best profile on failure	`true`, `false`
`EMBED_CHAPTERS`	`true`	Embed chapters by default	`true`, `false`
`EMBED_SUBTITLES`	`true`	Embed subtitles by default	`true`, `false`
`CUTTING_MODE`	`keyframes`	Video cutting precision	`keyframes`, `precise`

🎵 Audio Language Preferences

Variable	Default	Description	Options
`LANGUAGE_PRIMARY`	`en`	Primary audio language preference	`en`, `fr`, `es`, `de`, `ja`, etc.
`LANGUAGES_SECONDARIES`	(empty)	Secondary audio languages (comma-separated)	`en,es,de`
`LANGUAGE_PRIMARY_INCLUDE_SUBTITLES`	`true`	Include subtitles for primary language	`true`, `false`
`VO_FIRST`	`true`	Prioritize original voice (VO) before primary language	`true`, `false`

🌐 Browser Configuration

Variable	Default	Description	Options
`BROWSER_SELECT`	`chrome`	Default browser for cookies	`chrome`, `firefox`, `edge`, `safari`, `chromium`

🎯 Core Configuration

Variable	Default	Description	Example
`DOWNLOAD_FOLDER`	`/data/downloads`	Main download directory	`/home/user/Videos`
`TMP_DOWNLOAD_FOLDER`	`/data/tmp`	Temporary processing folder	`/tmp/hometube`
`HOMETUBE_LANGUAGE`	`en`	Interface language	`en`, `fr`
`YTDLP_CUSTOM_ARGS`	(empty)	Default yt-dlp arguments	`--max-filesize 100M`
`DEBUG`	`false`	Enable debug mode	`true`, `false`

🛠️ Custom yt-dlp Arguments

You can set default custom arguments using the YTDLP_CUSTOM_ARGS environment variable:

# In your .env file
YTDLP_CUSTOM_ARGS=--max-filesize 100M --write-info-json

⚠️ Important Notes:

Format Arguments: Don't override --format as it's managed by the quality selector
Output Arguments: Don't override output path arguments
Safety: Invalid arguments will be ignored with error messages
Priority: UI arguments override environment variables

🔄 Argument Parsing:

Arguments are parsed safely using shell-style parsing:

Quoted Strings: Use quotes for arguments with spaces: --user-agent "Custom Agent 1.0"
Multiple Arguments: Separate with spaces: --retries 3 --max-filesize 100M
Complex Paths: Quote paths with spaces: --cookies "/path with spaces/cookies.txt"

📚 yt-dlp Examples:

Corporate Network:

YTDLP_CUSTOM_ARGS=--proxy http://proxy.company.com:8080 --retries 5

Bandwidth Limited:

YTDLP_CUSTOM_ARGS=--limit-rate 1M --max-filesize 50M

Archival Download:

YTDLP_CUSTOM_ARGS=--write-info-json --write-description --write-thumbnail --write-sub

Development/Testing:

YTDLP_CUSTOM_ARGS=--verbose --print-json --simulate

🔧 Usage Examples

Best Quality Setup:

# Maximum quality with fallback allowed
VIDEO_QUALITY_MAX=max
QUALITY_DOWNGRADE=true
EMBED_CHAPTERS=true
EMBED_SUBTITLES=true
CUTTING_MODE=precise

Fast Download Setup:

# Quick downloads with 1080p limit
VIDEO_QUALITY_MAX=1080
QUALITY_DOWNGRADE=true
CUTTING_MODE=keyframes

Strict Quality Control:

# Best quality only, no fallback
VIDEO_QUALITY_MAX=2160
QUALITY_DOWNGRADE=false

📝 Configuration Notes

Priority: UI selections always override environment defaults
Auto Selection: System automatically selects 2 best profiles based on available formats
Fallback Behavior: When QUALITY_DOWNGRADE=true, tries Profile 2 if Profile 1 fails
Resolution Limit: VIDEO_QUALITY_MAX caps the maximum resolution (e.g., 1080 limits to 1080p even if 4K is available)

🔧 Troubleshooting

Common Issues

Download Failures:

Check internet connection
Verify URL validity and platform support
Try different quality settings
Check authentication status for platform

Quality Issues:

Video quality lower than expected → Check manual format selection
Audio sync problems → Try different cutting modes
Large file sizes → Adjust quality settings

Authentication Problems:

Cookies expired → Re-extract browser cookies
Private video access denied → Verify account permissions
Age restrictions → Ensure proper authentication

Performance Issues:

Slow downloads → Check network speed and server load
High CPU usage → Reduce concurrent downloads
Storage issues → Monitor disk space

Error Messages

"No formats available":

Video may be private or deleted
Try with authentication
Check URL format

"FFmpeg not found":

Install FFmpeg system-wide
Check PATH configuration
Verify installation

"Disk space insufficient":

Free up storage space
Choose lower quality settings
Use temporary directory on different drive

📊 Best Practices

For Best Quality

Use manual format selection
Choose highest bitrate options
Preserve original audio
Keep subtitles embedded

For Storage Efficiency

Use auto quality selection
Enable sponsor removal
Choose efficient codecs (H.264)
Regular cleanup of downloads

For Performance

Limit concurrent downloads
Use SSD for temporary files
Close unused browser tabs
Monitor system resources

For Organization

Use consistent folder structure
Enable automatic categorization
Set up meaningful naming patterns
Regular backup of important downloads

Next: Docker Guide - Container deployment options

FilesExpand file tree

usage.md

Latest commit

History