← Back to projects
Cross-Platform Desktop Media ToolPublic RepositoryActiveOpen Source

VidVortex

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.

Surfaces
Desktop · TUI · CLI
Platforms
Windows · macOS · Linux
Engine
yt-dlp · FFmpeg
Profiles
Fast · Safe · Conservative
Distribution
Python · Windows executable
Status
Active

Stack

  • Python
  • Tkinter
  • Textual
  • yt-dlp
  • FFmpeg
  • PyInstaller
See the Download FlowExplore the Architecture

One engine. Three interfaces. Verified output.

VidVortexSanitized preview

URL

https://example.com/watch?v=demo

Mode

Video

Quality

—

Profile

Safe

Load QualitiesDownload

Ready to load qualities

Why VidVortex Exists

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.

User works with

URL → format → quality → download

Engine handles

  • metadata inspection
  • format selection
  • cookie resolution
  • retries
  • throttling
  • download execution
  • remuxing
  • stream validation
  • platform differences

One Engine, Three Interfaces

The interfaces do not implement separate download behavior. They all call the same engine.

Use it your way

Desktop

GUI

For normal use.

Terminal

TUI

For keyboard-driven workflows.

Command line

vidvortex <url> --mode video --quality 1080

For scripts and batch workflows.

All three surfaces execute the same underlying pipeline.

Visual centerpiece

From URL to verified media

  1. Paste URL
  2. Validate
  3. Fetch metadata
  4. Inspect formats
  5. Select quality
  6. Build yt-dlp command
  7. Download
  8. Remux if needed
  9. FFprobe validation
  10. ✓ Ready
A successful process exit is not the same thing as a valid media file.

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.

Main UI thread

  • buttons
  • forms
  • progress
  • logs

Background thread

  • ├── metadata
  • ├── download
  • ├── ffmpeg
  • ├── validation

root.after(...) → UI update

Activity

  • [metadata] qualities loaded
  • [download] 22.4% · ETA 00:41
  • [download] 64.7% · ETA 00:16
  • [merge] combining video + audio
  • [validate] checking output streams
  • [done] ~/Desktop/VidVortex/video/...

Choose the output before downloading it

Instead of letting users guess format codes, VidVortex first queries metadata and translates available streams into useful choices.

Video

  • Best Available
  • 2160p
  • 1440p
  • 1080p
  • 720p
  • 480p

Audio

  • Best Available
  • 320 kbps
  • 256 kbps
  • 192 kbps
  • 128 kbps

Format strategy

User choice: 1080p

MP4 video
+ M4A audio
+ H.264 / AAC preference
merged MP4

VidVortex translates user-friendly quality choices into yt-dlp format expressions.

Different networks need different behavior

Fast

retries
5
delay
none
aria2c
enabled when available

Prioritizes throughput.

Safe

retries
10
delay
1–3s
aria2c
off

Default balance between speed and reliability.

Conservative

retries
15
delay
2–6s
aria2c
off

More conservative request pacing for restrictive networks.

Adaptive throttling

  1. 429 / 403 / rate-limit pattern
  2. increase throttle level
  3. more retries + additional delay

Authentication without making it the user's problem

VidVortex supports authenticated downloads through browser sessions or imported cookie files — including browser-profile edge cases.

Browser session

  • Chrome
  • Firefox
  • Edge
  • Chromium profiles

↓ --cookies-from-browser

Cookie file

  1. cookies.txt
  2. validate
  3. persist configuration
  4. lock browser source

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.

Same workflow, different operating systems

VidVortex adapts media selection and process execution around platform differences.

Windows / macOS

  • MP4
  • H.264
  • AAC / M4A

Prefer broadly compatible containers and codecs.

Linux

  • Broader codec support
  • Flexible container choices

Allow broader codec and container combinations where compatibility constraints are less strict.

GUI process handling

  • Windows console suppression
  • PATH recovery for double-click launches
  • OS-specific dependency discovery

Trust, then verify

VidVortex validates the output media instead of assuming a completed subprocess produced a usable file.

  1. Output file
  2. Container check
  3. Non-MP4? → FFmpeg remux + faststart
  4. FFprobe
  5. Duration > 0?
  6. Video stream?
  7. Audio stream?
  8. ✓ Valid

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
Not a streaming serviceNot a hosted downloaderNot a media converter websiteNot 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.

From Python project to desktop application

VidVortex checks external dependencies before starting download workflows and provides actionable diagnostics when something is missing.

  1. Source
  2. PyInstaller
  3. Single-file Windows executable

Bundled

  • application code
  • UI assets
  • default configs

Resolved externally

  • yt-dlp
  • FFmpeg
  • ffprobe
  • optional aria2c

VidVortex Doctor

  • Python✓
  • yt-dlp✓
  • FFmpeg✓
  • ffprobe✓
  • aria2coptional

Technical 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

Engineering 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.

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

Planned work — not yet completed features.

  • 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

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