Metube YouTube Downloader Service Documentation¶

Table of Contents¶

Overview
Architecture
Why Metube
Configuration Details
Access Information
Common Operations
Download Management
Backup Considerations
Troubleshooting Guide
Integration with Infrastructure
Security Considerations

Overview¶

Metube is a self-hosted web interface for youtube-dl/yt-dlp, providing a user-friendly way to download videos from YouTube and hundreds of other video platforms. It offers a clean, modern web interface that eliminates the need for command-line operations while maintaining the powerful features of the underlying yt-dlp library.

In this infrastructure, Metube is deployed as a containerized service providing: - Web-based interface for video downloads from 1000+ sites - Queue management with configurable concurrent downloads - Format selection with quality and codec options - Subtitle support with embedding and external files - Progress tracking with real-time download status - File organization with customizable naming templates

The service is exposed via the domain metube.rbnk.uk with SSL termination handled by Traefik reverse proxy.

Architecture¶

The Metube service consists of a single lightweight container with the following components:

metube (Web Interface & Download Engine)¶

Image: ghcr.io/alexta69/metube:latest
Role: Web interface frontend and yt-dlp backend integration
Internal Port: 8081 (exposed via Traefik)
Features:
React-based modern web interface
yt-dlp integration for video extraction
Download queue with progress tracking
Format selection and quality control
Subtitle downloading and embedding
File organization with custom templates

Container Architecture¶

services:
  metube:
    image: ghcr.io/alexta69/metube:latest
    container_name: metube
    restart: unless-stopped
    environment:
      - UID=1000
      - GID=1000
      - DOWNLOAD_DIR=/downloads
      - DOWNLOAD_MODE=sequential
      - MAX_CONCURRENT_DOWNLOADS=3
      - UMASK=022
    volumes:
      - ./downloads:/downloads
      - ./config:/config
    networks:
      - traefik_proxy

Why Metube¶

Metube was chosen for this infrastructure for several compelling reasons:

1. User-Friendly Interface¶

Clean, intuitive web interface eliminates command-line complexity
Real-time progress tracking with download speeds and ETAs
Queue management with ability to pause, resume, and reorder downloads
Mobile-responsive design for access from any device

2. Powerful Backend¶

Built on yt-dlp, the most capable video extraction library
Supports 1000+ video platforms beyond YouTube
Regular updates ensure compatibility with platform changes
Advanced format selection with quality and codec options

3. Self-Hosted Privacy¶

No data sent to third-party services
Complete control over downloaded content
No usage tracking or analytics
Runs entirely within your infrastructure

4. Enterprise Features¶

Configurable download limits and concurrent operations
File organization with custom naming templates
Subtitle support with multiple languages
Format conversion and quality selection

5. Low Resource Requirements¶

Lightweight container with minimal memory footprint
Efficient download management with pause/resume capabilities
No database dependencies - simple file-based storage

Configuration Details¶

Environment Variables¶

The service uses several environment variables for configuration:

# User and group IDs for file permissions
UID=1000
GID=1000

# Download configuration
DOWNLOAD_DIR=/downloads
DOWNLOAD_MODE=sequential
MAX_CONCURRENT_DOWNLOADS=3

# File permissions
UMASK=022

# Optional: Quality and format settings
QUALITY=best
FORMAT=mp4

# Optional: Output template for file naming
OUTPUT_TEMPLATE=%(title)s.%(ext)s

# Optional: Subtitle configuration
SUBTITLES=en,es
SUBTITLE_EMBED=true

# Optional: iOS compatibility
ENABLE_IOS_FORMAT=false

Download Modes¶

Sequential Mode (default): - Downloads one video at a time - Ensures consistent performance - Avoids rate limiting from video platforms - Recommended for most use cases

Concurrent Mode: - Multiple simultaneous downloads - Configurable via MAX_CONCURRENT_DOWNLOADS - Higher bandwidth usage - May trigger rate limiting

File Organization¶

Default Structure:

