<p align="center"> <img src="https://github.com/Rashed-alothman/Snatch/blob/main/main/assets/D7542102-E425-4F89-9D00-371C493D6033.png" alt="Snatch Logo" width="600" /> </p> <h1 align="center">Snatch</h1> <h3 align="center">Download Anything, Anywhere, Anytime</h3> <p align="center"> <a href="#features">Features</a> • <a href="#installation">Installation</a> • <a href="#quick-start">Quick Start</a> • <a href="#usage">Usage</a> • <a href="#supported-sites">Supported Sites</a> • <a href="#troubleshooting">Troubleshooting</a> </p> <p> <img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Rashed-alothman/f2ae0a272ff1f011523e43f8c5abad65/raw/snatch-ci-status.json"/> <img src="https://github.com/Rashed-alothman/Snatch/actions/workflows/codeql.yml/badge.svg" alt="CodeQL Status" /> <img src="https://img.shields.io/badge/version-2.0.0-blue" alt="Version 2.0.0" /> <img src="https://img.shields.io/badge/python-3.10+-yellow" alt="Python 3.10+" /> <img src="https://img.shields.io/badge/platforms-Windows%20|%20macOS%20|%20Linux-green" alt="Platforms" /> <img src="https://img.shields.io/badge/license-MIT-orange" alt="License" /> </p>

What's New in v2.0.0

Package Restructuring

Renamed package: modules/ → snatch/ with proper Python packaging
Modern packaging: Added pyproject.toml with optional dependency groups ([audio], [p2p], [video])
Console entry point: snatch command available globally after pip install
Consolidated config: Merged 4 config modules into 2 clean ones
Fixed Theme imports: Moved Theme/ into snatch/theme/ sub-package with corrected imports
Unified version: Single source of truth for version 2.0.0 in constants.py
Cleaned CI/CD: Fully updated GitHub Actions pipeline for new package structure
Test infrastructure: pytest-based test suite with fixtures for config, cache, CLI

Installation

# Basic install
pip install -e .

# With all optional features
pip install -e ".[all]"

# Audio processing features only
pip install -e ".[audio]"

# Development
pip install -e ".[dev,all]"

Features

🎯 Major Features & Enhancements

🎵 Comprehensive Audio Enhancement System

AI-Powered Audio Enhancement: Advanced noise reduction, frequency extension, and stereo widening
Professional Audio Presets: 5 curated presets (podcast, music, speech, broadcast, restoration)
Sample Rate Upscaling: Intelligent upsampling to higher quality audio
Dynamic Range Processing: Professional loudness normalization and compression
Audio Quality Analysis: Automatic preset recommendations based on content analysis
CLI Integration: Complete command-line interface for audio enhancement

🔧 Fixed Resolution Selection Bug

RESOLVED: Resolution flags (--resolution, -r) now work correctly
IMPACT: When requesting 2160p/4K, system now properly selects the highest available quality
IMPROVEMENT: Enhanced format string generation with proper fallback chains

🚀 AI-Powered Video Upscaling

NEW: Real-ESRGAN integration for AI-enhanced video quality
METHODS: Support for both AI (Real-ESRGAN) and traditional (Lanczos, Bicubic) upscaling
FLEXIBLE: 2x and 4x upscaling factors with quality preservation options
EFFICIENT: Optimized processing pipeline with progress tracking

🎮 Interactive Mode Enhancements

Enhanced UI: Modern Textual-based interface with rich components
Audio Processing: Built-in audio conversion and enhancement tools
File Management: Advanced file organization and management features
Real-time Processing: Background audio/video processing with progress tracking

📚 Comprehensive Documentation

🎯 Features Update Guide - Detailed overview of new features
📖 Usage Guide - Complete command examples and workflows
🔧 Technical Documentation - Architecture and implementation details

Quick Examples:

# Fixed resolution selection (now works correctly)
snatch download "URL" --resolution 2160  # Actually gets 4K!

# AI video upscaling
snatch download "URL" --upscale --upscale-method realesrgan --upscale-factor 2

# Audio enhancement with presets
snatch audio enhance myfile.mp3 --preset music
snatch audio enhance podcast.wav --preset podcast --output enhanced_podcast.wav

