🎵 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

🚀 Установка

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

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

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

dotnet restore

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

dotnet build

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

dotnet test

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

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

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 (расширенная работа)

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 Классы:

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

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

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

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

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

// С пользовательскими настройками
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: Поиск и получение информации

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: Работа с плейлистами

// Получение плейлиста
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: Работа с альбомами

// Получение альбома
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: Авторизация

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

// Подключение к 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

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 — Документация по низкоуровневому API
• Официальный сайт Яндекс Музыки
• .NET 10 Documentation
• C# 12 Features