Hugging Face's logo

Spaces:
Taf2023
/
Universal-Media-Downloader
Sleeping

App Files Community
Universal-Media-Downloader / README.md
Taf2023's picture
Taf2023
Upload 8 files
c0a4ca6 verified
preview code
|
Raw History Blame Contribute Delete
9.2 kB
metadata 
title: Universal Media Downloader
emoji: 🎥
colorFrom: blue
colorTo: indigo
sdk: docker
sdk_version: 1.4.0
app_file: app.py
pinned: false

A professional, accessible web application for downloading videos and audio from 1000+ platforms using yt-dlp. Built with accessibility-first design, mobile optimization, and automatic library updates.

Features

🎥 Universal Platform Support

  • YouTube, Vimeo, Dailymotion, Twitch
  • TikTok, Instagram, Twitter/X, Facebook
  • Reddit, SoundCloud, Spotify, Bandcamp
  • 1000+ additional platforms via yt-dlp

♿ Accessibility First

  • Screen reader compatible (ARIA labels, live regions)
  • Keyboard navigation support
  • High contrast design (WCAG AAA compliant)
  • Large touch targets for mobile users
  • Voice announcements for real-time status

📱 Mobile Optimized

  • Responsive design with touch-friendly interface
  • Progressive Web App (PWA) capabilities
  • Offline mode detection
  • Optimized for all screen sizes

🔄 Smart Features

  • Automatic yt-dlp updates (24-hour intervals)
  • Real-time download progress tracking
  • Format selection with quality options
  • Download queue management
  • Privacy mode support
  • Download history

🛠 Technical Features

  • RESTful API backend (Flask)
  • Real-time progress monitoring
  • Error handling and validation
  • Service worker for caching
  • CORS support for cross-origin requests

Quick Start

Deploy to Hugging Face Spaces

Docker Spaces (Recommended)

  1. Create a new Space:

    • Go to Hugging Face Spaces
    • Click "Create new Space"
    • Choose "Docker" as the SDK
    • Name your space (e.g., your-username/media-downloader)

  2. Upload files:

    • Upload all files from this repository
    • This README.md includes the required Docker configuration
    • The Dockerfile will be used to build the container

  3. Build and Deploy:

    • The Dockerfile contains all necessary dependencies
    • Container will be automatically built and deployed
    • Access your application at the provided space URL

Local Development

Option 1: Direct Python (Development) 

# Clone and install dependencies
git clone <repository-url>
cd universal-media-downloader
pip install -r requirements.txt

# Run the Flask application
python app.py

The application will be available at http://localhost:7860

Option 2: Docker (Production) 

# Build the Docker image
docker build -t media-downloader .

# Run the container
docker run -p 7860:7860 media-downloader

Usage

Web Interface

The Flask application provides a complete web interface for media downloading:

  1. Enter URL: Paste any media URL in the input field
  2. Analyze: Click "Get Formats" to fetch available options
  3. Select Format: Choose your preferred quality and format
  4. Download: Click "Download" to start the download
  5. Monitor: Track progress and view download history

API Usage

The application provides a RESTful API for programmatic access:

import requests

# Get available formats
response = requests.post('http://localhost:7860/api/formats', 
                        json={'url': 'https://www.youtube.com/watch?v=...'})
formats = response.json()

# Start download
download_response = requests.post('http://localhost:7860/api/download',
                                 json={
                                     'url': 'https://www.youtube.com/watch?v=...',
                                     'format_id': 'best'
                                 })

API Documentation

Endpoints

GET /api/health

Check API health status and yt-dlp version.

Response:

{
  "status": "healthy",
  "yt_dlp_version": "2023.11.16",
  "last_update_check": "2025-11-07T10:24:00Z",
  "active_downloads": 2,
  "queue_size": 1
}

POST /api/formats

Extract available formats from a URL.

Request:

{
  "url": "https://www.youtube.com/watch?v=..."
}

Response:

{
  "success": true,
  "title": "Video Title",
  "uploader": "Channel Name",
  "platform": "YouTube",
  "duration": 180,
  "thumbnail": "https://...",
  "formats": [
    {
      "id": "best",
      "ext": "mp4",
      "vcodec": "h264",
      "acodec": "aac",
      "width": 1920,
      "height": 1080,
      "filesize": 104857600,
      "format_note": "1080p",
      "type": "video"
    }
  ]
}

POST /api/download

