# yandex-music-downloader

Загрузчик музыки из Яндекс Музыки с двумя интерфейсами:

- `CLI` для точечных и пакетных загрузок
- `Web UI` на FastAPI для загрузки, экспорта дискографии и работы с лайками

Проект поддерживает загрузку в AAC и FLAC, сохранение тегов, обложек и текстов, а также запуск через Docker.

> В `v3` изменился способ авторизации и часть аргументов. Если обновляетесь со старой версии, смотрите [MIGRATION.md](MIGRATION.md).

## Возможности

- Скачать все треки артиста, альбом, плейлист или отдельный трек
- Загружать в качестве `AAC 64`, `AAC 192` или `FLAC`
- Встраивать обложку в файл
- Сохранять тексты песен в формате `text` или `lrc`
- Настраивать путь сохранения через шаблон
- Пропускать уже скачанные треки
- Отдельно настраивать совместимость тегов
- Работать через веб-панель без ручного ввода токена
- Смотреть лайки в веб-панели
- Скачивать из веб-панели:
  - все понравившиеся треки
  - альбомы артистов из лайков
  - дискографию артиста в JSON

## Требования

- Python `3.9+`
- Токен Яндекс Музыки

## Установка

Локально:

```bash
pip install .
```

После установки доступны две команды:

```bash
yandex-music-downloader --help
yandex-music-downloader-web --help
```

## Получение токена

Инструкция по получению токена:

https://yandex-music.readthedocs.io/en/main/token.html

## Быстрый старт CLI

Скачать все треки артиста в FLAC:

```bash
yandex-music-downloader \
  --token "<TOKEN>" \
  --quality 2 \
  --url "https://music.yandex.ru/artist/208167"
```

Скачать альбом и сохранить тексты в `LRC`:

```bash
yandex-music-downloader \
  --token "<TOKEN>" \
  --quality 1 \
  --lyrics-format lrc \
  --url "https://music.yandex.ru/album/294912"
```

Скачать плейлист в свою папку:

```bash
yandex-music-downloader \
  --token "<TOKEN>" \
  --playlist-id "user/playlists/123" \
  --dir "./downloads" \
  --skip-existing
```

Скачать один трек:

```bash
yandex-music-downloader \
  --token "<TOKEN>" \
  --url "https://music.yandex.ru/album/11644078/track/6705392"
```

## Основные аргументы CLI

- `--url` или один из `--artist-id`, `--album-id`, `--track-id`, `--playlist-id`
- `--token` для авторизации
- `--quality 0|1|2`
- `--lyrics-format none|text|lrc`
- `--embed-cover`
- `--cover-resolution 400|800|original`
- `--skip-existing`
- `--dir`
- `--path-pattern`
- `--unsafe-path`
- `--stick-to-artist`
- `--only-music`
- `--timeout`
- `--tries`
- `--retry-delay`

Полный список:

```bash
yandex-music-downloader --help
```

## Веб-панель

Веб-панель использует токен только из переменной окружения `YMD_TOKEN`. В интерфейсе поле токена отсутствует.

Локальный запуск:

```bash
export YMD_TOKEN="<TOKEN>"
yandex-music-downloader-web --host 127.0.0.1 --port 8000
```

После запуска откройте:

```text
http://127.0.0.1:8000
```

Что умеет веб-панель:

- загрузка по ссылке, `artist_id`, `album_id`, `track_id`, `playlist_id`
- экспорт дискографии артиста в JSON
- просмотр лайкнутых треков
- отдельный список артистов из лайков
- кнопка `Скачать всё понравившееся`
- кнопка `Скачать альбомы артистов`
- отображение активных задач и прогресса

## Запуск через Docker

1. Создайте `.env` из шаблона:

```bash
cp .env.example .env
```

2. Укажите токен и при необходимости остальные параметры.

3. Запустите контейнер:

```bash
docker compose up --build -d
```

4. Откройте веб-панель:

```text
http://localhost:8228
```

Загрузка по умолчанию сохраняется в локальную папку `./downloads`.

## Переменные окружения для Web UI / Docker

Полный набор есть в [.env.example](.env.example). Основные переменные:

- `YMD_TOKEN` — токен Яндекс Музыки
- `YMD_DOWNLOAD_DIR` — корневая папка загрузки
- `YMD_PATH_PATTERN` — шаблон пути
- `YMD_QUALITY` — качество по умолчанию (`0`, `1`, `2`)
- `YMD_LYRICS_FORMAT` — `none`, `text`, `lrc`
- `YMD_COVER_RESOLUTION` — размер обложки
- `YMD_COMPATIBILITY_LEVEL` — уровень совместимости тегов
- `YMD_SKIP_EXISTING` — пропускать существующие файлы
- `YMD_EMBED_COVER` — встраивать обложку
- `YMD_STICK_TO_ARTIST` — брать только альбомы самого артиста
- `YMD_ONLY_MUSIC` — исключать подкасты и аудиокниги
- `YMD_TIMEOUT` — таймаут запросов
- `YMD_TRIES` — число повторов
- `YMD_RETRY_DELAY` — пауза между повторами
- `YMD_DELAY` — задержка между треками
- `YMD_UNSAFE_PATH` — не чистить путь от небезопасных символов

## Шаблон пути

По умолчанию используется:

```text
#album-artist/#album/#number-#title
```

Поддерживаемые заполнители:

- `#number`
- `#number-padded`
- `#track-artist`
- `#album-artist`
- `#title`
- `#album`
- `#year`
- `#artist-id`
- `#album-id`
- `#track-id`

Пример:

```text
#album-artist/#album/#number-padded-#title
```

## Уровни совместимости тегов

### `0`

Стандартное поведение `mutagen`.

### `1`

Для `m4a` многозначные поля (`©ART`, `aART`) записываются через `;`, что лучше работает в части плееров.

## Изменения в текущей версии

- Добавлен Web UI на FastAPI
- Добавлен Docker-образ и `docker compose`
- Токен для веб-панели переведен только в `YMD_TOKEN`
- Добавлен просмотр лайков
- Добавлены действия `Скачать всё понравившееся` и `Скачать альбомы артистов`
- Улучшена логика построения путей и переименования по тегам

## Спасибо

- Разработчикам проекта [yandex-music-api](https://github.com/MarshalX/yandex-music-api)
- @ArtemBay за [скрипт](https://github.com/MarshalX/yandex-music-api/issues/656#issuecomment-2306542725) получения ссылки на загрузку в lossless качестве
- @keltecc за [метод дешифрования файлов](https://github.com/llistochek/yandex-music-downloader/issues/112#issuecomment-2812535100)
- @leowerd за [идею корректных имен исполнителей](https://github.com/llistochek/yandex-music-downloader/issues/93#issuecomment-2960210879) при загрузке сборников

## Дисклеймер

Проект не связан с Яндексом и является независимой разработкой.