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

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

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