❯ Media-Downloader-V3

Built with the tools and technologies:

---

Table of Contents

• Table of Contents
• Overview
• Features
• Project Structure
  • Project Index
• Getting Started
  • Prerequisites
  • Installation
  • Usage
  • Testing
• Roadmap
• Contributing
• License
• Acknowledgments

---

Overview

Media-Downloader-V3 is a powerful, modular Telegram bot designed to download media from a vast array of websites. Built with Python and Telethon, it leverages an asynchronous, event-driven architecture to handle multiple user requests efficiently. It features a robust module system, allowing for easy extension to support new sites and features, and includes administrative tools for statistics, system information, and remote updates.

---

Features

	Component	Details
⚙️	Architecture	Event‑driven, async architecture powered by asyncio and Telethon. Central Bot class orchestrates command handlers, middleware, and state persistence. Modular service layer: services/spotify.py, services/shazam.py, services/ytdl.py, etc. Database layer uses pymongo for user sessions and download metadata.
🔩	Code Quality	PEP‑8 compliant, linted with flake8 and formatted by black. Type hints throughout the codebase; mypy enabled in CI. Explicit error handling with custom exception classes. Logging via logging module, configurable log levels.
📄	Documentation	Comprehensive README.md with quick‑start, configuration, and command reference. Docstrings in Sphinx format; API docs generated with pydocstyle. Environment variable guide in .env.example.

---

Project Structure

└── /
    ├── akeno.py
    ├── config.py
    ├── Modules
    │   ├── antispam.py
    │   ├── cdn.py
    │   ├── database.py
    │   ├── deviantart.py
    │   ├── download.py
    │   ├── errors.py
    │   ├── force_sub.py
    │   ├── group_add.py
    │   ├── hanime.py
    │   ├── help.py
    │   ├── instagram.py
    │   ├── listen.py
    │   ├── logs.py
    │   ├── nhentai.py
    │   ├── PerfectGirls.py
    │   ├── pinterest.py
    │   ├── pornhub.py
    │   ├── reddit.py
    │   ├── restart.py
    │   ├── rule34.py
    │   ├── rule34video.py
    │   ├── Shazam.py
    │   ├── socigames.py
    │   ├── song.py
    │   ├── start.py
    │   ├── stats.py
    │   ├── supported_links.py
    │   ├── System_Info.py
    │   ├── threads.py
    │   ├── tiktok.py
    │   ├── twitter.py
    │   ├── update.py
    │   ├── xnxx.py
    │   ├── Xvideos.py
    │   ├── youtube.py
    │   └── youtubev2.py
    └── requirements.txt

Project Index

/

__root__

⦿ __root__

File Name	Summary
akeno.py	- Launches the Media Downloader Bot, initializing the Telegram client with credentials, loading modular features from the Modules directory, ensuring download folders exist, handling restart notifications, and sending a startup message to a log channel - It orchestrates startup, logging, and graceful shutdown while coordinating module initialization and restart state persistence for continuous operation.
config.py	- config.py loads and validates essential configuration parameters for the bot, including API credentials, database connection, logging identifiers, channel and owner IDs, Spotify authentication, and optional proxy settings - By pulling values from environment variables and enforcing presence of mandatory fields, it guarantees the application starts with a complete and secure configuration, preventing runtime failures due to missing data.
requirements.txt	- Lists all the required Python packages and dependencies for the project to run correctly.

Modules

⦿ Modules

