# VidVortex

> VidVortex is a cross-platform desktop media downloader built with Python, yt-dlp, and ffmpeg — with per-OS setup scripts and GitHub Releases packaging.

- HTML: https://estebanech.com/projects/vidvortex
- Markdown: https://estebanech.com/projects/vidvortex.md

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

## Metadata

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

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

## 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?

## Solution

### Desktop download flow

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

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

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

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

## Design Decisions

### Build on yt-dlp + ffmpeg instead of reimplementing extractors

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

### Invest in first-run setup UX

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

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

## 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

## 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

- 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

Author: Andres Echeverria (estebanech)