mirror of
https://github.com/Horizontal42/Sort_YM.git
synced 2026-11-10 15:42:02 +03:00
116 lines
6.4 KiB
Markdown
116 lines
6.4 KiB
Markdown
# Sort YM
|
||
|
||
Раскладывает лайкнутые треки Яндекс.Музыки по плейлистам вида `Жанр — RU` / `Жанр — INT`.
|
||
|
||
```
|
||
$ python -m sort_ym report
|
||
|
||
Распределение по плейлистам:
|
||
Рок — INT: 143
|
||
Рок — RU: 287
|
||
Рэп — RU: 512
|
||
...
|
||
|
||
Отчёт сохранён: out/report.csv
|
||
```
|
||
|
||
## Установка
|
||
|
||
Требования: Python 3.11+ (используется `tomllib` из стандартной библиотеки), Windows/Linux/macOS, доступ в интернет.
|
||
|
||
```
|
||
python -m venv .venv
|
||
.venv\Scripts\pip install -r requirements.txt
|
||
```
|
||
|
||
Для разработки (тесты):
|
||
|
||
```
|
||
.venv\Scripts\pip install -r requirements-dev.txt
|
||
```
|
||
|
||
## Что делает
|
||
|
||
1. **`auth`** — вход в аккаунт Яндекса через OAuth device-flow: покажет код, вы подтверждаете
|
||
вход на странице Яндекса, токен сохраняется в `.token` (локально, в `.gitignore`).
|
||
2. **`fetch`** — скачивает список лайкнутых треков и их метаданные (жанр альбома, доступность
|
||
текста) в `cache/tracks.json`. Повторный запуск докачивает только новые треки.
|
||
**Ничего не меняет в аккаунте.**
|
||
3. **`report`** — определяет жанр (крупная группа) и язык (RU/иностранный) каждого трека,
|
||
считает распределение по будущим плейлистам и сохраняет `out/report.csv` для проверки.
|
||
**Ничего не меняет в аккаунте.**
|
||
4. **`apply --yes`** — создаёт недостающие плейлисты и добавляет в них треки. Уже добавленные
|
||
треки не дублируются при повторном запуске. Лайки не трогает, ничего не удаляет.
|
||
**Меняет аккаунт** (создаёт плейлисты и добавляет треки).
|
||
|
||
## Полная очистка кэша
|
||
|
||
Если требуется начать с чистого листа (переполучить все данные с нуля), удалите папку `cache/`:
|
||
|
||
```
|
||
Remove-Item -Recurse -Force cache
|
||
```
|
||
|
||
Кэш состоит из трёх файлов:
|
||
- `cache/tracks.json` — список лайкнутых треков и их метаданные;
|
||
- `cache/genre_catalog.json` — снимок дерева жанров Яндекса на момент последнего запуска;
|
||
- `cache/lyrics_lang.json` — определённые языки текстов для каждого трека.
|
||
|
||
Удаление `cache/` заставит `fetch` и `report` переполучить всё с нуля при следующем запуске.
|
||
|
||
Также можно удалить сгенерированный отчёт:
|
||
|
||
```
|
||
Remove-Item -Recurse -Force out
|
||
```
|
||
|
||
Это просто результаты анализа, их удаление не повлияет на следующий запуск `report`.
|
||
|
||
**Важно:** файл `.token` (OAuth-токен) не входит в кэш и не удаляется при очистке `cache/`. Очистка кэша вас не разлогирует. Если нужна повторная авторизация, удалите `.token` отдельно:
|
||
|
||
```
|
||
Remove-Item .token
|
||
```
|
||
|
||
## Как определяется жанр и язык
|
||
|
||
- **Жанр**: у трека берётся жанр альбома, затем он сопоставляется с одной из ~11 крупных
|
||
групп (Поп, Рок, Метал, Рэп, Электроника, Джаз и блюз, Классика, Фолк и world, Инди и
|
||
альтернатива, Саундтреки, Разное) через реальное дерево жанров Яндекса
|
||
(`sort_ym/genres.py`, таблица `ROOT_BUCKET` — легко дополняется).
|
||
- **Язык** — гибрид:
|
||
1. Если у трека есть текст песни — реальный язык из API (`ru` → RU, иначе → INT).
|
||
2. Иначе — подсказка по жанру (`rusrap`, `shanson`, `bard`, ...).
|
||
3. Иначе — по алфавиту названия/исполнителя (кириллица/латиница).
|
||
4. Если ничего не сработало — трек попадает в `... — Не определено`.
|
||
|
||
После `report` в консоли также печатается список нераспознанных жанров (попавших в «Разное»),
|
||
чтобы можно было дополнить таблицу в `sort_ym/genres.py`.
|
||
|
||
## Handy things
|
||
|
||
- Первый прогон `apply` делайте с `--limit 20 --yes` и проверьте результат в приложении, прежде
|
||
чем запускать на все ~2000 треков.
|
||
- Все промежуточные данные лежат в `cache/` — их можно удалить, чтобы пересчитать с нуля.
|
||
- Настройки задержек между запросами — в `config.toml` (`[throttle]`).
|
||
|
||
## Риски (неофициальный API)
|
||
|
||
Официального API для личной библиотеки Яндекс.Музыки нет — инструмент использует
|
||
неофициальную библиотеку `yandex-music`. OAuth-токен в `.token` даёт полный доступ к аккаунту
|
||
Яндекса — храните его локально и не публикуйте. Инструмент выполняет только безопасные действия
|
||
(чтение лайков, создание плейлистов, добавление треков) и ничего не удаляет.
|
||
|
||
## For developers
|
||
|
||
Python 3.11+, `yandex-music==3.0.0`, стандартная библиотека (`tomllib`, `csv`, `unicodedata`).
|
||
|
||
```
|
||
.venv\Scripts\python -m pytest tests/ -v
|
||
.venv\Scripts\python -m sort_ym auth
|
||
.venv\Scripts\python -m sort_ym fetch
|
||
.venv\Scripts\python -m sort_ym report
|
||
.venv\Scripts\python -m sort_ym apply --limit 20 --yes
|
||
```
|
||
|
||
Структура кода и поток данных — в [ARCHITECTURE.md](ARCHITECTURE.md).
|