← Back to projects
Cross-Platform Media DownloaderPublic Repository

VidVortex

A Cross-Platform Media Downloader Friends Can Actually Run

VidVortex is a desktop app for pulling audio or video from a URL — paste a link, choose video or audio, load qualities, and download to organized folders — without requiring users to memorize yt-dlp flags.

Python · yt-dlp · ffmpeg · GitHub Releases

Role
Sole Designer and Engineer
Type
Open Source Tool
Status
Shipped
Distribution
GitHub Releases
Platforms
Windows · macOS · Linux
Repository
Public

Technologies

  • Python 3
  • yt-dlp
  • ffmpeg
  • PyInstaller
  • GitHub Actions
  • Shell / Batch / PowerShell
VidVortex desktop app showing URL input, quality selection, and download activity
VidVortex — paste a URL, pick quality, and download video or audio across Windows, macOS, and Linux.

Overview

VidVortex wraps the power of yt-dlp and ffmpeg in a small native-feeling desktop workflow. Users paste a link, choose video or audio, load available qualities, and download into organized output folders.

The hard part was not the download call itself — it was making the toolchain reliable on real machines: first-run setup, PATH hygiene, frozen builds per OS, and clear Activity feedback when hosts (especially YouTube) need cookies or extra auth steps.

The Problem

CLI media tools are flexible, but friends and family rarely want to install Python packages, resolve ffmpeg PATH issues, or decode format selectors before a simple download works.

The engineering question behind VidVortex was:

“How do you ship a yt-dlp/ffmpeg workflow as something people can run from GitHub Releases — with quality picking, setup UX, and supportable error feedback — without reading a man page first?”

The Solution

  1. 01

    Desktop download flow

    A focused UI for URL input, media type selection, quality discovery, and download orchestration with in-app Activity/status feedback.

  2. 02

    Per-OS setup scripts

    First-run scripts install or refresh yt-dlp and ffmpeg on Windows, macOS (arm64/Intel), and Linux so the GUI inherits a working toolchain.

  3. 03

    Release packaging

    PyInstaller-style frozen builds and GitHub Actions produce versioned zips for each platform so distribution does not depend on users cloning the repo.

Core Capabilities

Quality-aware downloads

Discover formats via yt-dlp, let the user pick quality, and route mux/remux work through ffmpeg instead of exposing raw CLI selectors.

Host edge-case handling

In-app guidance for tricky hosts — browser cookie hints, optional Netscape cookies.txt, and Activity logging for supportability.

Cross-platform packaging

Windows .exe, macOS launcher + .bin, and Linux binary layouts documented for GitHub Releases consumers.

Toolchain hygiene

Launcher scripts keep GUI runs on the same PATH users verify in Terminal — especially important on macOS security and Homebrew setups.

Key Engineering Decisions

Build on yt-dlp + ffmpeg instead of reimplementing extractors

Rationale: Host support and format discovery are moving targets. Wrapping battle-tested tools beats maintaining a custom extraction layer.

Invest in first-run setup UX

Rationale: Most download failures for non-technical users are environment failures. Setup scripts and PATH hygiene matter more than extra UI chrome.

Ship via GitHub Actions Releases

Rationale: Versioned platform zips let friends install without cloning, and CI keeps packaging reproducible across Windows, macOS, and Linux.

Technical Highlights

  • Python desktop UI + yt-dlp/ffmpeg orchestration
  • Per-OS setup scripts for dependency refresh
  • Quality picking without CLI flag gymnastics
  • Cookie/auth flows for YouTube-class hosts
  • PyInstaller-style frozen builds per platform
  • GitHub Actions release packaging

Technology

Languages & runtime

  • Python 3 — UI, orchestration, subprocess integration
  • Shell / Batch / PowerShell — setup and release automation

Core stack

  • yt-dlp — extraction & format discovery
  • ffmpeg — mux/remux pipelines

Packaging & delivery

  • PyInstaller-style frozen builds
  • GitHub Actions cross-platform releases
  • Windows · macOS arm64/Intel · Linux

Current Status

VidVortex is shipped as a public open-source tool. Builds are distributed through GitHub Releases for Windows, macOS, and Linux.

Ongoing work focuses on keeping yt-dlp/ffmpeg paths reliable as host sites and packaging environments change.

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/cookie edge cases