feat: initial implementation of navidrome-music-sync with Yandex, Spotify, Apple, YouTube support and Web UI

README.md

@@ -1,3 +1,56 @@
-# navidrome-music-sync
+# 🎵 Navidrome Music Sync
 
-Multi-source music importer & downloader for Navidrome (Yandex Music, Spotify, Apple Music, YouTube Music)
+Мультисервисный импортер и синхронизатор музыки для **Navidrome**.
+
+Позволяет в один клик или по расписанию импортировать треки, альбомы и плейлисты из **Яндекс Музыки**, **Spotify**, **Apple Music** и **YouTube Music** напрямую в медиатеку Navidrome с сохранением оригинальных тегов, обложек в высоком разрешении и синхронизированных караоке-текстов (`.lrc`).
+
+---
+
+## 🚀 Возможности
+
+- **Прямой импорт из Яндекс Музыки (320 kbps)**:
+  - Скачивание отдельных треков, альбомов и плейлистов.
+  - Полная синхронизация личного плейлиста **«Мне нравится»** (880+ треков).
+- **Импорт из Spotify и Apple Music**:
+  - Без необходимости платных подписок и зарубежных аккаунтов.
+  - Извлечение точных метаданных через официальные открытые каталоги и аудио-матчинг с YouTube Music CDN (Opus 160 / MP3 320k).
+- **Обход цензуры и региональных блокировок**:
+  - Если трек в каталоге РФ заблокирован или зацензурен («запикан»), движок автоматически переключается на глобальные источники и скачивает полноценную **Explicit (18+)** версию.
+- **Интеграция с Navidrome**:
+  - Организация каталога по стандарту: `/music/{Artist}/{Album}/{Track_Number} - {Title}.mp3`.
+  - Автоматическое скачивание построчных караоке-текстов (`.lrc`).
+  - Уведомление Navidrome через Subsonic API (`startScan`) сразу после завершения загрузки.
+- **Веб-интерфейс & REST API**:
+  - Адаптивный темный Web UI с прогресс-баром задач и историей загрузок.
+  - Фоновый асинхронный воркер без блокировки интерфейса.
+  - Дедупликация (не скачивает повторно треки, которые уже есть в библиотеке).
+
+---
+
+## 🛠️ Установка и запуск
+
+### 1. Конфигурация (.env)
+Скопируйте пример конфигурации и укажите токен Яндекс Музыки:
+```bash
+cp .env.example .env
+```
+
+### 2. Запуск через Docker Compose
+```bash
+docker compose up -d --build
+```
+
+Сервис будет доступен по адресу: `http://127.0.0.1:8005` (или через обратный прокси).
+
+---
+
+## 🔌 API Эндпоинты
+
+- `GET /` — Веб-интерфейс управления.
+- `POST /api/download` — Запуск задачи на скачивание по ссылке:
+  ```json
+  { "url": "https://music.yandex.ru/album/123/track/456" }
+  ```
+- `POST /api/sync/yandex-likes` — Запуск полной синхронизации понравившихся треков из Яндекс Музыки.
+- `GET /api/tasks` — Список активных задач и прогресс выполнения.
+- `GET /api/history` — История и статистика загруженной музыки.