CoomerDL - Universal Media Archiver 🎬

Download media from 1000+ websites - Desktop App or Web Application

CoomerDL is a powerful media downloader supporting over 1000 websites. Available as both a desktop application and a modern web application that can be deployed to the cloud.

---

🚀 NEW: Web Application

CoomerDL is now available as a modern web application with cloud deployment!

☁️ One-Click Cloud Deployment

Deploy your own instance to Google Cloud Platform in minutes:

git clone https://github.com/primoscope/CoomerDL.git
cd CoomerDL
./scripts/deploy-gcp.sh

Or click the button above ☝️ to deploy directly from GitHub!

🌐 Web App Features

• ✅ Modern React UI - Responsive design works on desktop, tablet, and mobile
• ✅ Real-Time Updates - WebSocket-powered live progress and logs
• ✅ Cloud Storage - Direct upload to Google Cloud Storage
• ✅ Scalable - Auto-scales based on demand
• ✅ No Installation - Access from any browser
• ✅ All Features - Same powerful downloading capabilities as desktop app

📚 Read the Web App Deployment Guide →

---

✨ Key Features

🌐 Universal Support

• 1000+ Websites Supported - YouTube, Twitter/X, Reddit, TikTok, Instagram, and more
• Specialized High-Speed Scrapers - Optimized for Coomer, Kemono, Erome, Bunkr, SimpCity, jpg5
• Gallery Support - DeviantArt, Pixiv, ArtStation, and 100+ image gallery sites
• Smart URL Detection - Automatically uses the best downloader for each URL

🚀 Powerful Automation

• Batch Downloads - Paste multiple URLs and download them all at once
• Auto-Retry - Failed downloads automatically retry with smart backoff
• Crash Recovery - Resume interrupted downloads after restart
• Duplicate Detection - Automatically skip files you've already downloaded
• Rate Limiting - Respectful download speeds to avoid getting blocked

🎨 User-Friendly Interface

• Modern GUI - Clean, intuitive interface with light and dark themes
• Real-Time Progress - See download speed, progress, and estimated time
• Multi-Language - Available in 6 languages: English, Spanish, French, Japanese, Russian, and Chinese
• Queue Management - Organize, prioritize, and control your downloads
• Download History - Browse and search everything you've downloaded

⚙️ Advanced Configuration

• Proxy Support - Use HTTP/HTTPS/SOCKS proxies
• Bandwidth Limiting - Cap download speeds to avoid overwhelming your connection (NEW!)
• Custom Timeouts - Configure connection and read timeouts (NEW!)
• File Size Filters - Skip files smaller or larger than specified sizes (NEW!)
• Date Range Filters - Download only posts from specific time periods (NEW!)
• File Type Exclusions - Exclude specific file types like WEBM, GIF, or ZIP (NEW!)
• Custom User Agent - Customize your browser identity
• File Filtering - Choose which file types to download
• Format Selection - Pick video quality and audio formats
• Cookie Import - Auto-authenticate using your browser cookies
• FFmpeg Integration - Merge video/audio, convert formats, embed metadata

---

🎯 Supported Sites

CoomerDL supports 1000+ websites through three powerful engines:

🏎️ Native Scrapers (Optimized for Speed)

High-performance, purpose-built downloaders for these popular sites:

• coomer.su - Patreon, OnlyFans, and other content creators
• kemono.su - Similar to Coomer with additional platforms
• erome.com - Image and video albums
• bunkr-albums.io - File hosting and albums
• simpcity.su - Forum media downloads
• jpg5.su - Image hosting

🎬 Video Sites (via yt-dlp)

Download from 1000+ video platforms including:

• Streaming: YouTube, Vimeo, Dailymotion, Twitch
• Social Media: Twitter/X, Reddit, TikTok, Instagram, Facebook
• And many more: View full list

🖼️ Image Galleries (via gallery-dl)

Support for 100+ image gallery sites including:

• Art Platforms: DeviantArt, Pixiv, ArtStation
• Social: Tumblr, Pinterest, Instagram
• Image Boards: Various supported boards
• And more: View full list

---

📥 Getting Started

Choose Your Version

CoomerDL is available in two versions:

Feature	Desktop App	Web Application
Installation	Download & run .exe	One-click cloud deploy
Interface	Native desktop GUI	Modern web browser
Platform	Windows/Mac/Linux	Any device with browser
Storage	Local filesystem	Cloud storage (GCS)
Deployment	Run locally	Cloud-hosted (scalable)
Updates	Manual download	Auto-deploy
Best For	Personal use, privacy	Remote access, sharing

