yandex-music-downloader

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

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

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

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

Возможности

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

Требования

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

Установка

Локально:

pip install .

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

yandex-music-downloader --help
yandex-music-downloader-web --help

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

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

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

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

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

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

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

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

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

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

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

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

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

yandex-music-downloader --help

Веб-панель

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

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

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

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

http://127.0.0.1:8000

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

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

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

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

cp .env.example .env

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

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

docker compose up --build -d

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

http://localhost:8228

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

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

Полный набор есть в .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 — не чистить путь от небезопасных символов

Шаблон пути

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

#album-artist/#album/#number-#title

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

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

Пример:

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

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

0

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

1

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

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

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

Спасибо

• Разработчикам проекта yandex-music-api
• @ArtemBay за скрипт получения ссылки на загрузку в lossless качестве
• @keltecc за метод дешифрования файлов
• @leowerd за идею корректных имен исполнителей при загрузке сборников

Дисклеймер

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