Metadata-Version: 2.4
Name: ytmusic-cli
Version: 1.6.0
Summary: CLI tool to download YouTube playlists as audio with metadata
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2024.12.14
Requires-Dist: mutagen>=1.47.0
Requires-Dist: pytubefix>=10.3.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.33.1
Requires-Dist: rich>=14.3.3
Dynamic: license-file

# ytmusic-cli

[![PyPI Version](https://img.shields.io/pypi/v/ytmusic-cli)](https://pypi.org/project/ytmusic-cli/)
[![License](https://img.shields.io/pypi/l/ytmusic-cli)](LICENSE)

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)

```bash
pip install ytmusic-cli
```

Or with [pipx](https://pypa.github.io/pipx/) (isolated environment):

```bash
pipx install ytmusic-cli
```

### From source

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

### Requirements

- Python 3.10+
- See `pyproject.toml` for dependencies

## Usage

### Basic

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

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

### Common Options

```bash
# 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`:

```bash
# Show config location
ytmusic --config
```

Example config:

```yaml
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](LICENSE) © 2026 Ilyes Hernandez

## Contributing

Pull requests welcome. Please ensure tests pass:

```bash
# Run tests
pytest

# Lint and format
ruff check .
ruff format .
```

## Support

- [GitHub Issues](https://github.com/ilyeshdz/ytmusic/issues) - Bug reports and feature requests
- [PyPI Project](https://pypi.org/project/ytmusic-cli/) - Package information and releases
