Локальный загрузчик Яндекс Музыки

Небольшой локальный веб-интерфейс для поиска музыки, просмотра жанров, новинок и чарта и постановки доступных треков в очередь скачивания. Он слушает только 127.0.0.1 по умолчанию и не передаёт токен сторонним сервисам.

В строку поиска можно вставить полную ссылку на публичный плейлист вида https://music.yandex.ru/users/<login>/playlists/<kind> или https://music.yandex.ru/playlists/<UUID> (включая региональные домены music.yandex.com, .by, .kz, query/fragment и ссылку на трек внутри пользовательского плейлиста). UUID должен иметь строгий формат 8-4-4-4-12 шестнадцатеричных символов. Появится карточка плейлиста; кнопка «Скачать плейлист» добавит все его доступные треки в очередь.

Это неофициальное использование библиотеки yandex-music. Соблюдайте условия Яндекса, авторские права и правила вашей подписки. Пользователь сам отвечает за законность сохранения файлов.

Установка и запуск

Нужен Python 3.11+ (включая Python 3.14).

python -m venv .venv
. .venv/bin/activate             # Windows: .venv\Scripts\activate
pip install -e .
python -m app
# или: uvicorn app.main:app

Откройте http://127.0.0.1:8765. Без токена интерфейс и /api/health доступны, а запросы к музыкальному API вернут понятную ошибку 503.

Docker

Нужны Docker Engine с Docker Compose plugin. Для локального запуска создайте каталоги для постоянных данных и соберите контейнер:

mkdir -p downloads token
docker compose up -d --build

Compose запускает процесс от UID/GID текущего пользователя (по умолчанию 1000:1000), поэтому созданные каталоги остаются доступны ему без chown. Если Docker запускается из окружения, где UID/GID не заданы или отличаются от владельца каталогов, задайте их явно, например: UID=$(id -u) GID=$(id -g) docker compose up -d --build.

Откройте http://127.0.0.1:8765. Остановить приложение: docker compose down; смотреть журналы: docker compose logs -f. Скачанные файлы сохраняются в ./downloads, а токен — в ./token/token; значение токена не передаётся через переменные окружения.

Чтобы включить FLAC при первом запуске контейнера, используйте YMD_REQUIRE_FLAC=1 docker compose up -d (переключатель также можно изменить в интерфейсе). Порт намеренно привязан только к 127.0.0.1: не меняйте binding на 0.0.0.0 без отдельной защиты доступа, так как приложение рассчитано на локальное использование.

Access token

Вставьте личный access token в стартовую форму. Токен не выводится в логах и сохраняется локально с правами 0600; удалить его можно кнопкой «Выйти».

Получение токена зависит от текущей версии и возможностей Яндекс Музыки/yandex-music. Обычно используют уже выданный OAuth/access token своей учётной записи (например, полученный через официальные механизмы Яндекса). Не вводите пароль от Яндекса в это приложение. Некоторые версии библиотеки могут иметь device-auth вспомогательные методы, но это приложение не заявляет и не гарантирует такой поток: используйте только документированный для вашей версии библиотеки и аккаунта способ получения access token.

Настройки окружения

Переменная	По умолчанию	Значение
YMD_HOST	127.0.0.1	адрес bind (не меняйте на публичный без понимания рисков)
YMD_PORT	8765	порт
YMD_DOWNLOAD_DIR	~/Music/Yandex Music	корень загрузок
YMD_TOKEN_FILE	$XDG_CONFIG_HOME/yandex-music-downloader/token или ~/.config/yandex-music-downloader/token	файл токена; при незаданной XDG_CONFIG_HOME используется ~/.config
YMD_REQUIRE_FLAC	не задана	при значении 1 задаёт начальное состояние переключателя FLAC

Пример: YMD_PORT=9000 YMD_DOWNLOAD_DIR=/mnt/music python -m app.

Загрузки и качество

Задачи выполняются в одной фоновой очереди, поэтому HTTP-запрос не ждёт файл. Путь формируется как Исполнитель/Альбом/NN - Название.ext; компоненты очищаются, а совпадающие имена получают суффикс. Кнопка «Очистить очередь» удаляет задачи и отменяет текущую загрузку между сетевыми чанками, не удаляя уже скачанные файлы. На практике часто доступен MP3 320 кбит/с; FLAC не гарантируется. Доступность, прямые ссылки и качество зависят от API, региона и подписки Яндекс Плюс.

Режимы качества

Выберите режим в списке «Качество» перед постановкой треков в очередь; настройка применяется сразу, без перезапуска сервера:

• Лучшее доступное (API v1) — используется только API v1; скачивается лучший доступный вариант.
• FLAC (API v2), иначе API v1 — сначала API v2 (/get-file-info) пытается скачать FLAC. Если FLAC отсутствует или любой этап V2-загрузки, обработки либо сохранения завершается ошибкой, выполняется fallback на API v1 с лучшим доступным вариантом.
• Только FLAC (API v2) — используется только API v2 для FLAC. Если FLAC отсутствует или V2-загрузка, обработка либо сохранение завершается ошибкой, задача завершается ошибкой без fallback на API v1.

Поддерживаемый lossless-поток сохраняется в соответствующем формате: зашифрованный FLAC-в-MP4 расшифровывается AES-CTR и remux'ится в обычный .flac с метаданными и обложкой, а другие поддерживаемые lossless-контейнеры сохраняются с корректным расширением. FLAC не гарантируется: доступность, прямые ссылки и качество зависят от API, региона и подписки Яндекс Плюс.

YMD_REQUIRE_FLAC=1 задаёт начальный режим «FLAC (API v2), иначе API v1»; его можно изменить в интерфейсе в любой момент.

Проверка

pip install -e ".[dev]"
pytest
python -m compileall app