File Name	Summary
antispam.py	- The antispam.py module tracks user download activity, enforcing a cooldown period to prevent rapid repeated downloads - Maintains per‑user status flags and timestamps, offering functions to query current download state, set status, check for spam based on elapsed time, and update the last download time - This module supports the bot’s anti‑spam logic by ensuring users cannot trigger multiple downloads in quick succession.
cdn.py	- The cdn.py module downloads media from CDN links, verifies URLs, creates organized folders, and stores files locally - For images exceeding Telegram’s 10 MB limit, it resizes or compresses them while preserving quality - After successful download, it uploads the media through the bot, adds a caption, updates usage statistics, enforces subscription and anti‑spam rules, logs any failures, and removes temporary files.
database.py	- The database.py module establishes MongoDB connectivity for MediaMasterBot, exposing collections for users, groups, and statistics - Provides helper functions to register new users and groups while preventing duplicates, and to retrieve user records - Logs significant events such as bot initiation by a user or addition to a new group, enabling consistent data persistence across the bot’s operations.
deviantart.py	- The deviantart.py module downloads media from DeviantArt links, retrieves them through a proxy‑enabled extraction service, stores files locally, uploads them to Telegram chats, enforces channel subscription, throttles spam, tracks user activity, logs upload statistics, and cleans up temporary files, integrating with the bot’s anti‑spam, force‑subscribe, and database modules - It validates user permissions, handles errors gracefully, records upload metrics, and removes temporary files after transfer, ensuring efficient resource usage within the bot’s modular architecture.
download.py	- The download.py module creates and verifies a comprehensive Downloads folder hierarchy for diverse media sources, automatically generating any missing directories and logging the process - This guarantees that subsequent download operations have a ready, organized storage structure across platforms such as Instagram, Pinterest, Reddit, and more, supporting the projects modular download functionality for users.
errors.py	- The errors.py module provides centralized error handling for the bot, capturing exceptions and logging them for debugging while notifying the user.
force_sub.py	- The force_sub.py module enforces channel membership before allowing media downloads, checking participant status, prompting users to join, and providing retry functionality via inline buttons - It retrieves the target channel entity, constructs a message with a link button and a retry callback, and handles callback queries to confirm membership or alert the user - This module integrates with the bot’s event loop to gate content access.
group_add.py	- The group_add.py module adds a group to the database upon the bot’s first join, sends a welcome message explaining media download features, and temporarily flags the chat to avoid duplicate welcomes - This module hooks into Telethon’s ChatAction events, coordinating with the database layer to track active groups and provide a smooth onboarding experience for users.
hanime.py	- The hanime.py module manages HAnime video requests by validating user status, retrieving media data from locoloader, downloading video and thumbnail, uploading to Telegram, recording usage statistics, and enforcing anti‑spam and subscription rules while handling errors and cleaning temporary files - It creates per‑user download
help.py	- The help.py module registers a /help command that, when triggered, sends a concise overview of all bot commands and their purposes, guiding users through available features such as song and video downloads, shazam identification, owner‑only utilities, and platform listings - This module integrates with the Telethon event system, ensuring the help message is accessible from any chat where the bot is active.
instagram.py	- The instagram.py module downloads Instagram media, uploads it to Telegram, manages user download state, enforces anti‑spam limits, logs progress, records upload statistics, and handles errors gracefully - It integrates with the bot
listen.py	- The listen.py module monitors incoming messages for media links across platforms such as YouTube, Twitter, Reddit, and adult sites, verifies user subscription status, and triggers corresponding download and upload routines to retrieve and forward media content - By registering event handlers for each platform’s URL patterns, it centralizes link processing and enforces access controls before media handling.
logs.py	- The logs.py module provides a /logs command for the bot owner, reading recent entries from the Media‑Downloader.log, uploading them to SpaceB.in, and sending the log file back to the chat with a public link - This module integrates logging utilities into the bot’s command framework, enabling quick diagnostics and remote log access for maintenance.
nhentai.py	- The nhentai.py module downloads nhentai content by extracting URLs through a proxy, converts images when necessary, uploads them to Telegram chats, and records usage statistics - It enforces channel subscription, prevents spam, tracks user download status, and cleans up temporary files, integrating with the bot’s anti‑spam, database, and upload helper modules, ensuring smooth user experience across private and group chats.
PerfectGirls.py	- Downloads PerfectGirls videos through a proxy‑enabled locoloader service, sanitizes filenames, streams media with yt_dlp, and uploads the result to Telegram chats while enforcing per‑user download limits and anti‑spam checks - It records upload metrics, handles errors gracefully, and cleans temporary files, fitting into the bot’s modular architecture for media retrieval and distribution.
pinterest.py	- The pinterest.py module downloads Pinterest media, validates user access, and uploads content to chat, while enforcing anti‑spam rules, handling errors, logging activity, and recording usage statistics - It orchestrates gallery‑dl calls, manages temporary storage, cleans up after uploads, and integrates with the bot’s user database and subscription checks,
pornhub.py	- The pornhub.py module is for downloading videos from Pornhub, including anti-spam and user-tracking features.
reddit.py	- The reddit.py module downloads Reddit media, converts streaming formats, and uploads the content to Telegram channels - It verifies user subscription status, enforces anti‑spam limits, and records upload statistics - The module interacts with a proxy API to fetch media URLs, handles image and video extraction, supports m3u8 conversion via yt‑dl, and cleans up temporary files after successful transfer.
restart.py	- The restart.py module enables the bot owner to trigger a graceful restart via the /restart command, records the chat and message identifiers to a JSON file for post‑restart updates, and re‑executes the Python interpreter to reload the bot - This module integrates with the Telethon event system, ensuring controlled restarts within the overall bot architecture.
rule34.py	- The rule34.py module handles user requests to fetch and deliver Rule34 media, integrating with Telethon event handling, enforcing
rule34video.py	- The rule34video.py module downloads and uploads Rule34 videos on user request, enforcing anti‑spam limits, tracking user activity, and recording upload statistics - It leverages yt_dlp for extraction, FastTelethonhelper for efficient uploads, and Telethon for messaging - Errors are handled gracefully, temporary files are cleaned up after transfer, and progress is logged while updating last download timestamps to ensure only one download per user at a time.
Shazam.py	- The Shazam.py module handles user‑initiated song recognition by processing replied audio or video files, leveraging Shazam for identification, searching YouTube for the track, downloading the best audio, and uploading it back to the chat with metadata - It integrates anti‑spam, force‑subscription enforcement, user state tracking, and upload statistics, ensuring smooth operation within the bot’s modular architecture.
socigames.py	- The socigames.py module downloads Socigames video from a supplied URL, ensuring the requester is a subscribed member and not spamming - It selects the highest‑resolution CDN link, streams the file to a temporary directory, uploads the media to the chat via Telethon, logs the upload size for analytics, and removes temporary files while updating user download status.
song.py	- The song.py module validates the request, downloads the media from Spotify or YouTube, uploads it to a CDN, and logs the results, orchestrating the end-to-end flow from request to delivery.
start.py	- The start.py module initiates user onboarding by registering a /start command that records new users, delivers a welcome message with media download instructions, and optionally sends a branded image - It ensures smooth first interaction, logs user details, and provides a fallback text response if image delivery fails, integrating with the bot’s command handling and database modules.
stats.py	- The stats.py module provides owner‑only statistics interface, tracking upload counts and sizes across modules, computing uptime, and presenting paginated module details via inline buttons - Records upload metrics in database, aggregates totals, and displays user count - Integrates with Telethon event handlers to respond to /stats and callback queries, enabling real‑time monitoring of bot activity.
supported_links.py	- The supported_links.py module displays a list of all supported websites and services from which the bot can download media.
System_Info.py	- The System_Info.py module enables a /sysinfo command that gathers system information using neofetch, parses the output, formats it into a stylized
threads.py	- The threads.py module downloads media from Threads links, verifies user eligibility, enforces anti‑spam limits, and streams each file to the chat via the bot - It logs progress, records upload statistics, and cleans temporary files, ensuring smooth interaction across private and group contexts while maintaining database state and error resilience, and supports graceful recovery from network failures.
tiktok.py	- The tiktok.py module downloads TikTok media from user‑supplied links, streams the content through an external extraction service, and uploads the resulting files to the chat - It enforces per‑user download limits and anti‑spam checks, logs progress, records upload statistics, and handles errors gracefully, ensuring an efficient and smooth user experience within the bot’s media‑handling architecture.
twitter.py	- The twitter.py module downloads media from Twitter links, verifies that the requesting user is subscribed to the required channel, and applies anti‑spam limits to prevent abuse - After successful download, the media is uploaded to the chat with a bot‑generated caption, while usage statistics are recorded - Temporary files are removed
update.py	- The update.py module enables remote self‑update capabilities for the bot through a privileged command that pulls the latest repository changes, installs any new dependencies found in requirements.txt, and restarts the process to apply updates, ensuring continuous deployment within the overall architecture that integrates Telethon event handling with secure owner verification and automated reboot.
xnxx.py	- The xnxx.py module downloads Xnxx videos by extracting metadata through locoloader, streams the chosen 720p file, uploads
Xvideos.py	- The Xvideos.py module downloads Xvideos links by extracting metadata through a proxy‑enabled API, retrieves a 720p video stream, and uploads it to Telegram using FastTelethonhelper - It enforces anti‑spam limits, tracks user download status, logs progress, records upload statistics, and cleans temporary files - Errors are routed to a central handler, ensuring graceful recovery within the bot’s modular architecture.
youtube.py	- The youtube.py module downloads YouTube videos requested by users, verifies channel membership, throttles repeated requests, and streams the media to the chat - It handles errors gracefully, informs users of subscription requirements
youtubev2.py	- Orchestrates the end-to-end flow for YouTube downloads by handling Telethon events, enforcing anti-spam and subscription rules, and managing the entire download/upload pipeline. - It connects the bot’s command interface with all necessary backend modules for media processing and user management.

---

Getting Started

Prerequisites

This project requires the following dependencies:

• Programming Language: Python
• Package Manager: Pip

Installation

Build from the source and intsall dependencies:

1. Clone the repository:

   ❯ git clone https://github.com/SyntaxAdi/Media-Downloader-Bot

2. Navigate to the project directory:

   ❯ cd Media-Downloader-Bot

3. Install the dependencies:

   ❯ pip install -r requirements.txt

Usage

Run the project with:

Using python3:

python3 akeno.py

Using reloady for auto-reloading:

reloady akeno.py

Testing

This project is tested in a live production environment on Northflank and through self-based testing to ensure stability and performance.

---

Roadmap

• Core: Initial bot structure and core modules.
• Feature: Add support for more media websites.
• Improvement: Refactor and improve error handling.
• Documentation: Add detailed documentation for each module.

---

Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🤖 Use the Bot: Try out the bot and explore its features.
• 💡 Suggest Features & Report Bugs: Share new ideas or let the owner know about any issues.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your LOCAL account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/SyntaxAdi/Media-Downloader-Bot

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'

6. Push to LOCAL: Push the changes to your forked repository.

   git push origin new-feature-x

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

---

License

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

---

Acknowledgments

• Thanks to the creators of readme-ai for the template.

---