CosmicDL 3.0.0
CosmicDL - Professional Multi-Platform Video Downloader
License: MIT
Requires Python: >=3.10
Keywords: downloader, video, cosmicdl, hls, m3u8, cli, tiktok, instagram

﻿# 🎬 CosmicDL

<div align="center">

![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)
![Python](https://img.shields.io/badge/python-3.10+-brightgreen.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/CosmicDL?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/CosmicDL)

**Professional Multi-Platform Video Downloader with Style!** ✨

*A powerful, feature-rich downloader with a beautiful CLI, comprehensive Python API, and a Modern GUI*


[Installation](#-installation) • [Features](#-features) • [Usage CLI](#-usage-cli) • [Usage GUI](#-usage-gui-v300)

</div>

---

## 📦 Installation

### With [CosmicDLSetup.exe](https://gitlab.com/GloryMajor/CosmicDL/releases) file

```bash
just download and install it, no actions needed
```

### From PyPI ✅ 

```bash
pip install CosmicDL
```

### Quick Install (Linux/macOS)

```bash
chmod +x install.sh
./install.sh
```

### Quick Install (Windows)

```batch
install.bat
```


## 🌐 Supported Sites

> See the full list with details: **[Supported Sites](docs/SupportedSites.md)**

---

## ✨ Features

- **Multi-Site Support** - Download from 7+ major video sites
- **Automatic Site Detection** - Just paste any supported URL
- **Beautiful GUI** - Modern, Glassmorphism design with React & Python
- **Advanced Queue** - Priority-based download queue with Pause/Resume
- **Fast Downloads** - Multi-threaded + aria2c support (up to 16 connections)
- **Quality Selection** - Choose from available qualities (up to 4K!)
- **Batch Downloads** - Download multiple videos concurrently
- **Playlist/Channel Support** - Download entire channels
- **Advanced Search** - Integrated search for supported sites
- **Favorites & History** - Manage your favorite videos and view download history
- **Proxy Manager** - Rotating proxy support (HTTP/HTTPS/SOCKS)
- **Rate Limiting** - Smart limits to prevent temporary IP bans
- **System Integration** - System Tray icon and Desktop Notifications (Windows)
- **Python API** - Use as a library for automation

### NEW in v3.0.0 ✨
- **Complete Rebranding** - New name, new identity
- **Queue Management** - Reorder, prioritize, and schedule downloads
- **Proxy Rotation** - Automatically switch proxies on failure
- **Search & Favorites** - Built-in search engine and folders for favorites
- **System Tray** - Minimize to tray background running
- **Drag & Drop** - Drag URLs directly into the app
- **Theme Support** - Light/Dark mode toggle


---

## 🚀 Usage (GUI) v3.0.0+

Download the [CosmicDLSetup.exe](https://github.com/GloryMajor/CosmicDL/releases) file and install it.

**Key Capabilities:**
1. **Dashboard**: View real-time stats and download speeds.
2. **Search**: Search specific sites or all sites at once.
3. **Queue**: Manage your downloads, change priorities, or pause the queue.
4. **Extras**: Use the Batch Downloader for multiple links or configure Proxies.


## 🚀 Usage (CLI)

### Interactive Mode (Recommended for beginners)

Simply run without arguments:

```bash
CosmicDL
```

You'll get a beautiful interactive menu:

```
╔═════════════════════════════════════════════════════════════════╗
║  ██████╗ ██████╗ ███████╗███╗   ███╗██╗ ██████╗██████╗ ██╗      ║
║  ██╔════╝██╔═══██╗██╔════╝████╗ ████║██║██╔════╝██╔══██╗██║     ║
║  ██║     ██║   ██║███████╗██╔████╔██║██║██║     ██║  ██║██║     ║
║  ██║     ██║   ██║╚════██║██║╚██╔╝██║██║██║     ██║  ██║██║     ║
║  ╚██████╗╚██████╔╝███████║██║ ╚═╝ ██║██║╚██████╗██████╔╝███████╗║
║   ╚═════╝ ╚═════╝ ╚══════╝╚═╝     ╚═╝╚═╝ ╚═════╝╚═════╝ ╚══════╝║
║       Professional Multi-Platform Video Downloader              ║
╚═════════════════════════════════════════════════════════════════╝
                    version 3.0.0 • CosmicDL
```


### Command Line Mode

```bash
# Download from any supported site
CosmicDL "VIDEO_URL"

# Specify quality
CosmicDL "URL" -q 720

# Custom output
CosmicDL "URL" -o my_video.mp4

# Use proxy
CosmicDL "URL" -p http://127.0.0.1:1080
```

---

## 📚 Documentation

Complete documentation available in [`docs/`](docs/):

- **[Quick Start Guide](docs/QuickStart.md)** - Get started in 5 minutes
- **[Multi-Site Guide](docs/MultiSite.md)** - Complete multi-site guide
- **[API Reference](docs/API.md)** - Function documentation
- **[Examples](docs/Examples.md)** - Code examples
- **[Advanced Usage](docs/Advanced.md)** - Advanced topics

---

## 🔧 Requirements

### Required
- Python 3.10 or higher
- Internet connection

### Optional (Recommended)
- **FFmpeg** - For automatic MP4 conversion
  - **Ubuntu/Debian**: `sudo apt install ffmpeg`
  - **macOS**: `brew install ffmpeg`
  - **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)

---

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs
- Suggest new features
- Submit pull requests

---

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## ⚖️ Disclaimer

This tool is for educational purposes only. Please respect copyright laws and the terms of service of the websites you download from. The developers are not responsible for any misuse of this software.

---

<div align="center">

**Made with ❤️ by CosmicDL Team**

If this tool helped you, consider giving it a ⭐ on GitHub!

[GitHub](https://github.com/GloryMajor/CosmicDL) • [PyPI](https://pypi.org/project/CosmicDL/) • [Documentation](docs/)

</div>