Metadata-Version: 2.5
Name: ytmp3-dl
Version: 1.0.0
Summary: Download a YouTube playlist as tagged MP3 files with cover art.
Project-URL: Homepage, https://github.com/arsalan-anwari/ytmp3-dl
Project-URL: Documentation, https://github.com/arsalan-anwari/ytmp3-dl/wiki
Project-URL: Source, https://github.com/arsalan-anwari/ytmp3-dl
Project-URL: Issues, https://github.com/arsalan-anwari/ytmp3-dl/issues
Project-URL: Changelog, https://github.com/arsalan-anwari/ytmp3-dl/blob/main/CHANGELOG.md
Author-email: Arsalan Anwari <arsalan@anwari.nl>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: cover-art,id3,mp3,music,playlist,youtube,yt-dlp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mutagen>=1.47
Requires-Dist: pillow>=10.3
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Requires-Dist: yt-dlp-ejs>=0.8
Requires-Dist: yt-dlp>=2024.8.6
Description-Content-Type: text/markdown

# ytmp3-dl

Download a YouTube playlist as tagged MP3 files, with album art looked up automatically.

- Extracts the best audio stream with [yt-dlp](https://github.com/yt-dlp/yt-dlp), converts it with ffmpeg.
- Parses `Artist - Title` out of messy video titles, preferring YouTube Music metadata.
- Finds real album art on iTunes, Deezer and the Cover Art Archive; falls back to the thumbnail.
- Writes ID3v2.4 tags (title, artist, album, year, genre, track number) and embeds the cover.
- Keeps a download archive, so reruns resume instead of starting over.

## Requirements

- Python 3.10+
- `ffmpeg` on your `PATH`
- A JavaScript runtime on your `PATH`: `deno`, `node`, `bun` or `quickjs` — YouTube hides its
  audio formats behind a JS "n challenge", and without a runtime every download fails.

## Install

```bash
uv tool install ytmp3-dl     # isolated, on your PATH
pipx install ytmp3-dl        # same, via pipx
pip install ytmp3-dl         # into the current environment
uvx ytmp3-dl "<url>"         # no install, one-off run
```

## Usage

```bash
ytmp3 "https://www.youtube.com/playlist?list=PLxxxxxxxx"
```

Files land in `downloads/<Playlist Name>/Artist - Title.mp3`. Use `--dry-run` to see the track
list first, and `ytmp3 --help` for every flag.

```bash
ytmp3 "<url>" --output ~/Music --quality 320 --concurrency 4 --number --save-cover
```

Private or age-gated playlists need cookies:

```bash
ytmp3 "<url>" --cookies-from-browser firefox
```

## Documentation

Full docs live in the [wiki](https://github.com/arsalan-anwari/ytmp3-dl/wiki), and in
[docs/](docs/) in this repo:

| Page | Contents |
| --- | --- |
| [Installation](docs/Installation.md) | Install methods, ffmpeg, JS runtimes. |
| [Usage](docs/Usage.md) | Every flag, with examples. |
| [Cover Art](docs/Cover-Art.md) | How art is found, scored and embedded. |
| [Cookies](docs/Cookies.md) | Getting past "Sign in to confirm you're not a bot". |
| [Troubleshooting](docs/Troubleshooting.md) | Common errors and fixes. |
| [Development](docs/Development.md) | Layout, tests, release process. |

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
```

## Licence and use

Apache-2.0, see [LICENSE](LICENSE). Downloading is subject to YouTube's Terms of Service and to
the rights covering each video. Use it for content you own, content licensed for reuse, or where
you otherwise have permission.