/srv/dockerdata/metube/downloads/
├── video1.mp4
├── video2.webm
├── playlist_name/
│   ├── video1.mp4
│   ├── video2.mp4
│   └── subtitles/
│       ├── video1.en.srt
│       └── video2.en.srt

Custom Output Templates: - %(title)s.%(ext)s - Video title with extension - %(uploader)s/%(title)s.%(ext)s - Organized by uploader - %(upload_date)s_%(title)s.%(ext)s - Include upload date - %(playlist)s/%(playlist_index)s_%(title)s.%(ext)s - Playlist organization

Access Information¶

Web Interface Access¶

URL: https://metube.rbnk.uk
Authentication: Authentik SSO (protected by authentik-secured@file middleware)
Protocol: HTTPS with automatic SSL via Traefik
Mobile Support: Responsive design works on all devices

API Access¶

Metube provides a REST API for programmatic access:

# Add video to download queue
curl -X POST https://metube.rbnk.uk/add \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=VIDEO_ID", "quality": "best"}'

# Check download status
curl https://metube.rbnk.uk/status

# Get download history
curl https://metube.rbnk.uk/downloads

Common Operations¶

Basic Video Download¶

Single Video:
Navigate to https://metube.rbnk.uk
Paste YouTube or other supported platform URL
Select quality/format (optional)
Click "Download"
Monitor progress in the queue
Playlist Download:
Paste playlist URL
Service automatically detects and queues all videos
Downloads proceed according to configured mode
Videos organized in playlist folder
Quality Selection:
Best: Highest available quality
Worst: Lowest available quality
Specific: Choose exact format (e.g., 720p, 1080p)
Audio Only: Extract audio in various formats

Download Queue Management¶

# View active downloads
docker logs metube

# Check download directory
ls -la /srv/dockerdata/metube/downloads/

# Monitor disk usage
du -sh /srv/dockerdata/metube/downloads/

# Clear completed downloads from UI
# Use web interface to manage queue

Service Management¶

# View service status
cd /srv/dockerdata/metube && docker compose ps

# Restart service
docker compose restart metube

# View logs
docker compose logs -f metube

# Update to latest version
docker compose pull && docker compose up -d

# Stop service
docker compose down

# Start service
docker compose up -d

Configuration Updates¶

# Edit configuration
nano /srv/dockerdata/metube/.env

# Apply changes (restart required)
cd /srv/dockerdata/metube
docker compose down && docker compose up -d

# Verify configuration
docker compose logs metube | grep -i config

Download Management¶

Supported Platforms¶

Metube supports 1000+ video platforms via yt-dlp, including:

Major Platforms: - YouTube (videos, playlists, channels) - Vimeo - Dailymotion - Twitch (VODs and clips) - Facebook - Instagram - Twitter/X - TikTok - Reddit

Educational: - Coursera - edX - Udemy - Khan Academy

News & Media: - BBC iPlayer - CNN - NBC - CBS

Live Streaming: - Twitch streams - YouTube Live - Facebook Live

Format Options¶

Video Formats: - MP4 (best compatibility) - WebM (smaller file sizes) - MKV (high quality, large files) - AVI (legacy support)

Audio Formats: - MP3 (universal compatibility) - M4A (Apple ecosystem) - OGG (open source) - FLAC (lossless)

Quality Settings: - 4K (2160p) - where available - 1080p HD - 720p HD - 480p SD - 360p (mobile) - Audio only

Subtitle Management¶

Automatic Subtitles: - Downloads available subtitle tracks - Supports multiple languages - Can embed in video files - External .srt files for compatibility

Configuration:

# Enable subtitle download
SUBTITLES=en,es,fr
SUBTITLE_EMBED=true

# External subtitle files
SUBTITLE_EMBED=false

Backup Considerations¶

What to Backup¶

Downloaded Content (/srv/dockerdata/metube/downloads/):
All downloaded videos and audio files
Subtitle files
Organized folder structure
Size: Can be large (GBs to TBs)
Configuration (/srv/dockerdata/metube/.env):
Environment variable settings
Download preferences
Output templates
Size: < 1KB
Container Configuration (/srv/dockerdata/metube/docker-compose.yml):
Service definition
Traefik routing
Volume mounts
Size: < 5KB

