---
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](https://huggingface.co/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)
```bash
# 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)
```bash
# 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:

```python
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:**
```json
{
  "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:**
```json
{
  "url": "https://www.youtube.com/watch?v=..."
}
```

**Response:**
```json
{
  "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:**
```json
{
  "url": "https://www.youtube.com/watch?v=...",
  "format_id": "best",
  "download_id": "dl_1234567890"
}
```

#### `GET /api/progress/<download_id>`
Get download progress.

**Response:**
```json
{
  "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:

```bash
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.