NovaDL: The All-In-One Media Downloader
The fastest YouTube downloader, Insta downloader, and comprehensive video/audio media downloader for Windows.
Whether you need a reliable youtube downloader to save playlists in 4K, a quick insta downloader for reels, or a versatile audio and video media downloader, NovaDL handles it all. Built with Flutter, it demonstrates complex systems engineering while providing users with a beautiful, ad-free experience.
The core downloading logic is abstracted behind the DownloadEngineContract
(domain/download_engine_contract.dart). This allows NovaDL to dynamically route downloads to the best engine
based on the file type, user settings, or protocol.
App Showcase
Comprehensive Dashboard
The control center for all media operations, providing real-time analytics and global state management at a glance.
- Real-time Analytics: Track active downloads, queued items, and live network speed.
- Storage Insights: Visual media distribution pie charts and exact storage footprint metrics.
- Smart Alerts: Push notifications for completed downloads directly in the UI.
Advanced Download Engine
A granular configuration interface giving power users absolute control over media processing.
- Format Selection: Choose exact resolutions, video/audio codecs (e.g., mp4, Best Audio).
- Parallelization: Configure up to 32x concurrent threads for maximum bandwidth utilization.
- Automation: Built-in SponsorBlock integration and metadata/subtitle embedding toggles.
Integrated Web Browser
A custom-built, secure in-app browser designed specifically for media discovery and seamless extraction.
- Ad-Free Experience: Integrated uBlock-style adblocking engine enabled by default.
- Media Detection: One-click floating "Download" FAB that scans the active page for extractable video/audio.
- Quick Access: Custom homepage with speed dials for YouTube and supported platforms.
Organized Media Library
A robust file management system that categorizes downloads automatically without needing an external file explorer.
- Smart Categorization: Auto-sorts into Video, Audio, Images, and Screenshots tabs.
- Deep Search: Find files instantly using tags, creators, codecs, or exact filenames.
- Layout Controls: Toggle between grid and list views with chronological or alphabetical sorting.
Deep Customization
Every aspect of the application is configurable, ensuring it adapts to the user's specific network and hardware capabilities.
- Network Engine: Tweak simultaneous downloads and turbo connections for optimal speed.
- Traffic Shaping: Set global speed limits and bypass throttling for specific domains.
- Automation: Configure file naming templates, metadata embedding, and default resolutions.
Privacy & Security Controls
The integrated browser includes enterprise-grade security and privacy toggles natively.
- Tracking Prevention: Multiple tiers (Basic, Balanced, Strict) to block unwanted trackers.
- Popup Blocking: Prevents intrusive ad overlays and forced redirects natively.
- Countdown Skip: Automatically fast-forwards through generic JavaScript countdown timers.
Infrastructure Layer
There are multiple independent download engines tailored for specific tasks.
🎥 yt_dlp_service.dart
Purpose: Wraps the yt-dlp executable.
Usage: Automatically used for YouTube videos, playlists, streaming sites, or any URL supported by yt-dlp extractors. Handles format selection, cookie passing, and delegates post-processing to ffmpeg.
⚡ aria2_service.dart
Purpose: Orchestrates the aria2c daemon via JSON-RPC.
Usage: Used for Torrents, Magnet Links, and heavily multi-threaded standard HTTP/FTP downloads.
📄 direct_download_service.dart
Purpose: A standard Dart-native (dio based) HTTP downloader.
Usage: Used for simple, small files, or when external dependencies are unavailable.
🚀 turbo_downloader.dart
Purpose: A custom multi-part/chunked HTTP downloader.
Usage: Accelerates standard direct downloads by splitting the file into byte ranges and downloading them concurrently using Dart isolates.
Application Layer
Managing global queues and inter-process communication.
queue_manager.dart
Manages the global download queue, limits concurrent downloads, handles pausing/resuming, and persists the queue state to the SQLite database.
ipc_download_engine.dart
Handles Inter-Process Communication (IPC) for downloads initiated from popup browser windows (which run in separate OS processes).
App Features
Core Utilities
Centralized Logging System
Built on top of Dart's logging package. Automatically categorizes logs into domains (Downloader, Browser, DNS, Database) based on logger name. Writes JSON-formatted logs to disk for debugging.
Smart File Conflict Resolution
Smartly renames files if a collision occurs (e.g., appends (1) to video.mp4).
Power Management
Uses native Windows APIs to prevent the PC from sleeping while active downloads are running.
Multi-Window & IPC Support
NovaDL supports multi-window capabilities (like tearing off a browser tab). Because Flutter Windows spawns these as entirely new OS processes, the EventBus handles cross-process state syncing.
Security & Path Guard
Validates file paths to prevent directory traversal attacks during downloads.
Graceful Shutdown Manager
Intercepts the window close button to gracefully shutdown aria2c daemons and local servers before exiting.
Local Storage & Network
Persistent Local Storage (SQLite)
The single source of truth for persistent data. Contains DAOs for Download History, Browser History, Favorites, and Settings. Uses Moor/Drift or raw sqlite3.
Custom Local Network Stack (Proxy & DoH)
Includes a completely custom local HTTP Proxy and DNS-over-HTTPS (DoH) client.
proxy_server: Local shelf/socket server the WebView routes traffic through.doh_client: Resolves domain names securely and feeds them to the proxy.proxy_speed_limiter: Throttles browser bandwidth to prioritize background downloads.
Services & External Integrations
Integrated Adblocking Engine
A full-fledged cosmetic and network adblocking engine for the WebView. Parses standard EasyList/uBlock rules and injects them into the browser.
Local HTTP Browser Bridge
Because WebView2's native JS bridge can be brittle, NovaDL runs a local HTTP shelf server. JavaScript injected into the webview sends POST requests to this local server to trigger Flutter actions.
FFmpeg Media Processing
Interfaces with the ffmpeg binary to merge video/audio streams downloaded by yt-dlp.
Remote Web Interface
A local web interface allowing users to monitor their NovaDL instance remotely from another device on the network.
State & UI Layers
Reactive State Management (Riverpod)
Provides global state and settings access across the UI seamlessly, eliminating the need to pass data manually down the widget tree.
Modern App Shell
The main application scaffold featuring a dynamic Sidebar, Titlebar, and responsive content area.
Advanced In-App Browser
The core WebView component. Extremely complex. Handles JS injections, native window focus logic, popup blocking, and tab management.
Active Downloads & Bandwidth Monitor
The active downloads queue UI, including visual bandwidth monitoring and torrent selection dialogs.
Critical Hacks & Quirks
Crucial information for developers and AI agents working on the codebase.
⚠️ The WebView2 Focus/Blur Bug
The Issue: Because the Edge WebView is integrated as a native Windows HWND embedded in a
Flutter window, clicking inside the WebView causes Windows to fire WM_MOUSEACTIVATE. This
momentarily steals focus back to the parent Flutter window, firing synthetic blur and focusout events inside
the JS environment.
The Consequence: Modern web apps (like YouTube and Google) listen to blur and instantly close dropdown menus when clicked.
The Fix: We inject a persistent script (__nova_popup_fix) that intercepts
blur and focusout in the capture phase and calls e.stopImmediatePropagation(), unless the
target is an INPUT element. Do not remove or alter this patch unless strictly necessary.
⚠️ Page Enhancement Scripts (Safe Mode)
We inject several scripts into the DOM. Always gate new script injections behind
settings.enablePageScripts. This allows the user to toggle off all custom JS ("Safe Mode") if a
website breaks.
Use addScriptToExecuteOnDocumentCreated for persistent scripts, not
executeScript, so they survive page navigations.
⚠️ Process Lifecycle
Because NovaDL orchestrates multiple external binaries (yt-dlp, aria2c, ffmpeg), always ensure that
processes are properly tracked and killed in app_close_handler.dart. Orphaned aria2c instances
will lock ports and break the app on the next launch.