youtube-music-dl 4.0.0

Download and label albums and playlists from YouTube using yt-dlp

youtube-music-dl

youtube-music-dl makes it super easy to download and label music from YouTube. It handles single songs, playlists, and single-song albums (it splits them by chapters).

It tags them (title, artist, album, track number) so they're correctly grouped and ordered in whatever music player you use, cleans up the song titles, and gives files clean names. Output is Opus by default (excellent quality at small sizes, and copied straight from YouTube's stream without re-encoding when possible) or mp3.

It's a wrapper around the amazing yt-dlp, built to be as simple as possible to use from the command line, in a script, or by an AI agent. It prints a single JSON object describing what it did.

# Download this Pharoah Sanders album from a single vid, split it by chapters, and label each song; youtube-music-dl guesses at the album name from the video metadata
youtube-music-dl SDeuYY3Hi_I -a "Pharoah Sanders" --album Pharoah

# Download "Nilsson Schmilsson" from a single vid, split it by its chapters, and label each song
youtube-music-dl <id> -a "Harry Nilsson" --album "Nilsson Schmilsson"

# Download and label tracks 1-10 of this playlist by "Star Band de Dakar"
youtube-music-dl "https://www.youtube.com/watch?v=...&index=1&list=..." -a "Star Band de Dakar" -p "1-10"

# Download this Lucinda Williams album from a list of single-song URLs/IDs
youtube-music-dl <id_1> <id_2> <id_3> ... -a "Lucinda Williams" --album "Sweet Old World"

Installation

pip install youtube-music-dl

Deps

youtube-music-dl needs a few system binaries (used by yt-dlp):

• FFmpeg and ffprobe to convert and split audio
  • macOS: brew install ffmpeg
  • Ubuntu: sudo apt install ffmpeg
• A JavaScript runtime: modern YouTube requires one for extraction; Deno is recommended (Node also works)
  • macOS: brew install deno
  • Ubuntu: see Deno install docs

If a required binary is missing, youtube-music-dl tells you (with an error.code of NO_FFMPEG or NO_JS_RUNTIME) instead of failing cryptically.

It's worth noting that yt-dlp occasionally "breaks", for example because YouTube changes something that prevents it from properly downloading videos. In these cases fixes appear quickly. If youtube-music-dl suddenly stops working, try running pip install --upgrade "yt-dlp[default]" to upgrade yt-dlp.

What it does that plain yt-dlp doesn't

yt-dlp can extract audio, embed metadata, and split by chapters on its own. youtube-music-dl is a focused convenience layer on top of it that adds:

• Custom-timestamp splitting. Split a single "full album" video at boundaries you supply in a JSON/CSV --chapters-file. Useful when the tracklist is only in the description and there are no real YouTube chapters. yt-dlp can only split by chapters that already exist.
• Albums from a list of single-song URLs, tagged with a shared album and sequential track numbers, in one command.
• Opinionated one-liner defaults: makes an artist/album folder, cleans song titles (strips the artist/album out), tags everything, and gives files clean, ordered names.
• Automatic mode detection: you don't tell it whether the URL is a playlist, a chaptered video, or single songs, it figures it out. It also auto-splits a single video that does have chapters, with no extra flag. When driven with an agent, it can download albums that don't have chapters, as long as the description has track names and durations, or if these are supplied by the user.
• Agent-friendly output: one JSON object on stdout, a stable error/exit-code contract, idempotent re-runs, and a skill that teaches agents how to run common workflows.

Usage

youtube-music-dl downloads tagged tracks into an <artist>/<album>/ folder, created inside your current directory (or the -o path), so you can browse your music by artist on disk. Run youtube-music-dl -h for the full help.

It prints one JSON object to stdout (logs go to stderr), so youtube-music-dl … 2>/dev/null | jq gives you clean JSON. Re-runs are idempotent. Tracks already present (matched by an embedded youtube_video_id tag) are skipped. Exit code is 0 on success, 2 if some tracks failed, 1 on a fatal error.

Required Arguments

• url: URL or ID of a YouTube playlist, a video with chapters, or one or more single-song URLs
• -a/--artist ARTIST

Optional Arguments