Start a download.

Request:

{
  "url": "https://www.youtube.com/watch?v=...",
  "format_id": "best",
  "download_id": "dl_1234567890"
}

GET /api/progress/<download_id>

Get download progress.

Response:

{
  "success": true,
  "download_id": "dl_1234567890",
  "progress": {
    "status": "downloading",
    "percentage": 45.7,
    "speed": 1024000,
    "eta": 120,
    "filename": "video.mp4"
  }
}

POST /api/update

Manually trigger yt-dlp update.

GET /api/supported-platforms

Get list of supported platforms.

Supported Platforms

Video Platforms

  • YouTube (including 4K, 8K, live streams)
  • Vimeo (including Vimeo Pro, premium content)
  • Dailymotion
  • Twitch (streams and VODs)
  • TikTok (videos and live streams)
  • Instagram (posts, reels, stories)
  • Twitter/X (videos)
  • Facebook (public videos)
  • Reddit (video posts)

Audio Platforms

  • SoundCloud
  • Spotify (non-premium limitations apply)
  • Bandcamp
  • Audiomack
  • Mixcloud

Other Platforms

  • 1000+ additional platforms supported by yt-dlp

Accessibility Features

Screen Reader Support

  • Complete ARIA labeling for all interactive elements
  • Live region announcements for status updates
  • Semantic HTML structure
  • Proper heading hierarchy

Keyboard Navigation

  • Full keyboard accessibility
  • Tab order optimization
  • Escape key support for modals
  • Enter/Space activation for buttons

Visual Accessibility

  • High contrast color scheme (WCAG AAA compliant)
  • Large touch targets (minimum 44px)
  • Clear focus indicators
  • Scalable fonts and UI elements

Motor Accessibility

  • Large clickable areas
  • Generous spacing between elements
  • Touch-friendly interface design

Configuration

Environment Variables

For production deployment, you can set these environment variables:

PORT=7860                    # Port for the application
DEBUG=False                  # Debug mode (set to False in production)
HF_TOKEN=your_token_here     # Optional: Hugging Face token

Docker Build Configuration

The Dockerfile includes:

  • Python 3.11 base image for optimal performance
  • FFmpeg for video/audio processing
  • Gunicorn WSGI server for production
  • Port 7860 exposed for HTTP traffic
  • Automatic dependency installation from requirements.txt

Build Process

  1. Base image download (python:3.11-slim)
  2. System dependencies installation (ffmpeg)
  3. Python packages installation from requirements.txt
  4. Application code copying
  5. Download directory creation
  6. Container startup with Gunicorn

Auto-Update Settings

The application automatically updates yt-dlp every 24 hours to support new platforms and features. You can:

  • Enable/disable auto-updates in settings
  • Manually trigger updates via the API
  • Monitor update status in the health endpoint

Troubleshooting

Common Issues

  1. "Connection failed"

    • Check if the backend service is running
    • Verify the API base URL
    • Check network connectivity

  2. "yt-dlp update failed"

    • Manually update via API endpoint
    • Check internet connection
    • Verify package installation

  3. "Download failed"

    • Verify the URL is valid and accessible
    • Check if the platform is supported
    • Try a different format option

Logs and Debugging

  • Application logs: Check the terminal output
  • Browser console: Use F12 developer tools
  • API logs: Monitor network requests in dev tools

Technical Architecture

Frontend

  • HTML5: Semantic structure with accessibility features
  • CSS3: Modern styling with CSS Grid and Flexbox
  • JavaScript ES6+: Progressive enhancement
  • PWA: Service worker for offline capabilities

Backend

  • Flask: RESTful API framework
  • yt-dlp: Video/audio extraction engine
  • APScheduler: Scheduled task management
  • CORS: Cross-origin resource sharing

Deployment

  • Hugging Face Spaces: Primary deployment target
  • Docker: Alternative deployment option
  • Gunicorn: Production WSGI server

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

License

This project is open source and available under the MIT License.

Support

For issues and questions:

  • Check the troubleshooting section
  • Review API documentation
  • Submit an issue on GitHub

Acknowledgments

  • yt-dlp: The core download engine
  • Flask: Web framework
  • Gradio: User interface framework
  • Inter Font: Typography
  • Accessibility Guidelines: WCAG compliance

⚠️ Disclaimer: This tool is for educational and personal use only. Please respect content creators' rights and platform terms of service.