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!
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.
| 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 |
pip install youtunePrerequisites: 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 ffmpegpip install youtune[soulseek]youtune "https://youtube.com/watch?v=dQw4w9WgXcQ"youtune "https://youtube.com/watch?v=..." --lyrics --normalizeyoutune "https://youtube.com/playlist?list=PL..." -o ~/Music/Playlistyoutune "https://youtube.com/watch?v=..." \
--soulseek \
--soulseek-user myusername \
--soulseek-pass mypasswordDownloads from YouTube first, then searches Soulseek for FLAC or 320kbps. If found, replaces the YouTube file.
youtune search "Radiohead - Everything In Its Right Place"youtune "https://youtube.com/watch?v=..." --no-tag --no-art --no-rename 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)
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
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.
Contributions welcome! See CONTRIBUTING.md.
- 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