mangofetch-core 0.5.1

• 🥭 mangofetch
  • Overview
  • 🛠️ Installation
    • Via Cargo (Recommended)
    • From Source
  • ✨ Key Features (v0.5.1)
  • 🏗️ Technical Architecture
    • Core Components
  • ⚙️ The Core Engine Lifecycle
    • Key Engineering Milestones
  • 🕹️ Command Reference
  • 🗺️ Roadmap & Milestones
  • 🤝 Acknowledgments
  • Contributing
  • License

Overview

MangoFetch represents a paradigm shift in terminal-based media acquisition. Engineered with uncompromising standards for memory safety and concurrency, it eschews bloated graphical interfaces in favor of a raw, low-latency execution environment. Built upon the robust foundations of Tokio and Reqwest, the engine is explicitly designed to saturate network throughput and orchestrate massive archival batches seamlessly, completely decoupling asynchronous I/O operations from the main thread.

With the release of v0.5.1, MangoFetch transcends traditional CLI tools by introducing a professional-grade TUI (Terminal User Interface). This interface blends hardcore operational efficiency with striking visual ergonomics, featuring dynamic settings management, fluid mouse event propagation, and a suite of 11 bespoke Tropical Fruit color palettes.

As of v0.5.1, MangoFetch features a professional-grade TUI (Terminal User Interface) with tropical fruit themes, mouse support, and an advanced dynamic settings engine.

🛠️ 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

✨ Key Features (v0.5.1)

• 1000+ Platforms: Deep, zero-overhead integration with yt-dlp to support virtually any media portal on the internet.
• Interactive TUI: A highly responsive, full-screen dashboard powered by ratatui, featuring 11 Tropical Fruit Themes (Mango, Pitaya, Guayaba, Passionfruit, and more).
• Fluid Mouse Support: Full support for pointer events—scroll through sprawling download queues and actuate tabs directly via mouse telemetry.
• Vim-Style Commands: For the ultimate power user, actuate ultra-fast, non-blocking operations via the : command buffer.
• P2P & Torrents: Native protocol implementations for magnet links and peer-to-peer decentralized file sharing.
• Intelligent Extraction Engine: Features multi-segment HTTP downloads, staggered connection starts to bypass rate limits, and zero-copy metadata embedding.

🏗️ Technical Architecture

MangoFetch is rigorously organized as a modular workspace, enforcing strict separation of concerns. This architectural decision ensures the core engine remains portable, highly testable, and isolated from the 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)]

Core Components

• mangofetch-core: The UI-agnostic heartbeat of the system. It governs the asynchronous download queue, orchestrates connection pooling, and houses the platform-specific native extractors (YouTube, Instagram, TikTok, etc.). It intelligently encapsulates yt-dlp and ffmpeg for complex stream muxing, automatically provisioning these binaries if omitted from the host $PATH.
• mangofetch-cli: A hyper-lightweight frontend built with clap. It acts as a highly optimized dispatcher consuming the core library, rendering real-time telemetry via a brutalist, information-dense ANSI interface or the interactive TUI.
• mangofetch-plugin-sdk: A robust FFI-compatible SDK engineered to extend MangoFetch's capabilities dynamically at runtime via shared libraries (.so / .dll).

⚙️ The Core Engine Lifecycle

The mangofetch-core queue is intrinsically fault-tolerant. Operating on a resilient asynchronous loop, if a single task in a 10,000-item batch encounters a network anomaly, the queue isolates the failure, initiates exponential backoff retries, and continues processing the matrix without stalling.

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 Milestones

• Asynchronous I/O Pipeline: Built upon tokio::sync::mpsc channels for non-blocking progress reporting. The UI rendering thread is completely decoupled from the heavy I/O threads, guaranteeing fluid terminal refreshes.
• Self-Healing Dependencies: Automatic checksum validation, resolution, downloading, and path-linking of external binaries (ffmpeg, yt-dlp).
• Intelligent Parser Heuristics: The Platform Registry attempts to natively parse media using zero-cost abstractions, falling back to generic extractors only when mathematically necessary.

🕹️ Command Reference

For a comprehensive breakdown of all execution flags, API arguments, and TUI keybindings, please consult our Official Engineering Wiki.

• 🚀 Installation Guide
• 🛠️ CLI Command Reference
• 🖥️ TUI Interactive Guide
• 🏗️ Technical Architecture

🗺️ 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. We adhere to rigorous engineering standards. For major architectural permutations, please open an RFC issue first to discuss your algorithm and approach. See CONTRIBUTING.md for guidelines.

License