ytmusic-cli 1.6.0

CLI tool to download YouTube playlists as audio with metadata

ytmusic-cli

CLI tool to download YouTube playlists as audio with rich metadata.

ytmusic-cli downloads YouTube playlists as properly tagged audio files. It automatically identifies songs using the iTunes API, strips promotional noise from YouTube titles, deduplicates repeat versions, and embeds cover art and metadata directly into your music library.

Features

• Smart title parsing - Extracts clean artist and song names from messy YouTube titles
• Automatic deduplication - Keeps the best version when the same song appears multiple times (studio > live > acoustic > remix)
• iTunes metadata - Fetches official album art, artist, and album information
• Configurable matching - Adjust similarity threshold to balance accuracy vs. coverage
• Persistent configuration - Set default options in a config file
• Smart caching - SQLite-based cache speeds up repeat downloads
• Clean output - Files named as "Artist - Song Title.m4a" with embedded metadata

Installation

From PyPI (recommended)

pip install ytmusic-cli

Or with pipx (isolated environment):

pipx install ytmusic-cli

From source

git clone https://github.com/ilyeshdz/ytmusic.git
cd ytmusic
pip install -e .

Requirements

• Python 3.10+
• See pyproject.toml for dependencies

Usage

Basic

# Download a playlist
ytmusic "https://www.youtube.com/playlist?list=PLAYLIST_ID"

# Or just the playlist ID
ytmusic "PL..."

Common Options

# Custom output directory
ytmusic "PLAYLIST_URL" -o ~/Music

# Stricter metadata matching (0.0-1.0, default: 0.5)
ytmusic "PLAYLIST_URL" -t 0.7

# Preview what would be downloaded (no actual download)
ytmusic "PLAYLIST_URL" --dry-run

# Skip existing files (sync mode)
ytmusic "PLAYLIST_URL" --sync

# Quiet mode (errors only)
ytmusic "PLAYLIST_URL" -q

Configuration File

Set persistent defaults at ~/.config/ytmusic/config.yaml:

# Show config location
ytmusic --config

Example config:

download:
  path: "~/Music"           # Output directory
  sync: false               # Skip existing files
  quiet: false              # Only show errors

metadata:
  threshold: 0.5            # Similarity threshold 0.0-1.0

Config precedence: CLI args > Config file > Built-in defaults

How It Works

1. Playlist Fetch - Retrieves all video URLs from the playlist
2. Pre-scan - Analyzes titles and detects duplicates before downloading
3. Title Parse - Cleans promotional noise and extracts artist/song
4. Metadata Search - Queries iTunes API with smart retry and caching
5. Similarity Check - Compares titles; skips if below threshold
6. Download - Gets highest-quality audio-only stream
7. Tag & Save - Embeds metadata and cover art, saves as "Artist - Song.m4a"

Output Organization

music_library/
└── Playlist Name/
    ├── Artist A - Song One.m4a
    ├── Artist B - Song Two.m4a
    └── ...

All files include embedded cover art and metadata (artist, album, year, genre when available).

Similarity Threshold Guide

Threshold	Result
0.3	Lenient - More songs, less accurate matches
0.5	Balanced (default) - Good mix of coverage and accuracy
0.7	Strict - Fewer songs, more reliable matches
0.9	Very strict - Only near-exact matches

License

MIT © 2026 Ilyes Hernandez

Contributing

Pull requests welcome. Please ensure tests pass:

# Run tests
pytest

# Lint and format
ruff check .
ruff format .

Support

• GitHub Issues - Bug reports and feature requests
• PyPI Project - Package information and releases