pipu-music/docs/genius.md

Genius: поиск метаданных и получение текста

Реализован Go-провайдер services/api/internal/genius и отдельная команда services/api/cmd/genius. Поиск через API возвращает кандидатов, ссылки на изображения и исполнителя. Текст выбранной песни извлекается из HTML страницы: из контейнеров data-lyrics-container либо из songPage.lyricsData.body.html во встроенном состоянии. JavaScript не исполняется. Используется HTML-парсер golang.org/x/net/html.

Это проверяемый первый этап: команда работает отдельно от сервера. Автоматическое дополнение каталога, хранение текстов в БД, аннотации и отображение в плеере пока не подключены. Поэтому переменная ниже пока нужна именно процессу команды, а не Docker Compose или веб-клиенту.

Почему Go

Основной API Pipu написан на Go. Небольшой провайдер можно подключить к нему без отдельного Python-сервиса. LyricsGenius удобен для Python, но собственный адаптер позволяет явно контролировать выбор версии песни, сетевые ограничения и ошибки. HTML Genius не является стабильным API: при изменении разметки парсер потребует обновления.

Получение токена

1. Войти или зарегистрироваться на https://genius.com.
2. Открыть https://genius.com/api-clients и создать новый API Client.
3. Указать название, например Pipu Music, и URL своего приложения. Если форма требует Redirect URI, указать URL под своим контролем; для чтения с Client Access Token OAuth-переходы и обработчик callback в Pipu не нужны.
4. В созданном клиенте нажать Generate Access Token.
5. Сохранить Client Access Token в переменной GENIUS_ACCESS_TOKEN процесса. Client ID и Client Secret вместо него не подходят.

Токен нужен для поиска через api.genius.com. Получение HTML по уже известному URL не требует токена и не отправляет заголовок Authorization. Не помещать токен в git, клиентские переменные VITE_*, логи или переписку.

Источник: https://lyricsgenius.readthedocs.io/en/master/setup.html.

Проверка в PowerShell 7

Из корня репозитория:

Set-Location services/api
$env:GENIUS_ACCESS_TOKEN = Read-Host 'Genius Client Access Token' -MaskInput
go run ./cmd/genius -search 'Исполнитель Название песни'

Выбрать нужного исполнителя и версию песни из результатов. Команда намеренно не считает первый результат правильным. Затем подставить возвращённый url:

go run ./cmd/genius -url 'https://genius.com/Artist-song-lyrics'
Remove-Item Env:GENIUS_ACCESS_TOKEN

URL во втором примере — шаблон. Результат — JSON с text, source_url и временем получения fetched_at. Это обычный текст без временной синхронизации.

Ограничения и дальнейшее подключение

• HTTP 401, 403, 404, 429 и другие ошибки возвращаются явно; HTTPError сохраняет Retry-After. Автоматических повторов и обхода блокировок нет.
• Таймаут запроса — 15 секунд, предел ответа — 8 MiB. Разрешён только HTTPS на Genius; перенаправления на другой хост запрещены.
• Отсутствие распознаваемого текста возвращает ErrLyricsUnavailable; HTML блокировки или навигация не становятся текстом песни.
• Перед интеграцией в каталог нужны кэш результатов, лимит частоты запросов, сохранение выбранного Genius ID и обработка временных ошибок без потери старого текста.
• Токен API не предоставляет лицензию на тексты. Документация LyricsGenius предупреждает, что парсинг противоречит условиям Genius; отображление и хранение в публичном сервисе требуют отдельной проверки разрешений: https://lyricsgenius.readthedocs.io/en/latest/how_it_works.html.

Тесты

go test ./internal/genius ./cmd/genius

Тесты используют синтетические тексты и подмену HTTP: переносы, HTML-сущности, служебные элементы, встроенное состояние, ошибки HTTP, проверка URL и отсутствие токена при запросе страницы. Реальный доступ к Genius проверяется отдельно из сети сервера с собственным токеном.