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:**
```bash
dotnet add package YandexMusic
```

2. **Из GitHub:**
```bash
git clone https://git.frigat.duckdns.org/FrigaT/YandexMusic.git
cd YandexMusic
dotnet build
```

3. **Добавить ссылку на проект:**
```bash
dotnet add reference ../YandexMusic/YandexMusic.csproj
```

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

**A:** Через NuGet:
```bash
dotnet package update YandexMusic
```

Или если вы клонировали репозиторий:
```bash
git pull origin master
dotnet build
```

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

**A:** Только встроенные в .NET 10:
- System.Net.Http
- System.Text.Json
- System.Net.WebSockets

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

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

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

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

```csharp
using YandexMusic;

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

Подробнее в [QUICKSTART.md](QUICKSTART.md).

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

**A:** 
```csharp
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. Сервер вернул ошибку

Всегда проверяйте результат:
```csharp
var track = await client.Api.Track.GetTrackAsync(id);
if (track == null)
{
    Console.WriteLine("Трек не найден или нет доступа");
}
```

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

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

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

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

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

```csharp
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. **Через логин и пароль:**
```csharp
await client.AuthorizeAsync("email@gmail.com", "password");
```

2. **Через токен:**
```csharp
await client.AuthorizeByTokenAsync("your-oauth-token");
```

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

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

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

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

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

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

Если хотите сохранить токен:
```csharp
// После авторизации
string token = client.AuthStorage.Token;

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

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

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

**A:** **Нет!** Никогда не сохраняйте пароль в открытом виде. Лучше:
1. Используйте OAuth токены
2. Сохраняйте токены в безопасном хранилище
3. Используйте переменные окружения

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

### Q: Получаю `HttpRequestException`

**A:** Проблемы с сетью или сервером:
```csharp
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:** Проблема с авторизацией:
```csharp
// Проверьте токен
if (!client.IsAuthorized)
{
    await client.AuthorizeAsync("email", "password");
}

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

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

**A:** Вы отправляете слишком много запросов. Добавьте задержку:
```csharp
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:**
```csharp
var track = await client.Api.Track.GetTrackAsync("invalid-id");
// Будет null если ID неверный
```

2. **Нет результатов поиска:**
```csharp
var results = await client.Api.Search.SearchAsync("абракадабра");
// results?.Tracks?.Results будет пусто
```

3. **Требуется авторизация:**
```csharp
var library = await client.Api.Library.GetLibraryAsync();
// Вернёт null если не авторизирован
```

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

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

Используйте асинхронные операции:
```csharp
// ✅ Хорошо
var track = await client.Api.Track.GetTrackAsync(id);

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

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

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

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

1. **Используйте пакетные операции:**
```csharp
// ✅ Хорошо - один запрос
var tracks = await client.Api.Track.GetTracksAsync(["id1", "id2", "id3"]);

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

2. **Кешируйте результаты:**
```csharp
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. **Запускайте запросы параллельно:**
```csharp
var (albums, artists) = await (
    Task.Run(() => client.Api.Album.GetAlbumsAsync(ids)),
    Task.Run(() => client.Api.Artist.GetArtistsAsync(ids))
).AsAsync();
```

4. **Добавляйте задержку между запросами:**
```csharp
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](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:**
```bash
dotnet build
```

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

**A:**
```bash
dotnet test
```

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

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

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

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

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

**A:** Создайте файл в папке Tests:
```csharp
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