438 lines
15 KiB
Markdown
438 lines
15 KiB
Markdown
# 🎵 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)
|