# VidVortex > VidVortex is a desktop media downloader built around yt-dlp and FFmpeg — one shared engine powering GUI, TUI, and CLI with quality selection, reliability profiles, validation, and cross-platform packaging. - HTML: https://estebanech.com/projects/vidvortex - Markdown: https://estebanech.com/projects/vidvortex.md ## Media downloads without the command-line friction. VidVortex turns yt-dlp and FFmpeg into a focused desktop workflow for inspecting available formats, choosing audio or video quality, downloading reliably, and validating the final output. A shared Python engine powers the desktop GUI, terminal interface, and CLI, keeping download behavior consistent across every surface. ## Metadata - Surfaces: Desktop · TUI · CLI - Platforms: Windows · macOS · Linux - Engine: yt-dlp · FFmpeg - Profiles: Fast · Safe · Conservative - Distribution: Python · Windows executable - Status: Active ## Overview yt-dlp and FFmpeg are extremely capable, but their power lives primarily behind command-line options, format selectors, browser-cookie handling, post-processing flags, and platform-specific behavior. VidVortex provides an opinionated layer over that complexity. The user works with URL → format → quality → download while the engine handles metadata inspection, format selection, cookie resolution, retries, throttling, download execution, remuxing, stream validation, and platform differences. You are not pretending you invented media extraction. You built the system that makes the underlying tools approachable and dependable. ## Problem Powerful tools shouldn't require memorizing flags. CLI media tooling is flexible, but most people do not want to decode format selectors, cookie flags, and post-processing options before a simple download works. The engineering question behind VidVortex was: > How do you turn yt-dlp and FFmpeg into a reliable desktop product — with quality picking, retries, validation, and cross-platform behavior — without making users construct commands by hand? ## Solution ### Shared download engine One Python engine powers GUI, TUI, and CLI — no duplicated download pipeline across interfaces. ### Quality abstraction Metadata inspection translates yt-dlp format lists into user-friendly video and audio choices. ### Reliability profiles Fast, Safe, and Conservative profiles tune retries, delays, and optional aria2c acceleration. ### Verified output Post-download FFprobe validation and remuxing ensure a completed subprocess produced usable media. ## Capabilities ### Fast Prioritizes throughput. ### Safe Default balance between speed and reliability. ### Conservative More conservative request pacing for restrictive networks. ## Design Decisions ### One engine, three interfaces Desktop GUI, TUI, and CLI all call vidvortex.py. Download behavior stays consistent; interfaces only handle presentation. ### Validate output, not just exit codes A subprocess can exit cleanly and still produce a broken file. FFprobe checks duration and streams before marking success. ### Wrap yt-dlp and FFmpeg instead of reimplementing extractors Host support and format discovery are moving targets. Wrapping battle-tested tools beats maintaining a custom extraction layer. ### Platform-aware format strategy Windows and macOS prefer MP4/H.264/AAC for compatibility. Linux allows broader codec choices where constraints are looser. ## From URL to verified media **A successful process exit is not the same thing as a valid media file.** - Paste URL - Validate - Fetch metadata - Inspect formats - Select quality - Build yt-dlp command - Download - Remux if needed - FFprobe validation - ✓ Ready ## Choose the output before downloading it Instead of letting users guess format codes, VidVortex first queries metadata and translates available streams into useful choices. VidVortex translates user-friendly quality choices into yt-dlp format expressions. ## Authentication without making it the user's problem VidVortex supports authenticated downloads through browser sessions or imported cookie files — including browser-profile edge cases. ### Atlas compatibility When a browser is not directly recognized by yt-dlp, VidVortex can resolve its Chromium profile path and translate it into a compatible browser-profile target. ## Trust, then verify VidVortex validates the output media instead of assuming a completed subprocess produced a usable file. ## Defensive boundaries URL validation happens before metadata retrieval and again before download execution. - HTTP / HTTPS only - localhost blocked - private/reserved IPs rejected - playlists disabled by default - subprocess cancellation supported ## The interface never owns the long-running work Long-running subprocess work happens off the Tk event loop; interface updates are marshalled back onto the main thread. ## From Python project to desktop application VidVortex checks external dependencies before starting download workflows and provides actionable diagnostics when something is missing. ## What VidVortex is not - Not a streaming service - Not a hosted downloader - Not a media converter website - Not a separate download engine **It is a desktop workflow around yt-dlp and FFmpeg.** Users are responsible for downloading media they are permitted to access and retain. ## Highlights - 03 Interfaces — Desktop · TUI · CLI - 01 Shared engine — No duplicated download pipeline - 03 Runtime profiles — Fast · Safe · Conservative - 02 Media tools — yt-dlp · FFmpeg - 02 Validation passes — URL · Output media - — Cross-platform — Windows · macOS · Linux ## Technology ### Interfaces - Tkinter / ttk — desktop GUI - Textual — terminal UI - CLI — scripted and batch workflows ### Engine & media - Python 3 — orchestration and subprocess management - yt-dlp — extraction and format discovery - FFmpeg / ffprobe — remux, validation, post-processing - aria2c — optional download accelerator ### Packaging & delivery - PyInstaller — single-file Windows executable - GitHub Actions — cross-platform releases - Per-OS setup scripts — dependency discovery ## Status VidVortex is an active open-source desktop tool. The shared engine powers GUI, TUI, and CLI surfaces across Windows, macOS, and Linux. Distribution includes Python source and a PyInstaller Windows executable. External dependencies (yt-dlp, FFmpeg, ffprobe) are validated before download workflows start. ## Next Steps - Keep release packaging current with yt-dlp and FFmpeg changes - Improve first-run diagnostics when toolchain detection fails - Refine activity logging for faster support on auth and cookie edge cases Author: Andres Echeverria (estebanech)