mrleo1nidandCursor
73ad61e7a5
Search hits omit album covers and artist images. The worker now reads the full song and artist, stores the description, and leaves Genius image URLs unchanged on mobile. Co-authored-by: Cursor <cursoragent@cursor.com>
5.9 KiB
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: при изменении разметки парсер потребует обновления.
Получение токена
- Войти или зарегистрироваться на https://genius.com.
- Открыть https://genius.com/api-clients и создать новый API Client.
- Указать название, например
Pipu Music, и URL своего приложения. Если форма требует Redirect URI, указать URL под своим контролем; для чтения с Client Access Token OAuth-переходы и обработчик callback в Pipu не нужны. - В созданном клиенте нажать Generate Access Token.
- Сохранить 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 проверяется отдельно из сети сервера с собственным токеном.