ytmusic-cli 1.5.0

CLI tool to download YouTube playlists as audio with metadata

ytmusic-cli

CLI tool to download YouTube playlists as audio with metadata.

A command-line tool that downloads YouTube playlists as audio files, automatically identifies songs using the iTunes API, and embeds rich metadata (artist, album, cover art) directly into the audio files.

Background

This tool was created to solve the problem of downloading music from YouTube playlists while maintaining proper metadata. Many existing tools download videos or audio without proper tagging, resulting in a disorganized music library. This tool:

• Automatically identifies songs using the iTunes API
• Downloads only audio streams (no video)
• Embeds cover art and metadata directly into audio files
• Names files consistently as "Artist - Song Title"
• Skips songs with poor metadata matches

Install

# Install from PyPI
pip install ytmusic-cli

# Or with pipx (recommended for CLI tools)
pipx install ytmusic-cli

# Or install from source with uv
uv sync

Dependencies

• Python 3.10+
• pytubefix (YouTube downloading)
• mutagen (audio metadata)
• rich (CLI output)
• requests (API calls)

See pyproject.toml for full dependency list.

Usage

# Run via the installed CLI
ytmusic "PLAYLIST_URL"

# Or module execution
python -m ytmusic "PLAYLIST_URL"

CLI

usage: ytmusic [-h] [-o DIR] [-t 0.0-1.0] [--dry-run] [--version] url

Download YouTube playlists as audio with rich metadata

positional arguments:
  url                   YouTube playlist URL or ID

options:
  -h, --help            show this help message and exit
  -o DIR, --output DIR  Output directory (default: music_library)
  -t 0.0-1.0, --threshold 0.0-1.0
                        Similarity threshold 0.0-1.0 (default: 0.5)
  --dry-run             Preview what would be downloaded
  --version             show program's version number and exit

Examples:
  # Basic usage
  ytmusic "https://www.youtube.com/playlist?list=PLAYLIST_ID"
  
  # Custom output with stricter matching
  ytmusic "PLAYLIST_URL" -o "my_music" -t 0.7
  
  # Preview without downloading
  ytmusic "PLAYLIST_URL" --dry-run

How It Works

1. Playlist Fetching - Retrieves all video URLs from the playlist
2. Title Parsing - Extracts "Artist - Song" from YouTube titles
3. Metadata Search - Queries iTunes API for matching songs
4. Similarity Check - Compares YouTube title with iTunes result
5. Download - Gets audio-only stream (skips if similarity < threshold)
6. Tagging - Embeds metadata and cover art into audio file
7. Naming - Saves as "Artist - Song Title.m4a"

Configuration

Similarity Threshold

The threshold controls how strictly songs must match metadata:

Threshold	Result
0.3	Lenient - More songs, less accurate
0.5	Balanced - (default)
0.7	Strict - Fewer songs, more accurate
0.9	Very strict - Only exact matches

Output Organization

music_library/
└── Playlist Name/
    ├── Artist - Song Title.m4a
    ├── Artist - Song Title.m4a
    └── ...

Configuration File

Create a config file at ~/.config/ytmusic/config.yaml to set default options:

# Generate default config file
ytmusic --init-config

Example Config

# ytmusic-cli configuration
output: "my_music"
threshold: 0.7
format: "mp3"
bitrate: "320k"
convert: true
quiet: false
verbose: false
summary: true
workers: 4

Config Precedence

1. CLI arguments (highest priority)
2. Config file values
3. Built-in defaults (lowest priority)

Environment Variable

Set a custom config path:

export YTMUSIC_CONFIG=/path/to/my/config.yaml
ytmusic "PLAYLIST_URL"

License

MIT © 2026

Releases

Prebuilt executables are available on GitHub Releases (Linux/macOS/Windows).