• --album: required for single-song URLs; otherwise defaults to the playlist/video title
• -p, --playlist-items: playlist items to download; e.g. "1,3-5,7-9,11,12"
• -t, --track-numbers: track numbers to assign; must be the same length as the items
• -s, --strip-patterns : extra regex patterns to remove from titles
• --no-strip-meta: don't strip the artist/album out of titles
• -f, --audio-format: {opus,mp3}; default opus; Opus is copied from YouTube's stream without re-encoding when possible; mp3 is for maximum device compatibility
• -q, --audio-quality: a bitrate like 160K, or 0–9 VBR for mp3; Omit for opus to avoid re-encoding (recommended)
• --chapters-file: JSON or CSV file of chapters used to split a single video at custom timestamps; see these examples (JSON files are validated against the chapters_file schema — run youtube-music-dl --print-schema)
• -o, --output-path: directory in which the album directory is created; Precedence: this flag (even -o .) → the YMD_OUTPUT_DIR env var → the current directory
• --force: re-download tracks even if they're already present
• --probe: print what a real run would do (mode, chapters, description) as JSON, without downloading — useful for deciding whether an album video needs a --chapters-file
• --print-schema / --print-skill: print the JSON Schemas / the agent skill and exit

File names and tags

Tracks land at <artist>/<album>/NN - Title.ext (e.g. Harry Nilsson/Nilsson Schmilsson/01 - Gotta Get Up.opus), named cleanly and in order. The artist/album is stripped out of both the title tag (what your player shows) and the filename. The source video is not lost: it's stored in a youtube_video_id tag on each file (yt-dlp also embeds the source URL), which is how re-runs know what's already been downloaded.

Fixing a wrong artist/album (retag)

Got the artist or album wrong? Fix it without re-downloading:

youtube-music-dl retag "<album directory>" -a "Charly García"
# or --album "New Name", or both

retag points at an existing <album> directory, rewrites the artist/album tags on its .opus/.mp3 files, and moves the <artist>/<album> folder to match, leaving titles, track numbers, and provenance untouched. It refuses with INVALID_ARGS if the directory has no audio files, or if the destination already exists (you probably already have the corrected album there). Anything more involved than this is a job for a real library manager like beets.

Env vars

• YMD_OUTPUT_DIR: default output directory
  • E.g. set export YMD_OUTPUT_DIR="$HOME/Music"

Use with AI agents

Because the CLI is non-interactive and emits schema-stable JSON, an agent can drive it directly. E.g. "download this album by this artist to ~/Music", a YouTube URL, or a CSV of albums to fetch one by one. This repo ships a skill that teaches an agent the workflows, the output schema, and the error codes. To use this skill with an agent, copy or symlink it into your agent's skills directory.

The CLI is self-describing, so an agent needs no filesystem paths: --print-skill prints the skill, --print-schema prints the JSON Schemas, and --probe <url> reports the detected mode (playlist / chaptered video / single song) and the video description without downloading — which is how an agent decides whether a "full album" video needs a generated --chapters-file.

Contributing

Fork the repo and submit a PR. Create an issue if something is broken!

Development

This project uses uv for packaging and development. Run uv sync to set things up:

uv sync

By default this creates a virtual environment at .venv in the repo root (the standard location uv uses) and installs all dependencies into it, including dev tools (ruff, pyright). pyrightconfig.json points pyright at this .venv, so type checking can resolve yt-dlp, mutagen, and the other deps without any extra configuration.

uv sync installs the project as an editable install in .venv, so running it through uv run always reflects your latest code — no reinstall step:

uv run youtube-music-dl ...

Note that python -m youtube_music_dl.command_line ... works too. Run other tools the same way with uv run, e.g. uv run pyright, or activate the environment with source .venv/bin/activate.

Run cd .git/hooks && ln -s -f ../../pre-push to add the pre-push hook to ensure you can't push anything that doesn't pass ruff, pyright and pytest.

Style

Uses ruff for formatting, linting, and import sorting.

• uv run ruff format . to format source files in place
• uv run ruff check . to lint (add --fix to auto-fix)
• uv run pyright to type-check
• uv run pytest to run the tests

To install the pre-push hook, run cd .git/hooks && ln -s -f ../../pre-push.

Release/Deploy to PyPI

uv build
uv publish

Install locally

To put a youtube-music-dl command on your PATH that tracks the repo — so it always picks up later code edits — install it editable:

uv tool install --editable .

Plain uv tool install . snapshots the current code instead, so you'd have to re-run uv tool install . --reinstall after every edit. Also, remember that you can skip install and simply do uv run youtube-music-dl ..., which always reflects the latest code.

License

This code is licensed under the MIT License.

Thanks

To the maintainers of yt-dlp, Mutagen and FFmpeg, and to anyone who doesn't want all that sweet music to go behind ads or a paywall.