Music Getter

A local Mac Video & Audio download tool powered by yt-dlp and ffmpeg. Paste up to 3 URLs, inspect available formats, and download audio in MP3, WAV, FLAC, or the original best quality.

Requirements

• Bun — replaces Node.js entirely
• yt-dlp — download engine
• ffmpeg — audio conversion

Install with Homebrew

brew install yt-dlp ffmpeg

Install Bun

curl -fsSL https://bun.sh/install | bash

Setup

bun install

This installs dependencies for both server and client via Bun workspaces.

Running

bun run dev

This starts both the server (port 3420) and client (port 5420) concurrently. Then open http://localhost:5420.

Troubleshooting Port Conflicts

If you get "port in use" errors, you can either:

1. Clean start (recommended): Kills conflicting ports then starts:

   bun run clean-start

2. Kill ports manually: Kills processes using the ports:

   bun run kill-ports

3. Manual cleanup: Kill specific ports:

   lsof -ti:3420 | xargs kill -9
   lsof -ti:5420 | xargs kill -9

Architecture

Music-Getter/
├── server/                  # Bun + Hono backend
│   ├── index.ts             # Server entry (port 3420)
│   └── routes/
│       ├── inspect.ts       # POST /inspect — run yt-dlp -F on URLs
│       ├── download.ts      # POST /download — stream download progress via SSE
│       └── library.ts       # GET /library, POST /library/reveal
├── client/                  # React + Tailwind frontend (Vite)
│   └── src/
│       ├── App.tsx
│       └── components/
│           ├── UrlInput.tsx       # URL fields + optional proxy input
│           ├── FormatInspector.tsx # Shows yt-dlp -F output + command used
│           ├── DownloadPanel.tsx  # Format selector, download button, live logs
│           └── Library.tsx        # File list with "Show in Finder"
└── downloads/               # Output folder (gitignored)

How it works

• The Vite dev server proxies /api/* requests to the Hono server at localhost:3420, so the frontend and backend run on separate ports without CORS issues in development.
• Format inspection shells out to yt-dlp -F <url> and returns the raw format table so you can see exactly what streams are available before downloading.
• Downloads use Bun.spawn to run yt-dlp and pipe stdout back to the browser in real time via Server-Sent Events. No WebSocket library needed.
• Proxy support — enter a proxy in the optional field (e.g. socks5://127.0.0.1:9050 for Tor, or http://host:port for HTTP proxies). It gets appended to all yt-dlp calls.

Supported formats

Option	What it does
MP3	Extracts best audio stream, converts to MP3 via ffmpeg
WAV	Extracts best audio stream, converts to WAV via ffmpeg
FLAC	Extracts best audio stream, converts to FLAC via ffmpeg
Best Audio	Downloads best audio in original codec (no conversion)
Best Video + Audio	Downloads best combined video + audio stream

Downloaded files land in the downloads/ folder. Use Show in Finder in the Library tab to locate them.

Supported Sources

yt-dlp supports thousands of sites. Common high-quality sources include:

• YouTube - Official music videos, audio uploads
• Archive.org - High-quality archival versions, often better than YouTube
• Vimeo - Professional music videos
• Bandcamp - Artist-direct uploads (when public)
• SoundCloud - Artist uploads (when permitted)

Pro tip: Archive.org often has higher quality versions of music videos than YouTube's compressed versions.