Desktop App - Quick Start

Method 1: Easy Installer (Recommended) ⭐

The easiest way to get started with CoomerDL:

# Download the repository
git clone https://github.com/primoscope/CoomerDL.git
cd CoomerDL

# Run the universal installer
python install.py

The installer will:

• ✅ Check Python version (3.8+ required)
• ✅ Check for FFmpeg (optional)
• ✅ Create a virtual environment
• ✅ Install all dependencies
• ✅ Test the installation
• ✅ Create a launcher script

Then just run:

• Windows: Double-click start_coomerdl.bat
• Mac/Linux: Run ./start_coomerdl.sh

Method 2: Pre-built Executable (Windows Only)

1. Download the latest CoomerDL-Windows.zip from Releases
2. Extract the ZIP file to a folder
3. Double-click CoomerDL.exe to launch - that's it!

Note: Windows may show a SmartScreen warning for unsigned executables. Click "More info" → "Run anyway" to proceed.

Method 3: Manual Installation

If you prefer to install manually:

1. Install Python 3.8+ (Download Python)

2. Install FFmpeg (Optional, for video merging):

   • Windows: winget install ffmpeg
   • macOS: brew install ffmpeg
   • Linux: sudo apt install ffmpeg

3. Clone and install:

   git clone https://github.com/primoscope/CoomerDL.git
   cd CoomerDL
   
   # Create virtual environment (recommended)
   python -m venv venv
   
   # Activate it
   source venv/bin/activate  # Mac/Linux
   venv\Scripts\activate      # Windows
   
   # Install dependencies
   pip install -r requirements.txt
   
   # Run CoomerDL
   python main.py

4. Validate installation:

   python validate_install.py

💡 Linux users: You may need to install tkinter: sudo apt install python3-tk

Method 4: Install as Python Package

For developers or users who want CoomerDL as a Python package:

git clone https://github.com/primoscope/CoomerDL.git
cd CoomerDL
pip install -e .

# Then run from anywhere
coomerdl "https://example.com/video"

Headless / Server Installation (Linux)

If you are running on a server without a display (headless), you can run the backend API only.

