YandexMusic/FAQ.md

❓ FAQ - Часто задаваемые вопросы

Ответы на самые частые вопросы по использованию YandexMusic.

📋 Содержание

• Общие вопросы
• Установка и настройка
• Использование
• Авторизация
• Ошибки и проблемы
• Производительность
• Разработка

📖 Общие вопросы

Q: Что такое YandexMusic?

A: YandexMusic — это .NET 10 библиотека для работы с неофициальным API Яндекс Музыки. Она позволяет искать музыку, управлять плейлистами, получать информацию об альбомах и исполнителях, а также работать с WebSocket через протокол Ynison.

Q: Это официальная библиотека?

A: Нет, это неофициальная библиотека. Используйте её на свой риск и соблюдайте Terms of Service Яндекс Музыки.

Q: На каких платформах работает?

A: На любых платформах, поддерживающих .NET 10:

• Windows (10/11)
• Linux (Ubuntu, Debian, Red Hat, etc.)
• macOS (Intel & Apple Silicon)

Q: Нужна ли авторизация?

A: Нет, многие операции работают без авторизации (поиск, получение информации о треках). Но для некоторых операций (работа с лайками, плейлистами) требуется авторизация.

Q: Где я могу сообщить об ошибке?

A: Создайте issue на GitHub:

• https://git.frigat.duckdns.org/FrigaT/YandexMusic/issues

🚀 Установка и настройка

Q: Какие требования?

A:

• .NET 10 SDK или выше
• C# 12 совместимый компилятор
• Интернет соединение

Q: Как установить библиотеку?

A: Несколько способов:

1. Через NuGet:

dotnet add package YandexMusic

2. Из GitHub:

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

3. Добавить ссылку на проект:

dotnet add reference ../YandexMusic/YandexMusic.csproj

Q: Как обновить библиотеку?

A: Через NuGet:

dotnet package update YandexMusic

Или если вы клонировали репозиторий:

git pull origin master
dotnet build

Q: Какие зависимости нужны?

A: Только встроенные в .NET 10:

• System.Net.Http
• System.Text.Json
• System.Net.WebSockets

Нет дополнительных NuGet пакетов!

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

Q: Как начать использовать?

A: Самый простой способ:

using YandexMusic;

var client = new YandexMusicClient();
var results = await client.Api.Search.SearchAsync("Beatles");

Подробнее в QUICKSTART.md.

Q: Как получить информацию о треке?

A:

var track = await client.Api.Track.GetTrackAsync("trackId");
Console.WriteLine($"{track?.Title} - {track?.Artists?.FirstOrDefault()?.Title}");

Q: Как найти ID трека/альбома/плейлиста?

A:

• В URL страницы на music.yandex.ru
• Через API при поиске
• На официальном сайте в адресной строке

Примеры:

• Трек: https://music.yandex.ru/album/123/track/456 → ID: 456
• Альбом: https://music.yandex.ru/album/123 → ID: 123
• Плейлист: https://music.yandex.ru/playlist/123 → ID: 123

Q: Почему я получаю null?

A: Несколько причин:

1. Неправильный ID
2. Ресурс был удален
3. Нет доступа (требуется авторизация)
4. Сервер вернул ошибку

Всегда проверяйте результат:

var track = await client.Api.Track.GetTrackAsync(id);
if (track == null)
{
    Console.WriteLine("Трек не найден или нет доступа");
}

Q: Как работать с пагинацией?

A: Используйте параметр page:

var page1 = await client.Api.Search.SearchAsync("query", page: 0);
var page2 = await client.Api.Search.SearchAsync("query", page: 1);

Q: Как получить большое количество данных?

A: Используйте цикл с пагинацией:

var allResults = new List<YTrack>();
int page = 0;

while (true)
{
    var search = await client.Api.Search.SearchAsync("query", page: page);
    if (search?.Tracks?.Results?.Count == 0) break;
    
    allResults.AddRange(search.Tracks.Results ?? []);
    page++;
}

🔐 Авторизация

Q: Как авторизироваться?

A: Два способа:

1. Через логин и пароль:

await client.AuthorizeAsync("email@gmail.com", "password");

2. Через токен:

await client.AuthorizeByTokenAsync("your-oauth-token");

Q: Где получить OAuth токен?

A: Вы можете:

1. Авторизироваться через логин/пароль (библиотека получит токен автоматически)
2. Получить токен через официальное приложение Яндекса
3. Использовать токен из DevTools браузера

Q: Как проверить авторизирован ли я?

A:

if (client.IsAuthorized)
{
    Console.WriteLine($"Авторизирован: {client.Account.User?.DisplayName}");
}
else
{
    Console.WriteLine("Требуется авторизация");
}

Q: Сохраняется ли авторизация?

A: По умолчанию нет. Вы должны авторизироваться при каждом запуске.

Если хотите сохранить токен:

// После авторизации
string token = client.AuthStorage.Token;

// Сохранить в файл, БД и т.д.
// ...

// При следующем запуске
var client = new YandexMusicClient();
await client.AuthorizeByTokenAsync(savedToken);