Backup Strategy¶

Option 1: Full Backup (for important content):

# Create backup directory
mkdir -p /srv/backups/metube/

# Backup downloads (large)
rsync -av /srv/dockerdata/metube/downloads/ /srv/backups/metube/downloads/

# Backup configuration
cp /srv/dockerdata/metube/.env /srv/backups/metube/
cp /srv/dockerdata/metube/docker-compose.yml /srv/backups/metube/

Option 2: Configuration Only (downloads are re-downloadable):

# Backup only configuration
tar -czf /srv/backups/metube-config-$(date +%Y%m%d).tar.gz \
  -C /srv/dockerdata/metube .env docker-compose.yml

Option 3: Selective Backup (important downloads only):

# Create list of important downloads
find /srv/dockerdata/metube/downloads/ -name "*.mp4" -mtime -30 > important_downloads.txt

# Backup based on list
rsync -av --files-from=important_downloads.txt / /srv/backups/metube/

Backup Automation¶

Integration with existing backup system:

# Add to /srv/dockerdata/_scripts/infrastructure-backup.sh
echo "Backing up Metube configuration..."
tar -czf "${BACKUP_DIR}/metube-config.tar.gz" \
  -C /srv/dockerdata/metube .env docker-compose.yml

# Optional: Backup recent downloads only
echo "Backing up recent Metube downloads..."
find /srv/dockerdata/metube/downloads/ -mtime -7 -type f \
  -exec cp --parents {} "${BACKUP_DIR}/metube-recent/" \;

Troubleshooting Guide¶

Common Issues¶

1. Video Download Fails¶

Symptoms: Download starts but fails with error Causes: - Video removed or made private - Geographic restrictions - Platform API changes - Rate limiting

Fix:

# Check yt-dlp version
docker exec metube yt-dlp --version

# Update container for latest yt-dlp
cd /srv/dockerdata/metube
docker compose pull && docker compose up -d

# Test URL manually
docker exec metube yt-dlp --simulate "VIDEO_URL"

2. Slow Download Speeds¶

Symptoms: Downloads taking much longer than expected Causes: - Network congestion - Platform throttling - Multiple concurrent downloads - Large file sizes

Fix:

# Reduce concurrent downloads
# Edit .env file
MAX_CONCURRENT_DOWNLOADS=1
DOWNLOAD_MODE=sequential

# Restart service
docker compose restart metube

3. Disk Space Full¶

Symptoms: Downloads fail with disk space errors Causes: Download directory full

Fix:

# Check disk usage
df -h /srv/dockerdata/metube/downloads/

# Clean old downloads
find /srv/dockerdata/metube/downloads/ -mtime +30 -delete

# Move large files to external storage
rsync -av /srv/dockerdata/metube/downloads/ /external/storage/metube/

4. Permission Errors¶

Symptoms: Cannot write files, permission denied errors Causes: UID/GID mismatch

Fix:

# Check current ownership
ls -la /srv/dockerdata/metube/downloads/

# Fix ownership
sudo chown -R 1000:1000 /srv/dockerdata/metube/downloads/

# Verify UID/GID in .env
grep -E "(UID|GID)" /srv/dockerdata/metube/.env

5. Service Not Accessible¶

Symptoms: Cannot access web interface Causes: Traefik routing, DNS, or container issues

Fix:

# Check service status
docker compose -f /srv/dockerdata/metube/docker-compose.yml ps

# Check Traefik routing
curl -H "Host: metube.rbnk.uk" http://localhost/

# Check DNS resolution
nslookup metube.rbnk.uk

# Check container logs
docker logs metube

Debug Commands¶

# Check container health
docker inspect metube | grep -A 10 "Health"

# Test yt-dlp functionality
docker exec metube yt-dlp --list-extractors | grep youtube

# Check available formats for a video
docker exec metube yt-dlp -F "VIDEO_URL"

