readme
This commit is contained in:
446
FAQ.md
Normal file
446
FAQ.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# ❓ 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
|
||||
Reference in New Issue
Block a user