# Audio quality analysis and recommendations
snatch audio analyze myfile.wav
snatch audio presets --detailed

# Batch audio processing
snatch audio batch "*.mp3" --preset restoration

# Combine resolution + upscaling for optimal results
snatch download "URL" --resolution 720 --upscale --upscale-factor 4 --replace-original

🎯 Major Architectural Overhaul

Complete Package Refactoring & Modularization

Modular Architecture: Well-structured snatch/ package:
- cli.py - Command-line interface and argument parsing (Typer)
- manager.py - Core download management and orchestration (yt-dlp)
- config.py - Configuration loading, validation, and management
- config_manager.py - Advanced configuration editing, profiles, backup/restore
- audio_processor.py - Advanced audio enhancement and processing
- ffmpeg_helper.py - Video upscaling and FFmpeg processing
- p2p.py - Peer-to-peer networking and file sharing
- cache.py - Intelligent caching and metadata storage
- session.py - Download session management and resume
- progress.py - Enhanced progress tracking and display
- common_utils.py - Shared utilities and helper functions
- logging_config.py - Comprehensive logging configuration
- constants.py - Application constants, version, and defaults
- metadata.py - Media information extraction and processing
- theme/ - Modern TUI interfaces (Textual, Rich)

Enhanced Plugin System

Hook-Based Architecture: Comprehensive plugin system with multiple hook points
Plugin Interfaces: Support for DownloadHooks, ProcessingPlugin, and UIPlugin
Dynamic Loading: Automatic plugin discovery and registration
Event System: Pre/post download hooks, format processing, and UI customization

Advanced Audio Processing

AI-Enhanced Audio: Intelligent audio enhancement using machine learning algorithms
Multi-Format Support: Opus, MP3, FLAC, WAV, and M4A with quality optimization
Audio Normalization: Automatic loudness normalization and dynamic range processing
Surround Sound: Support for stereo and 7.1 surround sound configurations

Peer-to-Peer Networking

P2P File Sharing: Share downloaded content directly with other users
Share Code System: Generate unique codes for easy file sharing
Network Discovery: Automatic peer discovery and connection management
Distributed Caching: Leverage peer network for faster downloads

🚀 Performance & User Experience Improvements

Smart Performance Optimization

Adaptive Resource Management: Dynamic chunk sizes based on system resources
Network Speed Testing: Automatic optimization based on connection speed
Smart Format Selection: Intelligent format selection without testing all possibilities
Concurrent Processing: Enhanced multi-threaded download and processing

Enhanced User Interface

Cyberpunk Theme: Futuristic, neon-styled interface with animations
Interactive Progress: Real-time progress bars with detailed statistics
Spinner Animations: Enhanced visual feedback during operations
Rich Console Output: Color-coded messages and status indicators

Improved Error Handling & Recovery

Intelligent Retry Logic: Exponential backoff with smart failure recovery
Detailed Error Messages: Actionable error descriptions with solutions
Advanced Logging: Comprehensive logging with configurable verbosity levels
Graceful Degradation: Fallback mechanisms for various failure scenarios

📚 Comprehensive Documentation Suite

We've created an extensive documentation ecosystem to support developers and users:

📖 Technical Documentation

Complete system architecture overview with visual diagrams
Component interaction flows and data flow analysis
Dependency relationships and module hierarchies
Comprehensive file structure documentation

🔧 Module Documentation

In-depth analysis of all core modules
Function signatures, parameters, and return values
Usage examples and best practices
Module interaction patterns

🔌 Plugin Development Guide

Complete plugin architecture documentation
Hook system explanation with practical examples
Plugin registration and lifecycle management
Sample plugin implementations

📋 API Reference

Comprehensive API documentation
Method signatures with detailed parameters
Error handling and return codes
Usage examples for all major functions

🚀 Deployment Guide

Development environment setup
Production deployment strategies
Docker containerization
Platform-specific installation guides
Security considerations and best practices

⚡ Performance Optimization Guide

System resource optimization strategies
Network performance tuning
Memory and CPU optimization techniques
Caching strategies and storage optimization
Platform-specific performance tips

Snatch

Install / Use

README