🥭 mangofetch

Brutally fast. Extensible. Pure Rust.
A high-performance, asynchronous download engine for the terminal.

Overview

MangoFetch is a highly concurrent, memory-safe media download engine. It eschews bloated graphical interfaces in favor of a raw, low-latency command-line interface. Built on top of Tokio and Reqwest, it is designed to maximize network throughput and handle massive archival batches without blocking the main thread.

Lineage and Credit: MangoFetch is an independent, terminal-focused evolution of the OmniGet project by tonhowft. While MangoFetch has been heavily refactored and optimized for pure CLI usage and extreme performance, the robust underlying core engine owes its existence to the brilliant foundational work done in OmniGet.

🏗️ Technical Architecture

MangoFetch is organized as a modular workspace, ensuring strict separation of concerns. This allows the core engine to be portable and highly testable, while the CLI remains a thin rendering layer.

graph TD
    User([Terminal User]) -->|CLI Commands| CLI(mangofetch-cli)
    
    subgraph MangoFetch Workspace
        CLI -->|Dispatch & Render| Core(mangofetch-core)
        
        subgraph Core Engine
            Core --> Queue[Async Download Queue]
            Core --> Registry[Platform Registry]
            Queue --> IO[Tokio Async I/O]
            Registry --> Ext_Native[Native Extractors]
            Registry --> Ext_Generic[Generic Extractor]
        end
        
        CLI -.->|Dynamic Linking| SDK(mangofetch-plugin-sdk)
    end
    
    Ext_Generic -->|Wraps| YTDLP[yt-dlp Binary]
    Ext_Native -->|Muxes Audio/Video| FFmpeg[FFmpeg Binary]
    YTDLP -.-> Network((Internet))
    IO -.-> Network
    IO --> Disk[(Local Storage)]

Components

• mangofetch-core: The UI-agnostic engine. It manages the asynchronous download queue, handles connection pooling, and contains the platform-specific extractors (native parsers for YouTube, Instagram, TikTok, etc.). It intelligently wraps yt-dlp and ffmpeg for complex media streams, automatically provisioning these binaries if they are missing.
• mangofetch-cli: A lightweight frontend built with clap. It acts as a thin dispatcher that consumes the core library, rendering real-time progress via a brutalist, information-dense ANSI interface.
• mangofetch-plugin-sdk: A robust FFI-compatible SDK designed for extending MangoFetch's capabilities dynamically via shared libraries (.so / .dll).

⚙️ The Core Engine Lifecycle

The mangofetch-core queue is fault-tolerant. If a single item in a 1,000-item batch fails, the queue continues processing, aggregating failures for the final summary.

stateDiagram-v2
    [*] --> Queued : User Submits URL
    Queued --> FetchingMetadata : Worker Thread Picks Item
    FetchingMetadata --> Active : Media Info Resolved
    FetchingMetadata --> Error : Network/Parse Failure
    
    state Active {
        [*] --> Allocating
        Allocating --> Downloading : Progress Stream via MPSC
        Downloading --> Muxing : Audio+Video Merge (FFmpeg)
        Muxing --> [*]
    }
    
    Active --> Complete : Success
    Active --> Error : Interruption / Connection Drop
    Error --> Queued : Retry Logic Triggered
    Complete --> [*]

Key Engineering Features:

• Asynchronous I/O Pipeline: Utilizing tokio::sync::mpsc channels for non-blocking progress reporting. The UI thread is completely decoupled from the I/O threads.
• Self-Healing Dependencies: Automatic resolution, downloading, and path-linking of external binaries (ffmpeg, yt-dlp). The user never has to touch their $PATH.
• Intelligent Parsers: The Platform Registry attempts to natively parse media (saving overhead) before falling back to generic extractors.

🕹️ Command Reference

MangoFetch is designed for speed. While the full mangofetch commands provide clarity, an upcoming release will introduce the mango binary and ultra-short aliases for power users.

🛠️ Installation

Via Cargo (Recommended)

The fastest way to install the CLI directly to your system path:

cargo install mangofetch-cli

From Source

For developers who want the absolute bleeding edge or wish to modify the core:

git clone https://github.com/julesklord/mangofetch-cli.git

cd mangofetch-cli

cargo build --release

# The compiled binary will be available at: target/release/mangofetch

🗺️ Roadmap & Milestones

🤝 Acknowledgments

• OmniGet — The absolute backbone of this project. A huge shoutout to tonhowft for architecting the original extraction logic and queue engine that MangoFetch builds upon.
• yt-dlp — The incredible extraction engine handling the heavy lifting for over a thousand unsupported platforms.

Contributing

Pull requests are fiercely welcomed. For major architectural changes, please open an issue first to discuss your approach. See CONTRIBUTING.md for guidelines.

License