MediaDownload

🤖 Media Download Bot

A powerful Discord bot for downloading and organizing media files from channels with smart categorization and Top.gg vote verification.

✨ Features

• 🎯 Interactive Download Menu - User-friendly button-based interface
• 🧠 Smart File Organization - Automatic categorization by content type
• 🗳️ Top.gg Vote System - Encourages community support
• 📊 Progress Tracking - Real-time download progress with visual indicators
• 🔄 Resource Monitoring - Automatic pausing when system resources are low
• 📁 Multiple Download Options - By date, type, or recent messages
• ☁️ External Hosting - Large files automatically uploaded to Catbox
• 🎨 Beautiful Embeds - Professional Discord embeds with progress bars

🚀 Quick Start

Prerequisites

• Python 3.8+
• Discord Bot Token
• Top.gg API Token (optional)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/media-download-bot.git
   cd media-download-bot
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure environment variables

   cp env.example .env
   # Edit .env with your tokens
   

4. Run the bot

   python bot.py
   

⚙️ Configuration

Environment Variables

Variable	Description	Required
DISCORD_TOKEN	Discord Bot Token	✅ Yes
TOP_GG_TOKEN	Top.gg API Token	❌ No
LOGS_CHANNEL_ID	Logs Channel ID	❌ No
WEBHOOK_URL	Webhook URL	❌ No
GOFILE_TOKEN	GoFile Token	❌ No

Intents & Permissions

• Works without Messages Intent. The bot scans channel history via API and extracts media from attachments and embeds.
• Optional: set ENABLE_MESSAGE_CONTENT=true if you want to parse plain-text links from message content (requires enabling Message Content Intent in the Discord Developer Portal).
• Ensure the bot has channel permissions: View Channel, Read Message History, Attach Files, Embed Links.

Getting Your Tokens

Discord Bot Token

1. Go to Discord Developer Portal
2. Create a new application
3. Go to “Bot” section
4. Copy the token

Top.gg API Token

1. Go to Top.gg
2. Click “Edit Bot”
3. Go to “Webhooks” section
4. Copy your Authorization token

🎮 Usage

Commands

• /download - Open interactive download menu

Download Options

• 📥 Download All - Download all media from the channel
• 📅 By Date - Download media from specific date ranges
• 🎨 By Type - Download only images or videos
• 🔄 Recent - Download from last X messages

Vote System

Users must vote on Top.gg to access download features:

• Vote is valid for 12 hours
• Automatic verification after voting
• Seamless download experience

🏗️ Project Structure

media-download-bot/
├── bot.py                 # Main bot file
├── config.py              # Configuration settings
├── cogs/                  # Bot commands
│   ├── download.py        # Download functionality
│   ├── help.py           # Help command
│   └── stats.py          # Statistics
├── utils/                 # Utility modules
│   ├── interactive_menu.py # Interactive menus
│   ├── media_extractor.py  # Attachment+embed media extraction (no message content needed)
│   ├── topgg_checker.py   # Vote verification
│   ├── smart_classifier.py # File organization
│   └── catbox.py         # External hosting
├── requirements.txt       # Dependencies
├── env.example           # Environment template
└── README.md             # This file

🔧 Development

Setting up Development Environment

1. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

2. Install development dependencies

   pip install -r requirements.txt
   

3. Configure local environment

   cp env.example .env
   # Add your tokens to .env
   

Testing

# Check environment variables
python check_env.py

# Test Top.gg API connection
python test_topgg.py

📚 Documentation

• Environment Setup Guide - Complete environment configuration
• GitHub Setup Guide - Quick GitHub Secrets setup
• Top.gg Integration - Vote system documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🆘 Support

If you encounter any issues:

1. Check the documentation
2. Verify your environment variables
3. Check the bot logs
4. Open an issue on GitHub

🙏 Acknowledgments

• Discord.py - Discord API wrapper
• Top.gg - Bot listing and voting platform
• Catbox - File hosting service

---

Made with ❤️ for the Discord community

This site is open source. Improve this page.