youtune 1.0.1

The smartest YouTube → MP3 downloader. Auto-tags with MusicBrainz, embeds album art, fetches lyrics, upgrades quality via Soulseek.

🎵 youtune

The smartest YouTube → MP3 downloader

Auto-tags with MusicBrainz · Embeds album art · Fetches lyrics · Upgrades quality via Soulseek · Normalizes loudness · Smart renaming

---

One command. Perfect MP3.

pip install youtune
youtune "https://youtube.com/watch?v=dQw4w9WgXcQ"

  ╭──────────────────────────────────╮
  │  youtune v1.0.0                  │
  │  The smartest YouTube → MP3 downloader │
  ╰──────────────────────────────────╯

  🎵 Rick Astley — Never Gonna Give You Up (confidence: 90%)
  ✅ Metadata found via MusicBrainz
     📀 Album: Whenever You Need Somebody
     📅 Year:  1987
     #️⃣  Track: 1
  📝 Lyrics found (36 lines)
  🖼️  Cover art embedded
  📝 Renamed → Rick Astley - Never Gonna Give You Up.mp3

  ✨ Done!

The problem

yt-dlp -x --audio-format mp3 "https://youtube.com/watch?v=..." gives you:

• ❌ Filename: Rick Astley - Never Gonna Give You Up (Official Music Video) [HD Remaster].mp3
• ❌ No artist, album, year, or track number
• ❌ No album art
• ❌ No lyrics
• ❌ 128kbps YouTube audio, no loudness normalization
• ❌ Messy filenames with junk like "(Official Video)", "[HD]", etc.

youtune fixes all of that — automatically.

Features

	Feature	What it does
🧠	Smart title parsing	Strips "Official Music Video [HD Remaster]" → extracts clean artist + song
🏷️	MusicBrainz tagging	Looks up the real recording → writes ID3v2 tags (artist, album, year, track #, genre)
🖼️	Album art	Fetches cover from Cover Art Archive → embeds in MP3
📝	Lyrics	Fetches synced/plaintext lyrics from lrclib → embeds in file
🔥	Soulseek upgrade	Searches Soulseek for FLAC/320kbps → replaces YouTube download
🔊	Loudness normalization	EBU R128 normalization — no more quiet/blasting tracks
📂	Playlists	Download + tag entire playlists in one shot
✏️	Smart renaming	Rick Astley - Never Gonna Give You Up.mp3 not vevo_aU_official(1).mp3
🔎	Dry-run search	youtune search "Artist - Song" → preview metadata without downloading
🌍	Thousands of sites	Works with any site yt-dlp supports — not just YouTube

Install

pip install youtune

Prerequisites: yt-dlp and ffmpeg must be on your PATH:

# macOS
brew install yt-dlp ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg && pip install yt-dlp

# Windows (winget)
winget install yt-dlp.yt-dlp Gyan.FFmpeg

# Arch
sudo pacman -S yt-dlp ffmpeg

Optional: Soulseek support

pip install youtune[soulseek]

Usage

Download & auto-tag a track

youtune "https://youtube.com/watch?v=dQw4w9WgXcQ"

Download with lyrics + loudness normalization

youtune "https://youtube.com/watch?v=..." --lyrics --normalize

Download a playlist

youtune "https://youtube.com/playlist?list=PL..." -o ~/Music/Playlist

Upgrade quality via Soulseek

youtune "https://youtube.com/watch?v=..." \
  --soulseek \
  --soulseek-user myusername \
  --soulseek-pass mypassword

Downloads from YouTube first, then searches Soulseek for FLAC or 320kbps. If found, replaces the YouTube file.

Preview metadata (no download)

youtune search "Radiohead - Everything In Its Right Place"

Skip everything, just download

youtune "https://youtube.com/watch?v=..." --no-tag --no-art --no-rename

How it works

  YouTube URL
      │
      ▼
  ┌────────────┐
  │  yt-dlp    │  Extract audio → MP3
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │  Parse      │  "Rick Astley - Never Gonna Give You Up (Official Video) [HD]"
  │  title      │  → artist: "Rick Astley", song: "Never Gonna Give You Up"
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │ MusicBrainz │  Lookup recording → album, year, track #, MBIDs
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │ Cover Art   │  Fetch from Cover Art Archive → embed in MP3
  │ Archive     │
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │  lrclib     │  Fetch synced lyrics → embed in MP3
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │  mutagen    │  Write ID3v2 tags + APIC art + USLT lyrics
  └─────┬──────┘
        │
        ▼
  ┌────────────┐
  │  Soulseek   │  (optional) Search for FLAC/320 → replace YouTube file
  └─────┬──────┘
        │
        ▼
  Artist - Title.mp3 ✨
  (clean, tagged, art, lyrics)

All options

usage: youtune download [-h] [-o OUTPUT] [-q QUALITY] [--normalize] [--lyrics]
                        [--no-tag] [--no-art] [--no-rename] [--soulseek]
                        [--soulseek-user USER] [--soulseek-pass PASS]
                        [--prefer-flac] [--min-bitrate N] [--keep-youtube]
                        URL

  -o, --output         Output directory (default: .)
  -q, --quality        Audio quality 0 (best) – 9 (worst)
  --normalize          Apply EBU R128 loudness normalization
  --lyrics             Fetch & embed lyrics
  --no-tag             Skip MusicBrainz tagging
  --no-art             Skip cover art
  --no-rename          Keep original filename

  --soulseek           Search Soulseek for better quality
  --soulseek-user      Soulseek username
  --soulseek-pass      Soulseek password
  --prefer-flac        Prefer FLAC from Soulseek (default: true)
  --min-bitrate        Minimum Soulseek bitrate (default: 256)
  --keep-youtube       Keep YouTube file when Soulseek upgrades

FAQ

Does it work with Spotify / SoundCloud / Bandcamp?

Yes! youtune works with any URL that yt-dlp supports — that's thousands of sites.

What if MusicBrainz doesn't have the track?

youtune falls back to the parsed YouTube title. You'll still get a clean filename and basic ID3 tags from whatever was parsed.

What's the Soulseek upgrade?

YouTube audio is typically 128kbps AAC. Soulseek is a P2P network where people share FLAC and 320kbps MP3s. If you enable --soulseek, youtune will search for and download a higher-quality version to replace the YouTube rip. Requires a free Soulseek account.

Can I use it in scripts / CI?

Yes — exit code 0 on success, non-zero on failure. Use -v for debug logging. No interactive prompts.

Why not just use beets?

beets is great for library management, but it's a heavy setup. youtune is zero-config — one command and you're done. You can pipe youtune output into beets if you want both.

Contributing

Contributions welcome! See CONTRIBUTING.md.

Related projects

• yt-dlp — the download engine that makes this possible
• MusicBrainz — open music encyclopedia
• Cover Art Archive — free cover art API
• lrclib — open-source lyrics database
• mutagen — Python audio metadata library
• beets — the music organizer for obsessives
• slsk-batchdl — Soulseek batch downloader

License

MIT