# ytmdl

A terminal UI for downloading audio from YouTube / YouTube Music video, playlist, and
album URLs, built on [Textual](https://github.com/Textualize/textual) and
[yt-dlp](https://github.com/yt-dlp/yt-dlp).

## Requirements

- Python 3.10+
- [ffmpeg](https://ffmpeg.org/) on your `PATH` (used for audio extraction, thumbnail
  embedding, and metadata tagging)
- A [Nerd Font](https://www.nerdfonts.com/) in your terminal — the folder browser, the
  queue status column, and the command palette all use Nerd Font glyphs; without one
  they'll show as missing-glyph boxes

## Install

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
```

## Run

```bash
.venv/bin/ytmdl
```

Or without installing the entry point:

```bash
.venv/bin/python -m ytmdl
```

Paste a video, playlist, or album URL into the input field and press Enter. Playlists
and albums are expanded into individual tracks, each downloaded and tagged separately,
with up to 2 downloads running concurrently.

The "Saving to:" link below the URL box shows where files are saved. Click it (or press
`Ctrl+O`) to open a folder browser and pick a new destination for any downloads queued
from that point on (in-flight downloads keep going to the old directory).

The "Create a folder per playlist/album" switch (on by default) controls whether tracks
from a playlist or album URL get saved directly into the save directory, or nested in a
subfolder named after the playlist/album title. Single-video URLs are never nested.

### Options

```
ytmdl [-o OUTPUT_DIR] [-f {mp3,m4a,flac,opus,wav,vorbis}]
```

- `-o/--output-dir` — where files are saved (default `~/Music/ytmdl`)
- `-f/--format` — output audio format (default `mp3`)

### Keybindings

- `Enter` — submit the URL in the input box
- `Ctrl+O` — open the folder browser to change the download directory
  - `Backspace` or the `Up` button — go to the parent folder
  - `Esc` — cancel without changing the directory
- `Ctrl+N` — clear finished: remove every completed/errored row from the queue in one go,
  so you can start a fresh batch. Works no matter what has focus. Also available from the
  command palette (`Ctrl+P` → "Clear finished").
- `d` / `Delete` — remove the selected queue entry (not while it's actively downloading;
  select a row first by clicking the table or pressing `Tab` until it's focused)
- `r` — retry a queue entry that errored (same focus requirement as above)
- `q` — quit