Q: Безопасно ли хранить пароль?

A: Нет! Никогда не сохраняйте пароль в открытом виде. Лучше:

1. Используйте OAuth токены
2. Сохраняйте токены в безопасном хранилище
3. Используйте переменные окружения

⚠️ Ошибки и проблемы

Q: Получаю HttpRequestException

A: Проблемы с сетью или сервером:

try
{
    var track = await client.Api.Track.GetTrackAsync(id);
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Сетевая ошибка: {ex.Message}");
}

Проверьте:

• Интернет соединение
• Доступность сервера Яндекса
• Firewall/прокси настройки

Q: Получаю JsonException

A: Проблема с десериализацией JSON. Обновите библиотеку или сообщите об issue.

Q: Получаю 401 Unauthorized

A: Проблема с авторизацией:

// Проверьте токен
if (!client.IsAuthorized)
{
    await client.AuthorizeAsync("email", "password");
}

// Или обновите токен
await client.AuthorizeByTokenAsync(newToken);

Q: Получаю 429 Too Many Requests

A: Вы отправляете слишком много запросов. Добавьте задержку:

for (int i = 0; i < ids.Count; i++)
{
    var track = await client.Api.Track.GetTrackAsync(ids[i]);
    if (i < ids.Count - 1) await Task.Delay(100); // 100ms задержка
}

Q: Результаты пусты/null

A: Несколько причин:

1. Неправильный ID:

var track = await client.Api.Track.GetTrackAsync("invalid-id");
// Будет null если ID неверный

2. Нет результатов поиска:

var results = await client.Api.Search.SearchAsync("абракадабра");
// results?.Tracks?.Results будет пусто

3. Требуется авторизация:

var library = await client.Api.Library.GetLibraryAsync();
// Вернёт null если не авторизирован

Q: Почему медленно работает?

A: Несколько причин:

1. Медленное интернет соединение
2. Сервер Яндекса перегружен
3. Получаете большое количество данных
4. Блокирующие операции вместо async

Используйте асинхронные операции:

// ✅ Хорошо
var track = await client.Api.Track.GetTrackAsync(id);

// ❌ Плохо
var track = client.Api.Track.GetTrackAsync(id).Result;

🚀 Производительность

Q: Как оптимизировать производительность?

A: Несколько советов:

1. Используйте пакетные операции:

// ✅ Хорошо - один запрос
var tracks = await client.Api.Track.GetTracksAsync(["id1", "id2", "id3"]);

// ❌ Плохо - три запроса
foreach (var id in ids)
{
    var track = await client.Api.Track.GetTrackAsync(id);
}

2. Кешируйте результаты:

private Dictionary<string, YTrack?> cache = new();

public async Task<YTrack?> GetCached(string id)
{
    if (cache.TryGetValue(id, out var cached)) return cached;
    var track = await client.Api.Track.GetTrackAsync(id);
    cache[id] = track;
    return track;
}

3. Запускайте запросы параллельно:

var (albums, artists) = await (
    Task.Run(() => client.Api.Album.GetAlbumsAsync(ids)),
    Task.Run(() => client.Api.Artist.GetArtistsAsync(ids))
).AsAsync();

4. Добавляйте задержку между запросами:

for (int i = 0; i < 100; i++)
{
    var track = await client.Api.Track.GetTrackAsync(id);
    await Task.Delay(100); // 100ms между запросами
}

Q: Есть ли какие-то лимиты?

A: Яндекс Музыка имеет лимиты:

• Количество запросов в секунду
• Размер результатов поиска
• Размер файлов для загрузки

Уважайте эти лимиты и не создавайте нагрузку на сервер.

🔧 Разработка

Q: Как стать разработчиком?

A: Читайте CONTRIBUTING.md.

Q: Как создать pull request?

A:

1. Форкните репозиторий
2. Создайте ветку: git checkout -b feature/my-feature
3. Сделайте изменения
4. Коммитьте: git commit -m "feat: описание"
5. Пушьте: git push origin feature/my-feature
6. Создайте Pull Request

Q: Как собрать проект?

A:

dotnet build

Q: Как запустить тесты?

A:

dotnet test

Q: Есть ли стиль кода?

A: Да, используется Microsoft C# Coding Conventions. Смотрите CONTRIBUTING.md.

Q: Как добавить новый API метод?

A: Прочитайте ARCHITECTURE.md раздел "Как добавить новый API метод".

Q: Как создать тест?

A: Создайте файл в папке Tests:

using Xunit;
using YandexMusic.API;

public class YTrackAPITests
{
    [Fact]
    public async Task GetTrackAsync_WithValidId_ReturnsTrack()
    {
        // Arrange
        var api = new YandexMusicApi();
        string trackId = "valid-id";

        // Act
        var result = await api.Track.GetTrackAsync(trackId);

        // Assert
        Assert.NotNull(result);
    }
}

🆘 Не нашли ответ?

Создайте вопрос через GitHub Issues: https://git.frigat.duckdns.org/FrigaT/YandexMusic/issues