# 🎵 YandexMusic - Complete Solution

Полнофункциональное решение для работы с неофициальным API Яндекс Музыки на базе .NET 10. Содержит библиотеку API, оборачиватель клиента и CLI приложение.

## 📋 Содержание

- [Описание](#описание)
- [Структура решения](#структура-решения)
- [Требования](#требования)
- [Установка](#установка)
- [Быстрый старт](#быстрый-старт)
- [Проекты](#проекты)
- [Примеры использования](#примеры-использования)
- [Архитектура](#архитектура)
- [Лицензия](#лицензия)

## 📖 Описание

**YandexMusic** — это комплексное решение для взаимодействия с API Яндекс Музыки на платформе .NET 10. Решение состоит из двух ключевых компонентов:

1. **YandexMusic.API** — низкоуровневая библиотека для прямого взаимодействия с API
2. **YandexMusic** — удобный оборачиватель (wrapper) с клиентом `YandexMusicClient`

### 🎯 Основные возможности

- ✅ **Полная асинхронная архитектура** — Async/await на всех уровнях
- ✅ **Типобезопасный код** — Nullable reference types, full type safety
- ✅ **Модульная структура** — Легко расширяемые компоненты
- ✅ **Современный стек** — .NET 10, C# 12, System.Text.Json
- ✅ **Полная документация на русском** — XML docs для всех публичных членов
- ✅ **WebSocket поддержка** — Протокол Ynison для real-time синхронизации
- ✅ **Гибкая конфигурация** — Поддержка прокси, cookies, custom headers
- ✅ **Отладка встроена** — Debug settings для логирования и анализа

## 🏗️ Структура решения

```
YandexMusic/
├── YandexMusic.API/              # Низкоуровневая библиотека API
│   ├── API/                      # Классы для разных веток API
│   ├── Models/                   # Модели данных
│   ├── Requests/                 # Построители запросов
│   ├── Common/                   # Вспомогательные компоненты
│   ├── Extensions/               # Методы расширения
│   ├── YandexMusicApi.cs         # Главный класс API
│   ├── YandexMusic.API.csproj
│   └── README.md                 # Документация по API
│
├── YandexMusic/                  # Оборачиватель и клиент
│   ├── YandexMusicClient.cs      # Основной класс клиента
│   ├── YandexMusic.csproj
│   └── YandexMusicClient.cs      # Реализация клиента
│
└── README.md                     # Этот файл
```

### Зависимости между проектами

```
YandexMusic (Client wrapper)
    ↓
YandexMusic.API (Core library)
```

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

- **.NET 10** или выше
- **C# 12** или выше
- **Visual Studio 2026** (рекомендуется) или Visual Studio Code

### Системные требования

- Windows 10/11, Linux, macOS (любая ОС с .NET 10)
- Минимум 512 MB RAM
- Интернет соединение для работы с API

## 🚀 Установка

### Клонирование репозитория

```bash
git clone https://git.frigat.duckdns.org/FrigaT/YandexMusic.git
cd YandexMusic
```

### Восстановление зависимостей

```bash
dotnet restore
```

### Сборка решения

```bash
dotnet build
```

### Запуск тестов (если есть)

```bash
dotnet test
```

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

### 1. Как клиент (рекомендуется для большинства случаев)

```csharp
using YandexMusic;

// Создание клиента
var client = new YandexMusicClient();

// Получение информации о треке
var track = await client.Api.Track.GetTrackAsync("trackId123");
Console.WriteLine($"Трек: {track?.Title}");

// Поиск музыки
var results = await client.Api.Search.SearchAsync("Ленинград");
Console.WriteLine($"Найдено результатов: {results?.Tracks?.Results?.Count}");

// Работа с плейлистами
var playlists = await client.Api.Playlist.GetPlaylistAsync("playlistId");
Console.WriteLine($"Плейлист: {playlists?.Title}");
```

### 2. Низкоуровневой API (расширенная работа)

```csharp
using YandexMusic.API;

// Создание API
var api = new YandexMusicApi();

// Прямая работа с API
var track = await api.Track.GetTrackAsync("trackId");
```

## 📚 Проекты

### YandexMusic.API

Низкоуровневая библиотека, предоставляющая полный доступ к API Яндекс Музыки.

**Основные компоненты:**

- `YandexMusicApi` — главный класс, содержит все API классы
- `AuthStorage` — управление авторизацией и cookies
- `IRequestProvider` — интерфейс для обработки HTTP запросов
- `YCommonAPI` — базовый класс для всех API веток

**API Классы:**

```csharp
public class YandexMusicApi
{
    public YAlbumAPI Album { get; }           // Альбомы
    public YArtistAPI Artist { get; }         // Исполнители
    public YLabelAPI Label { get; }           // Лейблы
    public YLandingAPI Landing { get; }       // Рекомендации
    public YLibraryAPI Library { get; }       // Библиотека
    public YPlaylistAPI Playlist { get; }     // Плейлисты
    public YPinsAPI Pins { get; }             // Закреплённые
    public YRadioAPI Radio { get; }           // Радио
    public YSearchAPI Search { get; }         // Поиск
    public YTrackAPI Track { get; }           // Треки
    public YQueueAPI Queue { get; }           // Очередь
    public YUserAPI User { get; }             // Пользователь
    public YUgcAPI UserGeneratedContent { get; } // UGC
    public YYnisonAPI Ynison { get; }         // WebSocket
}
```

**Особенности:**

- 300+ моделей данных для полного покрытия API
- Асинхронные методы для всех операций
- Поддержка WebSocket (Ynison)
- Встроенная обработка ошибок
- System.Text.Json для сериализации

**Документация:** [YandexMusic.API/README.md](YandexMusic.API/README.md)

### YandexMusic

Удобный оборачиватель (wrapper) над низкоуровневой библиотекой с клиентом `YandexMusicClient`.

**Основной класс:**

```csharp
public class YandexMusicClient : IDisposable
{
    // Свойства
    public AuthStorage AuthStorage { get; }
    public YAccount Account { get; }
    public bool IsAuthorized { get; }
    public YnisonPlayer? Ynison { get; }
    public HttpClient HttpClient { get; }
    public YandexMusicApi Api { get; }
    
    // Методы авторизации
    public Task AuthorizeAsync(string login, string password);
    public Task AuthorizeByTokenAsync(string token);
}
```

**Возможности:**

- Интеграция с собственным HttpClient
- Управление cookies и прокси
- Встроенная авторизация
- WebSocket плеер Ynison
- Удобное API через свойство `Api`

**Использование:**

```csharp
// С пользовательскими настройками
var client = new YandexMusicClient(
    cookieContainer: new CookieContainer(),
    proxy: new WebProxy("http://proxy:8080"),
    timeout: TimeSpan.FromSeconds(30),
    userAgent: "Custom Agent"
);

// Авторизация
await client.AuthorizeAsync("login@gmail.com", "password");

// Использование
var playlists = await client.Api.Playlist.GetPlaylistAsync("123");
```

## 💡 Примеры использования

### Пример 1: Поиск и получение информации

```csharp
using YandexMusic;

var client = new YandexMusicClient();

// Поиск треков
var search = await client.Api.Search.SearchAsync("The Beatles");
var track = search?.Tracks?.Results?.FirstOrDefault();

if (track != null)
{
    Console.WriteLine($"🎵 {track.Title}");
    Console.WriteLine($"👤 {string.Join(", ", track.Artists?.Select(a => a.Title) ?? [])}");
    Console.WriteLine($"⏱️ {track.DurationMs / 1000} сек");
}
```

### Пример 2: Работа с плейлистами

```csharp
// Получение плейлиста
var playlist = await client.Api.Playlist.GetPlaylistAsync("playlistId");
Console.WriteLine($"Плейлист: {playlist?.Title}");
Console.WriteLine($"Треков: {playlist?.Tracks?.Count}");

// Вывод треков
foreach (var track in playlist?.Tracks ?? [])
{
    Console.WriteLine($"  - {track.Title}");
}
```

### Пример 3: Работа с альбомами

```csharp
// Получение альбома
var album = await client.Api.Album.GetAlbumAsync("albumId");

Console.WriteLine($"Альбом: {album?.Title}");
Console.WriteLine($"Исполнитель: {album?.Artists?.FirstOrDefault()?.Title}");
Console.WriteLine($"Год: {album?.Year}");
Console.WriteLine($"Жанр: {album?.Genre}");

// Вывод треков в альбоме
foreach (var track in album?.Tracks ?? [])
{
    Console.WriteLine($"  {track.Position}. {track.Title}");
}
```

### Пример 4: Авторизация

```csharp
var client = new YandexMusicClient();

try
{
    // Авторизация через логин и пароль
    await client.AuthorizeAsync("your-email@gmail.com", "your-password");
    
    Console.WriteLine($"✅ Авторизирован: {client.Account.User?.DisplayName}");
}
catch (Exception ex)
{
    Console.WriteLine($"❌ Ошибка авторизации: {ex.Message}");
}
```

### Пример 5: WebSocket Ynison

```csharp
// Подключение к Ynison (если авторизирован)
var player = client.Ynison;

if (player != null)
{
    await player.ConnectAsync();
    Console.WriteLine("✅ Подключено к Ynison");
    
    // Использование плеера...
    
    await player.DisconnectAsync();
}
```

## 🏛️ Архитектура

### Слои

```
┌─────────────────────────────────────┐
│   YandexMusic (Client Wrapper)      │  ← Удобный клиент
├─────────────────────────────────────┤
│   YandexMusic.API (Core Library)    │  ← Низкоуровневой API
├─────────────────────────────────────┤
│   HttpClient, System.Text.Json      │  ← .NET Framework
└─────────────────────────────────────┘
```

### Ключевые компоненты YandexMusic.API

```
YandexMusicApi (Main Entry Point)
    ├── API Classes (YAlbumAPI, YTrackAPI, etc.)
    │   └── Requests (YGetAlbumBuilder, YSearchBuilder, etc.)
    │
    ├── Models (YAlbum, YTrack, YPlaylist, etc.)
    │   └── Common Models (YBaseModel, YResponse, etc.)
    │
    ├── AuthStorage (Authorization Management)
    │   └── IRequestProvider (HTTP Request Handling)
    │       ├── DefaultRequestProvider
    │       ├── CommonRequestProvider
    │       └── MockRequestProvider
    │
    └── Extensions & Utilities
        ├── HttpRequestHeaderExtensions
        ├── StringExtensions
        ├── Encryptor (для шифрования)
        └── DataDownloader
```

### Обработка запросов

```
Request Builder (YRequestBuilder<T>)
    ↓
HttpRequestMessage
    ↓
IRequestProvider.GetWebResponseAsync()
    ↓
HttpResponseMessage
    ↓
System.Text.Json Deserialization
    ↓
Model<T>
```

## 🔧 Конфигурация

### Настройка HttpClient

```csharp
var client = new YandexMusicClient(
    cookieContainer: new CookieContainer(),
    proxy: new WebProxy("http://127.0.0.1:8080"),
    timeout: TimeSpan.FromSeconds(30),
    userAgent: "MyCustomAgent/1.0"
);
```

## 📊 Статистика проекта

| Метрика | Значение |
|---------|----------|
| Проектов | 3 |
| Целевая платформа | .NET 10 |
| Язык C# | 12 |
| Основных API методов | 50+ |
| Моделей данных | 300+ |
| Документированных членов | 100% |
| Асинхронных методов | 100% |

## 🔐 Безопасность

- ✅ Использование HTTPS для всех запросов
- ✅ Поддержка прокси для безопасности
- ✅ Встроенное шифрование для чувствительных данных
- ✅ Управление cookies и сессиями
- ✅ Валидация всех входных данных

**⚠️ Важно:** Это неофициальная библиотека. Используйте её на свой риск и соблюдайте Terms of Service Яндекс Музыки.

## 🚦 Статус проекта

- ✅ **Стабильный** — Основная функциональность работает
- 🔄 **Активная разработка** — Регулярные обновления
- 📝 **Документирован** — Полная документация на русском

## 📝 Лицензия

Это неофициальная библиотека для работы с API Яндекс Музыки. 

**Дисклеймер:** Автор не несет ответственности за неправомерное использование данной библиотеки. Используйте её в соответствии с Terms of Service Яндекс Музыки.

## 👨‍💻 Автор

**FrigaT** - Разработчик

## 🤝 Поддержка

Для вопросов, багов и предложений:
- 🐛 Issues: [https://git.frigat.duckdns.org/FrigaT/YandexMusic/issues]
- 💬 Discussions: [https://git.frigat.duckdns.org/FrigaT/YandexMusic/discussions]

## 📚 Дополнительная информация

- [YandexMusic.API/README.md](YandexMusic.API/README.md) — Документация по низкоуровневому API
- [Официальный сайт Яндекс Музыки](https://music.yandex.ru)
- [.NET 10 Documentation](https://learn.microsoft.com/dotnet/)
- [C# 12 Features](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-12)