YCIS MDL

A high-performance, visually polished yt-dlp terminal media downloader wrapper for YouTube, Instagram, TikTok, X/Twitter, SoundCloud, Reddit, and 1000+ sites.

Paste a link, customize formats, and let yt-dlp handle the heavy lifting through a clean, double-panel TUI.

📖 Table of Contents

• Why YCIS MDL?
• Supported Platforms
• Key Features
• Installation
• Quick Start
• TUI Keyboard Directory
• CLI Command Reference
• Configuration & Storage
• License

❓ Why YCIS MDL?

ycis-mdl wraps the raw power of yt-dlp in a guided terminal application. It provides:

1. One-Command Downloads: Fast, argument-driven queries when you know exactly what you need.
2. Interactive TUI: A split-panel, context-rich dashboard for previewing media metadata, choosing video/audio/image formats, running batch downloads, and managing history.
3. Optimized Defaults: Sensible, pre-configured flags for Termux (Android), Linux, macOS, and Windows.

🌐 Supported Platforms

Supports all major media hosting backends compatible with yt-dlp:

• Video & Short-form: YouTube (videos, playlists, channels, Shorts), Instagram (Posts, Reels, IGTV), TikTok, X/Twitter, Vimeo, Facebook, Dailymotion.
• Audio & Music: SoundCloud tracks, playlists, sets.
• Image & Graphics: Pinterest pins, Tumblr posts, Reddit threads, and generic image URLs.

For private, restricted, or age-gated media, see the Configuration section on exporting and utilizing Netscape cookies.

⚡ Key Features

| Feature | Description | | :--- | :--- | | Split-Pane Grid | Dynamically splits TUI into Left Navigation and Right Context preview panels. Autodetects terminal width and collapses to a single-pane on mobile or narrow viewports. | | Micro-Animations | Real-time ticking UTC clock, pulsing header colors, rotating load spinners, and rolling speed graph sparklines. | | Double-Buffered Display | Completely flicker-free screen drawing using ANSI cursor repositioning instead of full terminal clearing. | | TUI Suspension | Automatically halts rendering loops during interactive text prompts or external update subprocesses to protect terminal output alignment. | | Smart Quality Fallback | Handles codec/resolution negotiations cleanly and falls back automatically based on user options. | | Autonomic Retries | Detects geo-restrictions, rate-limits (HTTP 429), or private links, and prompts with actionable remediation tips. |

📦 Installation

Install the package globally via npm:

npm install -g ycis-mdl

System Prerequisites

Ensure the following binaries are available on your system path:

1. Node.js >= 18.0.0
2. npm >= 9
3. yt-dlp (Required for metadata fetching and stream queries)
4. ffmpeg (Highly recommended; required for HD streams merging, audio extraction, and subtitle embedding)

If yt-dlp or ffmpeg is missing, navigate to the Setup & Dependencies tab inside the TUI to install or update them.

🚀 Quick Start

Launch the interactive split-pane interface:

ycis-mdl

Or trigger a direct download:

# Auto-detect mode & format
ycis-mdl "https://youtu.be/dQw4w9WgXcQ"

# Force MP3 audio extraction
ycis-mdl URL -m audio -f mp3

# Download 1080p MP4 video
ycis-mdl URL -m video -f mp4 -q 1080p

# Run batch downloads with concurrency
ycis-mdl --batch links.txt --concurrency 3

⌨️ TUI Keyboard Directory

When navigating the TUI Dashboard:

• [ ↑ / ↓ ] or [ J / K ] : Move menu selection up / down.
• [ ← / → ] or [ H / L ] : Cycle selection values in options configurations.
• [ Enter ] : Confirm selection / execute current action.
• [ Esc ] : Return to the previous view or exit the application.
• [ Backspace ] : Delete last character in text inputs.

🛠️ CLI Command Reference

| Action | Command Syntax | | :--- | :--- | | Open TUI Dashboard | ycis-mdl | | Download URL | ycis-mdl <url> | | Save audio as MP3 | ycis-mdl <url> -m audio -f mp3 | | Save 1080p MP4 | ycis-mdl <url> -m video -f mp4 -q 1080p | | Embed cover art | ycis-mdl <url> -m audio -f mp3 --embed-thumbnail | | Download subtitles | ycis-mdl <url> -m video --subtitles --sub-langs en | | Dry run metadata print | ycis-mdl <url> --info | | Run batch from text file | ycis-mdl --batch urls.txt | | Show recent downloads | ycis-mdl --history | | Update dependencies | ycis-mdl update |

⚙️ Configuration & Storage

Settings are managed interactively through the Settings view in the TUI.

Persisted Files

Data is saved locally under your home directory:

• Config Storage: ~/.config/configstore/ycis-mdl.json
• Job Queue: ~/.ycis-mdl_queue.json
• Download History: ~/.ycis-mdl_history.json

Using Cookies

To download private videos, member-only streams, or content requiring authentication:

1. Export your browser cookies using a standard extension (e.g., GetCookies.txt) in Netscape format.
2. Save the file to your disk (e.g., ~/cookies.txt).
3. Set the absolute path to this file under the Cookies file option in Settings.

📄 License

Distributed under the MIT License. Built with 💜 by YCIS.