# Monitor download progress
docker logs -f metube

# Check file permissions
docker exec metube ls -la /downloads

# Test network connectivity
docker exec metube ping youtube.com

Log Analysis¶

# View all logs
docker logs metube

# Follow logs in real-time
docker logs -f metube

# Search for errors
docker logs metube 2>&1 | grep -i error

# Check yt-dlp specific logs
docker logs metube 2>&1 | grep yt-dlp

# Monitor download progress
docker logs metube 2>&1 | grep -E "(Download|Progress|ETA)"

Integration with Infrastructure¶

Traefik Integration¶

Metube integrates with the Traefik reverse proxy for external access:

labels:
  - "traefik.enable=true"
  - "traefik.docker.network=traefik_proxy"
  - "traefik.http.routers.metube-http.rule=Host(`metube.rbnk.uk`)"
  - "traefik.http.routers.metube-http.entrypoints=web"
  - "traefik.http.routers.metube-http.middlewares=redirect-to-https@file"
  - "traefik.http.routers.metube.rule=Host(`metube.rbnk.uk`)"
  - "traefik.http.routers.metube.entrypoints=websecure"
  - "traefik.http.routers.metube.tls.certresolver=cf"
  - "traefik.http.services.metube.loadbalancer.server.port=8081"

Network Configuration¶

Single Network Architecture: - Uses traefik_proxy network for external access - No internal network needed (standalone service) - Direct access via Traefik reverse proxy

DNS Management¶

DNS record created via Cloudflare API:

# Create DNS record
./_scripts/cloudflare-dns-create.sh metube

# Verify DNS resolution
nslookup metube.rbnk.uk

Monitoring Integration¶

Prometheus Metrics (if monitoring is needed):

# Add custom metrics exporter
# Monitor download queue size
# Track download success/failure rates
# Monitor disk usage of downloads directory

Grafana Dashboard (optional): - Download activity graphs - Storage usage trends - Service availability monitoring - Download success rates

Backup Integration¶

Integration with existing infrastructure backup:

# Add to backup scripts
echo "Metube configuration backup" >> /srv/dockerdata/_scripts/infrastructure-backup.sh

# Optional: Include in cloud backup for important downloads
# Configure rclone to sync important downloads to cloud storage

Security Considerations¶

Access Control¶

Current Setup: Protected by Authentik SSO - Requires Authentik authentication for access - Users must be authenticated via Authentik before accessing the service - Integrated with infrastructure-wide SSO via Traefik middleware

Enhanced Security Options:

Traefik BasicAuth:

labels:
  - "traefik.http.routers.metube.middlewares=auth@file"
  # Define auth middleware in Traefik configuration

Network Restrictions:

# Limit to internal network only
# Remove traefik_proxy network
# Access via VPN or internal network only

Download Security¶

Content Validation: - Downloaded files should be scanned for malware - Avoid downloading executable files - Be cautious with unknown sources

Storage Security:

# Set restrictive permissions
UMASK=077  # Owner only access

# Regular cleanup
find /srv/dockerdata/metube/downloads/ -mtime +30 -delete

Platform Compliance¶

YouTube Terms of Service: - Personal use and backup purposes - No redistribution of downloaded content - Respect copyright and fair use - Educational and research purposes

General Best Practices: - Don't download copyrighted content for distribution - Respect platform rate limits - Use for personal/educational purposes - Follow local copyright laws

Conclusion¶

The Metube service provides a user-friendly, self-hosted solution for video downloading from hundreds of platforms. Its lightweight architecture, powerful backend, and clean web interface make it an excellent addition to the infrastructure for content creators, educators, and media archivists.

Key benefits: - Simple deployment with single container - Web-based interface eliminates command-line complexity - Supports 1000+ video platforms via yt-dlp - Configurable download management with quality control - Self-hosted privacy with no third-party dependencies - Integration with existing infrastructure and backup systems

For production use, consider implementing authentication, monitoring disk usage, and establishing content retention policies. The service's efficiency and extensive platform support make it a valuable tool for content archival and offline media consumption.