1. Install system dependencies (skip python3-tk if you don't need the GUI):

   sudo apt update
   sudo apt install ffmpeg python3-pip python3-venv

2. Clone and Setup:

   git clone https://github.com/primoscope/CoomerDL.git
   cd CoomerDL
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

   (Note: Some GUI-related packages might fail to build or warn on headless systems. This is usually fine for backend-only usage.)

3. Run Backend: To run only the backend API (without attempting to start the GUI):

   export HEADLESS=true
   python main.py

   The API will be available at http://localhost:8080.

CLI Usage (Command Line Interface)

You can use CoomerDL purely from the command line for automation or scripts.

Basic Usage:

python main.py "https://example.com/video"

Batch Download from File:

python main.py --batch-file urls.txt

Advanced Options:

python main.py "https://example.com/video" \
  --output "my_downloads" \
  --no-images \
  --min-size 10M \
  --date-from 2023-01-01 \
  --max-retries 5

All CLI Options:

Option	Description
urls	List of URLs to download
--batch-file, -i	File containing URLs (one per line)
--output, -o	Output directory (default: downloads)
--no-images	Skip downloading images
--no-videos	Skip downloading videos
--min-size	Minimum file size (e.g. 5M, 100K)
--date-from	Download only after date (YYYY-MM-DD)
--proxy	Proxy URL (http://user:pass@host:port)
--headless	Force backend server mode

---

🎮 How to Use

1. Launch CoomerDL - The application window will open
2. Paste URLs - Enter one or more URLs (one per line for batch downloads)
3. Choose Options - Select what to download (images, videos, etc.)
4. Click Download - Sit back and watch the magic happen!

Pro Tips

• 📝 Batch Downloads: Paste multiple URLs (one per line) to download them all at once
• 🌐 Network Settings: Go to Settings → Network to configure proxy, bandwidth limits, and timeouts
• 🔍 Advanced Filters: Use Settings → Filters to set file size limits, date ranges, and exclude specific file types
• 🍪 Cookie Import: Settings → Universal → Import cookies from your browser for authenticated downloads
• 📋 Queue Management: Click the Queue button to manage, reorder, and control your downloads
• ⚙️ Custom Filters: Use Settings → Downloads to configure file type filters and download options

---

🌍 Language Support & Community

Supported Languages

CoomerDL is available in 6 languages:
🇺🇸 English | 🇪🇸 Español | 🇫🇷 Français | 🇯🇵 日本語 | 🇨🇳 中文 | 🇷🇺 Русский

Command-Line Alternatives

Prefer CLI tools? Check out other similar command-line tools for specific sites.

---

---

⚠️ Troubleshooting

Common Issues

ModuleNotFoundError: No module named 'tkinter'

Linux users need to install tkinter separately:

sudo apt install python3-tk      # Ubuntu/Debian
sudo dnf install python3-tkinter # Fedora
sudo pacman -S tk               # Arch Linux

Windows/macOS: Reinstall Python from python.org with tkinter enabled.

Missing Python packages

Update or reinstall dependencies:

pip install -r requirements.txt --upgrade
# or force reinstall
pip install -r requirements.txt --force-reinstall

FFmpeg not found

Install FFmpeg for video/audio merging:

• Windows: winget install ffmpeg
• macOS: brew install ffmpeg
• Linux: sudo apt install ffmpeg

Verify: ffmpeg -version

Note: CoomerDL works without FFmpeg, but video merging won't be available.

Downloads fail with 403/429 errors

• 403 Forbidden: Site requires authentication. Use Settings → Universal → Import browser cookies.
• 429 Too Many Requests: Rate limited. Lower concurrent downloads in Settings → Network.

YouTube or other site downloads fail

If you get "invalid URL" or "not supported" errors:

• Verify yt-dlp is installed: pip install -U yt-dlp
• Check network connectivity to the target site
• For video+audio merging, install FFmpeg (see installation section above)
• Try updating yt-dlp: pip install --upgrade yt-dlp
• Check the URL format - some sites require specific URL patterns

Testing yt-dlp directly:

# Test if yt-dlp can handle the URL
yt-dlp --list-formats YOUR_URL

# Download with yt-dlp directly
yt-dlp -f best YOUR_URL

Note: CoomerDL uses yt-dlp which supports 1000+ sites including YouTube, Twitter, TikTok, etc.

Application won't start or crashes

Check for common issues:

• Python version: Requires Python 3.8 or higher - check with python --version
• Missing dependencies: Run pip install -r requirements.txt to reinstall all packages
• Tkinter missing (Linux): Install with sudo apt install python3-tk
• Corrupted settings: Delete the settings file in the app data directory and restart

High memory usage or database locked

• Lower concurrent downloads in settings
• Clear completed downloads from queue
• Close other CoomerDL instances (only one should run)
• Restart the application periodically

Still Need Help?

1. Check existing issues
2. Create a new issue with:
   • Python version (python --version)
   • OS and version
   • Full error message
   • Steps to reproduce

---

---

👨‍💻 For Developers

Contributing

Contributions are welcome! This project is optimized for both human developers and AI coding agents.

Documentation for Developers:

• DEVELOPMENT_ROADMAP.md - Technical roadmap with task breakdowns
• TASKS.md - Detailed task definitions with acceptance criteria
• SPECIFICATIONS.md - Code specifications for new features
• tests/CONTRACTS.md - System behavior contracts

Running Tests

pytest tests/         # Run all 241 tests
pytest tests/ -v      # Verbose output
python main.py        # Manual testing

Tech Stack

• UI: CustomTkinter (modern tkinter framework)
• Backend: Python 3.8+ with threading
• Engines: yt-dlp, gallery-dl, custom scrapers
• Database: SQLite for history and caching
• HTTP: requests with connection pooling

Architecture Highlights

• Multi-Engine System: Native scrapers, yt-dlp adapter, gallery-dl adapter with smart routing
• Event-Driven: Backend emits events, UI subscribes (no tight coupling)
• Job Queue: Persistent queue with crash recovery and status tracking
• Rate Limiting: Per-domain concurrency caps and request throttling
• Thread-Safe: Event-based cancellation, locked database access

Quick Start for Development

git clone https://github.com/primoscope/CoomerDL.git
cd CoomerDL
pip install -r requirements.txt
pip install pytest  # For running tests
python main.py      # Run the application

Building Executables

Want to build your own executable? See BUILDING.md for detailed instructions.

Quick build:

pip install pyinstaller
python build.py

The executable will be in the dist/ folder.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⭐ Support the Project

If you find CoomerDL useful, please consider:

• ⭐ Star this repository on GitHub
• 🐛 Report bugs and suggest features
• 🤝 Contribute to the project

Your support helps maintain and improve CoomerDL!

---

Made with ❤️ by the CoomerDL community