- Overview
- Key Features
- Screenshots
- Installation
- Usage Guide
- Architecture
- Project Structure
- Concurrent Downloads
- Queue Management
- Troubleshooting
- Building from Source
- Roadmap
- Contributing
- Credits
- License
Avrix is a feature-rich, cross-platform desktop application designed for seamless YouTube content downloads. Built with modern Python technologies and following SOLID principles, it offers a professional-grade user experience with a sleek, themeable interface.
| Feature | Avrix | Others |
|---|---|---|
| ๐จ Modern UI | โ Dark/Light themes | โ Basic interfaces |
| โก Concurrent Downloads | โ Up to 10 simultaneous | โ Single at a time |
| ๐ Queue System | โ Batch processing | โ Limited support |
| ๐ฏ Quality Options | โ Up to 4K | |
| ๐พ Format Support | โ MP4, MP3, WebM | |
| ๐ Live Updates | โ Real-time progress | โ Basic indicators |
| ๐จ Thumbnails | โ Download & embed | โ Not available |
| ๐ Subtitles | โ Multiple languages | โ Limited support |
|
|
|
|
Professional dark mode with Avrix branding
Real-time progress tracking with speed and ETA indicators
Batch processing with intelligent queue system
Note: Screenshots showcase the modern UI with embedded thumbnails, progress tracking, and queue management.
๐ฏ One-Click Installation - No Python Required!
-
Download the latest release:
๐ฆ Avrix_v1.0_Setup.zip -
Extract and run the installer:
Avrix_Installer/ โโโ Avrix.exe โ Double-click to run (portable) โโโ Install_Avrix.bat โ Or run installer for system integration -
First-time setup:
- Avrix will check for FFmpeg
- If needed, follow the automatic download prompt
- That's it! Start downloading ๐
System Requirements:
- Windows 10 or later (64-bit)
- ~100 MB free disk space
- Internet connection
|
๐ Python Python 3.8+ |
๐ฌ FFmpeg Required for processing |
๐ฆ Git For cloning |
# 1. Clone the repository
git clone https://github.com/yassine-krichen/avrix-downloader.git
cd avrix-downloader
# 2. Create virtual environment (recommended)
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run the application
python main.py๐ช Windows
Option 1: Automatic (Recommended)
python setup_ffmpeg.pyOption 2: Manual
- Download from ffmpeg.org
- Extract and add to PATH
- Restart terminal
Option 3: Chocolatey
choco install ffmpeg๐ macOS
Homebrew (Recommended)
brew install ffmpegMacPorts
sudo port install ffmpeg๐ง Linux
Ubuntu/Debian
sudo apt update
sudo apt install ffmpegFedora
sudo dnf install ffmpegArch Linux
sudo pacman -S ffmpeg-
Launch Avrix
# From source python main.py # Or run the executable Avrix.exe
-
Enter YouTube URL
- Paste any YouTube video or playlist URL
- Auto-detection identifies single videos vs playlists
-
Configure Download
- Format: MP4 (Video) or MP3 (Audio)
- Quality: 4K, 1080p, 720p, 480p, 360p, or Best
- Options: Subtitles, Thumbnails
-
Choose Destination
- Default:
Downloads/YoutubeDownloader - Click "Browse" to change location
- Default:
-
Start Downloading
- Click "Download" for immediate start
- Or "Add to Queue" for batch processing
1. Paste URL โ 2. Select Quality โ 3. Click Download โ 4. Done!
1. Paste Playlist URL
2. App detects all videos
3. Choose download method:
- Download Now (immediate)
- Add to Queue (batch)
4. Track progress per video + total
1. Settings โ Max Concurrent Downloads (1-10)
2. Add multiple items to queue
3. Watch them download simultaneously
4. Progress tracked for each item
1. Select MP3 format
2. Choose quality (higher = better audio)
3. Automatic conversion with FFmpeg
4. Output: Clean .mp3 files
Avrix is built with clean architecture principles and SOLID design patterns:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ User Interface Layer โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Main Window โ โ Progress/Queue Widgets โ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Business Logic Layer โ
โ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Facade Pattern โ โ Download Manager โ โ
โ โ (Simplified โ โ Queue Manager โ โ
โ โ Interface) โ โ Concurrent Manager โ โ
โ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Core Services Layer โ
โ โโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ yt-dlp โ โ FFmpeg Integration โ โ
โ โ Wrapper โ โ Format Builder โ โ
โ โโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
| Pattern | Purpose | Implementation |
|---|---|---|
| Facade | Simplified API | DownloaderFacade class |
| Observer | Event handling | Qt Signals/Slots |
| Strategy | Format selection | FormatBuilder |
| Factory | Object creation | Download worker factory |
| Singleton | Config management | Settings manager |
graph TD
A[Avrix Application] --> B[PySide6/Qt]
A --> C[yt-dlp]
A --> D[FFmpeg]
B --> E[UI Components]
C --> F[YouTube API]
D --> G[Media Processing]
avrix-downloader/
โ
โโโ ๐ main.py # Application entry point
โโโ ๐ build_exe.py # Executable builder script
โโโ ๐ setup_ffmpeg.py # FFmpeg auto-installer
โโโ ๐ requirements.txt # Python dependencies
โโโ ๐ README.md # This file
โ
โโโ ๐ core/ # Business logic layer
โ โโโ __init__.py
โ โโโ downloader.py # Core download engine (400+ lines)
โ โโโ concurrent_manager.py # Concurrent download orchestration
โ โโโ queue_manager.py # Queue processing system
โ โโโ queue_item.py # Queue item data class
โ โโโ facade.py # Simplified API interface
โ โโโ format_builder.py # yt-dlp format specifications
โ โโโ utils.py # Helper utilities
โ โโโ notification_service.py # Desktop notifications
โ
โโโ ๐ ui/ # User interface layer
โ โโโ __init__.py
โ โโโ main_window.py # Main application window (900+ lines)
โ โโโ progress_widget.py # Download progress display
โ โโโ queue_widget.py # Queue management UI
โ โโโ theme_manager.py # Dark/Light theme system
โ โโโ ui_state_manager.py # UI state coordination
โ
โโโ ๐ config/ # Configuration
โ โโโ settings.json # User preferences (auto-generated)
โ
โโโ ๐ assets/ # Application assets
โ โโโ Avrix_dark.png # Dark theme logo
โ โโโ Avrix_light.png # Light theme logo
โ โโโ avrix_icon.ico # Windows icon
โ โโโ README.md # Asset documentation
โ
โโโ ๐ dist/ # Build output (generated)
โ โโโ Avrix_Installer/
โ โโโ Avrix.exe # Standalone executable
โ โโโ Install_Avrix.bat # Windows installer
โ โโโ Uninstall_Avrix.bat # Windows uninstaller
โ
โโโ ๐ docs/ # Documentation
โโโ ARCHITECTURE.md # System architecture
โโโ BUILD_INSTRUCTIONS.md # Building executables
๏ฟฝ๏ฟฝโโ PROJECT_SUMMARY.md # Project overview
โโโ QUICK_START.md # Quick start guide
Core Module (Backend)
- downloader.py - Main download engine using yt-dlp Python API
- concurrent_manager.py - Manages multiple simultaneous downloads
- queue_manager.py - Processes download queue sequentially
- facade.py - Provides simplified interface for UI layer
- format_builder.py - Constructs yt-dlp format specifications
- utils.py - URL validation, config management, formatting
UI Module (Frontend)
- main_window.py - Main application window and layout
- progress_widget.py - Real-time progress visualization
- queue_widget.py - Queue display and management
- theme_manager.py - Theme switching and styling
- ui_state_manager.py - Coordinates UI element states
Avrix supports downloading multiple items simultaneously for maximum efficiency:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Concurrent Download System โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Thread Pool (Configurable 1-10) โ
โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โDownload 1โ โDownload 2โ ... โ
โ โ Thread โ โ Thread โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Queue Manager โ โ
โ โ โข Processes pending items โ โ
โ โ โข Manages thread lifecycle โ โ
โ โ โข Handles completions โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Via Settings Menu:
Settings โ General โ Max Concurrent Downloads (1-10)
Benefits:
- โก Speed: Download multiple videos simultaneously
- ๐ฏ Efficiency: Maximize bandwidth utilization
- ๐ Flexibility: Adjust based on system resources
- ๐ Tracking: Individual progress for each download
The intelligent queue system allows batch processing of multiple downloads:
| Feature | Description |
|---|---|
| Add to Queue | Queue multiple items for sequential processing |
| Reorder | Drag and drop to change download order |
| Pause/Resume | Control queue processing |
| Clear Queue | Remove all pending items |
| Persistent | Queue survives application restarts |
| Status Tracking | Pending, Downloading, Completed, Failed |
Pending โ Downloading โ Completed โ
โ
Failed โ (with retry option)
โ FFmpeg Not Found
Problem: Application can't find FFmpeg
Solutions:
- Run automatic installer:
python setup_ffmpeg.py - Install manually and add to PATH
- Place
ffmpeg.exein Avrix directory - Restart application after installation
Verification:
ffmpeg -version๐ด Download Fails
Common Causes:
- โ Invalid or private video URL
- ๐ Network connectivity issues
- ๐ Region-restricted content
- ๐ซ Age-restricted videos
Solutions:
- Verify URL is accessible in browser
- Check internet connection
- Try lower quality settings
- Update yt-dlp:
pip install --upgrade yt-dlp
๐ Slow Downloads
Optimization Tips:
- Reduce concurrent downloads (try 2-3)
- Close bandwidth-heavy applications
- Check network speed
- Try different quality settings
- Disable subtitles/thumbnails temporarily
๐พ Out of Disk Space
Prevention:
- Monitor download destination free space
- Clean up old downloads regularly
- Change destination to drive with more space
- Use MP3 format for audio-only (smaller files)
๐ฅ๏ธ Application Won't Start
Source Installation:
# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
# Check Python version
python --version # Should be 3.8+Executable:
- Check Windows Defender/Antivirus
- Run as Administrator
- Download fresh copy from releases
Create your own standalone executable:
# Automated build script
python build_exe.py# Install PyInstaller
pip install pyinstaller
# Build single-file executable
pyinstaller --name=Avrix \
--windowed \
--onefile \
--icon=assets/avrix_icon.ico \
--add-data="assets;assets" \
--add-data="config;config" \
--hidden-import=yt_dlp \
--hidden-import=PySide6 \
main.py
# Output: dist/Avrix.exedist/Avrix_Installer/
โโโ Avrix.exe # ~60 MB standalone executable
โโโ Install_Avrix.bat # Windows installer script
โโโ Uninstall_Avrix.bat # Uninstaller script
โโโ README.txt # User instructions
See: BUILD_INSTRUCTIONS.md for detailed guide
- Core download functionality
- MP3/MP4 format support
- Quality selection (up to 4K)
- Playlist downloads
- Queue management system
- Concurrent downloads (up to 10)
- Dark/Light themes
- Progress tracking with ETA
- Subtitle downloads
- Thumbnail embedding
- Settings persistence
- Desktop notifications
- Windows executable build
- Download history tracking
- Search & filter in queue
- Automatic yt-dlp updates
- Proxy support
- Custom output templates
- Browser extension integration
- Advanced audio codec options (FLAC, WAV)
- Batch URL import from file
- Download scheduler
- Mobile companion app
- Multi-language support (i18n)
- Chromecast integration
- Format conversion tools
- Plugin system
- Command-line interface (CLI)
Want a feature? Open an issue or contribute!
We welcome contributions from the community! Here's how you can help:
- ๐ Report Bugs: Open detailed issue reports
- ๐ก Suggest Features: Share your ideas
- ๐ Improve Documentation: Fix typos, add examples
- ๐ง Submit Code: Pull requests are welcome
- ๐ Translations: Help localize Avrix
- โญ Star the Project: Show your support
# Fork and clone
git clone https://github.com/YOUR_USERNAME/avrix-downloader.git
cd avrix-downloader
# Create feature branch
git checkout -b feature/amazing-feature
# Make your changes
# ... code ...
# Test thoroughly
python main.py
# Commit with clear messages
git commit -m "Add: Amazing new feature"
# Push and create PR
git push origin feature/amazing-feature- Follow PEP 8 style guidelines
- Add docstrings to functions/classes
- Include type hints where appropriate
- Write meaningful commit messages
- Test your changes thoroughly
- Update documentation as needed
 Python Core Language |
 Qt/PySide6 UI Framework |
 yt-dlp Download Engine |
 FFmpeg Media Processing |
- yt-dlp - Feature-rich YouTube downloader
- PySide6 - Official Python Qt bindings
- FFmpeg - Multimedia framework
- PyInstaller - Executable packaging
- Qt Documentation & Examples
- yt-dlp Community & Contributors
- Python Packaging Authority (PyPA)
- Open Source Community
This project is licensed under the Educational License.
Copyright (c) 2025 Yassine Krichen
Permission is granted for educational and personal use only.
Commercial use requires explicit permission from the author.
Special thanks to:
- yt-dlp Team for the incredible download engine
- Qt/PySide6 for the powerful UI framework
- FFmpeg Developers for media processing capabilities
- Open Source Community for inspiration and support
- Beta Testers for valuable feedback
If you find Avrix useful, please consider:
- โญ Starring the repository
- ๐ฆ Sharing with friends
- ๐ Writing a review
- ๐ Contributing code or ideas
Made with โค๏ธ by yassine krichen, for everyone
Built with Python, Qt, and a passion for great software