Metadata-Version: 2.4
Name: ytmusic-cli
Version: 1.1.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: eyed3>=0.9.9
Requires-Dist: musicbrainzngs>=0.7.1
Requires-Dist: mutagen>=1.47.0
Requires-Dist: pytubefix>=10.3.8
Requires-Dist: requests>=2.33.1
Requires-Dist: rich>=14.3.3
Dynamic: license-file

# ytmusic

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

```bash
# Install from PyPI
pip install ytmusic

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

# 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

```bash
# 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
    └── ...
```

## License

[MIT](LICENSE) © 2026

## Releases

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