System Architecture
This document explains how the Ultimate Media Downloader is designed and how its different parts work together. If you are a computer science student or someone trying to understand the project structure, this guide will walk you through everything step by step.
Overview
The Ultimate Media Downloader is a Python-based command-line application that downloads media content from over 100 different platforms. The application follows a modular architecture where different components handle specific responsibilities. This makes the code easier to maintain, test, and extend.
Design Principles
The project follows these key principles:
- Modularity: Each component does one thing well
- Extensibility: New platforms can be added without changing existing code
- Graceful Degradation: If optional features are not available, the app still works
- User Experience: Beautiful CLI interface with progress indicators
High-Level Architecture
The following diagram shows how the main components interact with each other:
Loading diagram...
Component Breakdown
Entry Point
The application starts from ultimate_downloader.py. This file contains the main class UltimateMediaDownloader which orchestrates everything.
Loading diagram...
Main Components
| Component | File | Purpose |
|---|---|---|
| Main Downloader | ultimate_downloader.py | Core application logic and coordination |
| Generic Downloader | generic_downloader.py | Handles sites with special requirements like SSL bypass |
| CLI Parser | cli_args.py | Processes command-line arguments |
| Logger | logger.py | Custom logging to suppress verbose output |
| YouTube Scorer | youtube_scorer.py | Ranks YouTube search results for accuracy |
| Platform Info | platform_info.py | Displays supported platform information |
| Patch Handlers | patch_handlers.py | Manages runtime patches and overrides for handlers |
Data Flow
When a user provides a URL, here is what happens inside the application:
Loading diagram...
Handler System
The handler system is how the application supports different platforms. Each platform that needs special handling has its own handler class.
Handler Architecture
Loading diagram...
How Handlers Work
- Detection: The main class detects which platform a URL belongs to
- Delegation: If a handler exists for that platform, the request is delegated
- Processing: The handler extracts metadata and determines how to download
- Fallback: If direct download is not possible, handlers search YouTube and download from there
Spotify and Apple Music Flow
These platforms do not allow direct downloading. Here is how the application handles them:
Loading diagram...
Utility Modules
The utils/ directory contains helper modules that provide common functionality.
Module Overview
Loading diagram...
Key Utility Functions
| Module | Function | Description |
|---|---|---|
| utils.py | sanitize_filename() | Removes invalid characters from filenames |
| utils.py | format_bytes() | Converts bytes to human-readable format |
| utils.py | detect_platform() | Identifies platform from URL |
| url_validator.py | is_valid_url() | Checks if URL is properly formatted |
| url_validator.py | check_url_support() | Verifies if URL can be downloaded |
| terminal_image.py | display_image() | Renders an image using sixel if supported |
| ui_components.py | Icons.get() | Returns consistent icons for UI |
| ui_components.py | Messages.success() | Formats success messages |
Configuration Management
The application uses a JSON configuration file to store settings.
Configuration Structure
Loading diagram...
Environment Variables
Some settings can be configured through environment variables:
| Variable | Purpose |
|---|---|
SPOTIFY_CLIENT_ID | Spotify API authentication |
SPOTIFY_CLIENT_SECRET | Spotify API authentication |
APPLE_MUSIC_TOKEN | Apple Music direct download |
APPLE_MUSIC_STOREFRONT | Apple Music region |
Error Handling
The application handles errors gracefully to provide a good user experience.
Error Handling Flow
Loading diagram...
Fallback Strategies
- SSL Issues: The generic downloader creates permissive SSL contexts
- Rate Limiting: Automatic delays between requests
- Anti-bot Protection: Multiple request methods (cloudscraper, curl-cffi, selenium)
- Missing Handlers: Falls back to yt-dlp generic extractor
Summary
The Ultimate Media Downloader is built with a clean, modular architecture that separates concerns and makes the codebase maintainable. The handler system allows easy extension for new platforms, while the utility modules provide reusable functionality across the application.
Understanding this architecture will help you:
- Navigate the codebase effectively
- Add new features or platforms
- Debug issues by tracing the data flow
- Contribute improvements to the project
For more details on specific components, refer to the individual source files and their inline documentation.