From 81fce4a335e35781d55c1a99c427b6b912f62834 Mon Sep 17 00:00:00 2001 From: Yuriy Panov Date: Mon, 19 Oct 2026 12:04:50 +0600 Subject: [PATCH] Fall back to LRCLIB for lyrics Yandex doesn't have When Yandex answers "no lyrics" for a track, the lyrics tab now asks LRCLIB (lrclib.net), an open lyrics database that needs no key. The exact match by title, artist, album and length comes first; when that is plain text, or missing, search picks a synced copy of the same recording (within 3 s of its length). Speech and instrumentals get none. - LRCLIB's /get answers 503 "ServerOverloaded" now and then: busy answers are retried twice, briefly, and a busy /get falls through to search. - LRCLIB errors never map to Unauthorized, so they can't sign the user out of Yandex. - Lyrics from LRCLIB carry a "Lyrics from LRCLIB" credit at the end of the list, and the empty state no longer blames Yandex alone. Co-Authored-By: Claude Opus 5.5 --- README.md | 3 +- .../main/java/it/panov/musyx/tv/api/Lrclib.kt | 128 ++++++++++++++++++ .../main/java/it/panov/musyx/tv/api/Lyrics.kt | 18 ++- .../java/it/panov/musyx/tv/state/AppState.kt | 5 +- .../it/panov/musyx/tv/ui/screens/Player.kt | 11 ++ app/src/main/res/values-ru/strings.xml | 3 +- app/src/main/res/values/strings.xml | 3 +- .../java/it/panov/musyx/tv/api/ApiTest.kt | 80 +++++++++++ 8 files changed, 241 insertions(+), 10 deletions(-) create mode 100644 app/src/main/java/it/panov/musyx/tv/api/Lrclib.kt diff --git a/README.md b/README.md index 914798c..41444bc 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ your phone (or a pasted token), Home (My Wave, recently played, personal playlis chart, new releases, genres), My Wave with its mood, character and language settings and other stations, search with suggestions and paged results, Collection (liked tracks, albums, artists, playlists, clips), album, artist, playlist, genre and podcast pages, and a -Now Playing screen with the queue and synced lyrics. Tracks can be liked, disliked, queued +Now Playing screen with the queue and synced lyrics (from [LRCLIB](https://lrclib.net) when +Yandex has none). Tracks can be liked, disliked, queued next or last, added to playlists, and used to start similar tracks; your own playlists can be created, renamed, made public or private, reordered and deleted. Playback runs in a media session, so it keeps going in the background and answers the remote's media keys. While diff --git a/app/src/main/java/it/panov/musyx/tv/api/Lrclib.kt b/app/src/main/java/it/panov/musyx/tv/api/Lrclib.kt new file mode 100644 index 0000000..2650648 --- /dev/null +++ b/app/src/main/java/it/panov/musyx/tv/api/Lrclib.kt @@ -0,0 +1,128 @@ +// LRCLIB (lrclib.net): an open lyrics database, asked when Yandex has no lyrics for a track. +// No key; it asks clients to name themselves in the User-Agent. +package it.panov.musyx.tv.api + +import it.panov.musyx.tv.BuildConfig +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.delay +import kotlinx.coroutines.withContext +import kotlinx.serialization.json.JsonElement +import okhttp3.HttpUrl.Companion.toHttpUrl +import okhttp3.Request +import java.io.IOException +import kotlin.math.abs +import kotlin.math.roundToLong + +private const val LRCLIB_BASE = "https://lrclib.net/api" +private val LRCLIB_AGENT = "Musyx-TV/${BuildConfig.VERSION_NAME} (https://git.panov.it/panov/musyz-mobile)" + +object Lrclib { + /** How far a search result's length may be from the track's and still be the same recording. */ + internal const val DURATION_SLACK_S = 3.0 + + /** + * Lyrics for `track`: the exact match by title, artist, album and length first, then the + * closest search result. Null for speech, instrumentals and tracks LRCLIB doesn't know. + */ + suspend fun lyrics(track: Track): Lyrics? { + if (track.spoken) return null + val artist = track.artists.firstOrNull()?.name ?: return null + val seconds = (track.durationMs / 1000.0).takeIf { it > 0 } + if (seconds != null) { + val exact = try { + get( + "/get", + Params().add("track_name", track.title).add("artist_name", artist) + .add("album_name", track.album?.title?.takeIf { it.isNotBlank() }) + .add("duration", seconds.roundToLong()), + ) + } catch (e: YmError) { + // `/get` answers 503 "ServerOverloaded" now and then; search still works then. + if (e is YmError.NotFound || e.isRetryable) null else throw e + } + if (exact != null) { + val l = fromRecord(exact) + // The exact match is often a plain-text copy of a recording that has a synced one. + if (l == null || l.synced) return l + val found = try { + get("/search", Params().add("track_name", track.title).add("artist_name", artist)) + } catch (e: YmError) { + return l + } + return better(l, pick(found.arr.orEmpty(), seconds)?.let(::fromRecord)) + } + } + val found = get("/search", Params().add("track_name", track.title).add("artist_name", artist)) + return pick(found.arr.orEmpty(), seconds)?.let(::fromRecord) + } + + /** The exact match's plain lyrics, unless search found the same recording synced. */ + internal fun better(exact: Lyrics, searched: Lyrics?): Lyrics = if (searched?.synced == true) searched else exact + + /** A record's lyrics, synced when it has them; null for instrumentals and empty records. */ + internal fun fromRecord(r: JsonElement): Lyrics? { + if (r.bool("instrumental") == true) return null + r.str("syncedLyrics")?.takeIf { it.isNotBlank() }?.let { lrc -> + Lyrics.fromLrc(lrc, emptyList(), LyricsSource.Lrclib).takeIf { it.lines.isNotEmpty() }?.let { return it } + } + return r.str("plainLyrics")?.takeIf { it.isNotBlank() } + ?.let { Lyrics.fromText(it.trim(), emptyList(), LyricsSource.Lrclib) } + } + + /** + * The search result for a track `seconds` long: lengths within the slack only (any length + * when it's unknown), synced over plain, then the closest. An instrumental closest match + * means there are no lyrics, not that a further one should stand in. + */ + internal fun pick(results: List, seconds: Double?): JsonElement? { + fun off(r: JsonElement): Double { + val d = r.double("duration") ?: return Double.MAX_VALUE + return if (seconds == null) 0.0 else abs(d - seconds) + } + val near = results.filter { off(it) <= DURATION_SLACK_S }.sortedBy(::off) + if (near.firstOrNull()?.bool("instrumental") == true) return null + val withLyrics = near.filter { fromRecord(it) != null } + return withLyrics.firstOrNull { !it.str("syncedLyrics").isNullOrBlank() } ?: withLyrics.firstOrNull() + } + + /** A GET, tried again twice when LRCLIB says it's busy (429, 503), as its error asks. */ + private suspend fun get(path: String, params: Params): JsonElement { + val url = (LRCLIB_BASE + path).toHttpUrl().newBuilder().apply { + params.pairs.forEach { (k, v) -> addQueryParameter(k, v) } + }.build() + val request = Request.Builder().url(url).header("User-Agent", LRCLIB_AGENT).get().build() + var attempt = 0 + while (true) { + val (status, retryAfter, body) = withContext(Dispatchers.IO) { + try { + Http.api.newCall(request).execute().use { r -> Triple(r.code, r.header("Retry-After"), r.body.string()) } + } catch (e: IOException) { + throw YmError.Network(e.message ?: e.javaClass.simpleName) + } + } + if (status in 200..299) return parseJson(body) + if ((status == 429 || status == 503) && attempt < 2) { + delay(retryDelayMs(retryAfter, attempt)) + attempt += 1 + continue + } + throw lrclibError(status, path) + } + } + + /** `Retry-After` seconds when given, else 1 s then 2 s; never more than 3 s on a TV that's waiting. */ + internal fun retryDelayMs(retryAfter: String?, attempt: Int): Long { + val asked = retryAfter?.trim()?.toLongOrNull()?.let { it * 1000 } + return (asked ?: (1000L shl attempt)).coerceIn(0, 3000) + } + + /** Never `Unauthorized`: that signs the user out of Yandex, and LRCLIB has no accounts. */ + internal fun lrclibError(status: Int, path: String): YmError { + val message = "lrclib $path: http $status" + return when { + status == 404 -> YmError.NotFound(message) + status == 429 || status >= 500 -> YmError.Network(message) + else -> YmError.Api(message) + } + } +} diff --git a/app/src/main/java/it/panov/musyx/tv/api/Lyrics.kt b/app/src/main/java/it/panov/musyx/tv/api/Lyrics.kt index f563e6e..0c484a1 100644 --- a/app/src/main/java/it/panov/musyx/tv/api/Lyrics.kt +++ b/app/src/main/java/it/panov/musyx/tv/api/Lyrics.kt @@ -4,7 +4,15 @@ package it.panov.musyx.tv.api /** One line of lyrics; synced lyrics carry the moment it's sung. */ data class LyricLine(val atMs: Long?, val text: String) -data class Lyrics(val lines: List, val synced: Boolean, val writers: List) { +/** Where lyrics came from; anything but Yandex is credited under them. */ +enum class LyricsSource { Yandex, Lrclib } + +data class Lyrics( + val lines: List, + val synced: Boolean, + val writers: List, + val source: LyricsSource = LyricsSource.Yandex, +) { /** The line being sung at `positionMs`: the last line that has started. */ fun current(positionMs: Long): Int? { if (!synced) return null @@ -13,11 +21,11 @@ data class Lyrics(val lines: List, val synced: Boolean, val writers: companion object { /** Plain text: one line per line, blank lines kept as paragraph breaks. */ - fun fromText(text: String, writers: List) = - Lyrics(text.lines().map { LyricLine(null, it.trimEnd()) }, synced = false, writers = writers) + fun fromText(text: String, writers: List, source: LyricsSource = LyricsSource.Yandex) = + Lyrics(text.lines().map { LyricLine(null, it.trimEnd()) }, synced = false, writers = writers, source = source) /** LRC: `[mm:ss.xx] words`. Lines with several stamps repeat; metadata tags are dropped. */ - fun fromLrc(lrc: String, writers: List): Lyrics { + fun fromLrc(lrc: String, writers: List, source: LyricsSource = LyricsSource.Yandex): Lyrics { val lines = mutableListOf() for (raw in lrc.lines()) { var rest = raw.trim() @@ -37,7 +45,7 @@ data class Lyrics(val lines: List, val synced: Boolean, val writers: } for (at in stamps) lines += LyricLine(at, rest) } - return Lyrics(lines.sortedBy { it.atMs }, synced = true, writers = writers) + return Lyrics(lines.sortedBy { it.atMs }, synced = true, writers = writers, source = source) } /** `mm:ss`, `mm:ss.x`, `mm:ss.xx` or `mm:ss.xxx`. */ diff --git a/app/src/main/java/it/panov/musyx/tv/state/AppState.kt b/app/src/main/java/it/panov/musyx/tv/state/AppState.kt index c56e68e..326a0de 100644 --- a/app/src/main/java/it/panov/musyx/tv/state/AppState.kt +++ b/app/src/main/java/it/panov/musyx/tv/state/AppState.kt @@ -23,6 +23,7 @@ import it.panov.musyx.tv.api.Genre import it.panov.musyx.tv.api.Home import it.panov.musyx.tv.api.LibraryPlaylists import it.panov.musyx.tv.api.LikedIds +import it.panov.musyx.tv.api.Lrclib import it.panov.musyx.tv.api.Lyrics import it.panov.musyx.tv.api.MY_WAVE import it.panov.musyx.tv.api.PlaylistId @@ -541,11 +542,11 @@ class AppState( // ---- Lyrics ---- - /** Lyrics for `track`, fetched once while the lyrics tab shows it. */ + /** Lyrics for `track`, fetched once while the lyrics tab shows it: Yandex's, else LRCLIB's. */ fun wantLyrics(track: Track) { if (lyrics.containsKey(track.id)) return lyrics[track.id] = Loadable.Loading - load({ it.lyrics(track.id) }) { lyrics[track.id] = it } + load({ it.lyrics(track.id) ?: Lrclib.lyrics(track) }) { lyrics[track.id] = it } } fun retryLyrics(track: Track) { diff --git a/app/src/main/java/it/panov/musyx/tv/ui/screens/Player.kt b/app/src/main/java/it/panov/musyx/tv/ui/screens/Player.kt index f5f3453..d526ce9 100644 --- a/app/src/main/java/it/panov/musyx/tv/ui/screens/Player.kt +++ b/app/src/main/java/it/panov/musyx/tv/ui/screens/Player.kt @@ -71,6 +71,7 @@ import androidx.tv.material3.Text import it.panov.musyx.tv.MainActivity import it.panov.musyx.tv.R import it.panov.musyx.tv.api.Lyrics +import it.panov.musyx.tv.api.LyricsSource import it.panov.musyx.tv.api.Track import it.panov.musyx.tv.player.Notice import it.panov.musyx.tv.player.PlaybackState @@ -526,6 +527,16 @@ private fun LyricsList(state: AppState, lyrics: Lyrics) { ) } } + if (lyrics.source == LyricsSource.Lrclib) { + item(key = "source") { + Text( + stringResource(R.string.lyrics_source_lrclib), + style = MusyxTheme.type.small, + color = c.muted, + modifier = Modifier.padding(10.dp), + ) + } + } } } diff --git a/app/src/main/res/values-ru/strings.xml b/app/src/main/res/values-ru/strings.xml index 0ed4c12..d7b8c4a 100644 --- a/app/src/main/res/values-ru/strings.xml +++ b/app/src/main/res/values-ru/strings.xml @@ -208,10 +208,11 @@ Далее · %1$d Очередь пока пуста. Здесь появятся треки, которые вы включите, и те, что за ними. Включите трек, чтобы увидеть его текст. - У Яндекс Музыки нет текста этого трека. + Текст этого трека не найден. Не удалось загрузить текст. Проверьте подключение и попробуйте ещё раз. Загружаем текст… Авторы: %1$s + Текст из LRCLIB Не удалось загрузить продолжение станции. Проверьте подключение и попробуйте ещё раз. Несколько треков подряд не удалось воспроизвести. Проверьте подключение и попробуйте ещё раз. Не удалось воспроизвести «%1$s», трек пропущен. diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml index d8b91fd..8040661 100644 --- a/app/src/main/res/values/strings.xml +++ b/app/src/main/res/values/strings.xml @@ -222,10 +222,11 @@ Next up · %1$d Nothing queued yet. Tracks you play, and the ones lined up after them, show up here. Play a track to see its lyrics. - Yandex Music has no lyrics for this track. + No lyrics found for this track. Couldn\'t load the lyrics. Check your connection and try again. Loading lyrics… Written by %1$s + Lyrics from LRCLIB Couldn\'t load more of this station. Check your connection and try again. Several tracks in a row couldn\'t be played. Check your connection and try again. Couldn\'t play “%1$s”, so it was skipped. diff --git a/app/src/test/java/it/panov/musyx/tv/api/ApiTest.kt b/app/src/test/java/it/panov/musyx/tv/api/ApiTest.kt index 0ca525e..c14d798 100644 --- a/app/src/test/java/it/panov/musyx/tv/api/ApiTest.kt +++ b/app/src/test/java/it/panov/musyx/tv/api/ApiTest.kt @@ -367,6 +367,86 @@ class ApiTest { assertNull(Lyrics.parseStamp("00:01.1234")) } + // ---- LRCLIB ---- + + private fun record(duration: Double, synced: String? = null, plain: String? = null, instrumental: Boolean = false) = + json( + buildString { + append("""{"duration":$duration,"instrumental":$instrumental""") + append(""","syncedLyrics":${synced?.let { JsonPrimitive(it) } ?: "null"}""") + append(""","plainLyrics":${plain?.let { JsonPrimitive(it) } ?: "null"}}""") + }, + ) + + @Test + fun lrclibRecordPrefersSyncedAndIsCredited() { + val l = Lrclib.fromRecord(record(280.0, synced = "[00:01.00]Тёплое место", plain = "Тёплое место"))!! + assertTrue(l.synced) + assertEquals(LyricsSource.Lrclib, l.source) + assertEquals(listOf(1_000L to "Тёплое место"), l.lines.map { it.atMs!! to it.text }) + + val plain = Lrclib.fromRecord(record(280.0, plain = "a\nb\n"))!! + assertFalse(plain.synced) + assertEquals(listOf("a", "b"), plain.lines.map { it.text }) + assertEquals(LyricsSource.Lrclib, plain.source) + } + + @Test + fun lrclibInstrumentalsAndEmptyRecordsHaveNoLyrics() { + assertNull(Lrclib.fromRecord(record(200.0, plain = "la", instrumental = true))) + assertNull(Lrclib.fromRecord(record(200.0))) + assertNull(Lrclib.fromRecord(record(200.0, synced = "[ar:Someone]", plain = " "))) + // Synced text with no stamped lines falls back to the plain text. + assertFalse(Lrclib.fromRecord(record(200.0, synced = "[ar:Someone]", plain = "words"))!!.synced) + } + + @Test + fun lrclibPicksTheSameRecordingSyncedFirst() { + val live = record(246.0, synced = "[00:01.00]live") + val plainNear = record(280.0, plain = "studio") + val syncedNear = record(282.5, synced = "[00:01.00]studio") + val results = listOf(live, plainNear, syncedNear) + assertEquals(syncedNear, Lrclib.pick(results, 280.0)) + // Nothing within the slack: a different recording's words are worse than none. + assertNull(Lrclib.pick(listOf(live), 280.0)) + // Length unknown: any record with lyrics will do, synced first. + assertEquals(live, Lrclib.pick(listOf(plainNear, live), null)) + } + + @Test + fun lrclibClosestInstrumentalMeansNoLyrics() { + val results = listOf(record(281.0, synced = "[00:01.00]cover"), record(280.0, instrumental = true)) + assertNull(Lrclib.pick(results, 280.0)) + } + + @Test + fun lrclibSyncedSearchResultBeatsAPlainExactMatch() { + val plain = Lrclib.fromRecord(record(173.0, plain = "words"))!! + val synced = Lrclib.fromRecord(record(172.0, synced = "[00:01.00]words"))!! + assertEquals(synced, Lrclib.better(plain, synced)) + assertEquals(plain, Lrclib.better(plain, Lrclib.fromRecord(record(172.0, plain = "other")))) + assertEquals(plain, Lrclib.better(plain, null)) + } + + @Test + fun lrclibBusyRetriesWaitBriefly() { + assertEquals(1000L, Lrclib.retryDelayMs(null, 0)) + assertEquals(2000L, Lrclib.retryDelayMs(null, 1)) + assertEquals(2000L, Lrclib.retryDelayMs(" 2 ", 0)) + assertEquals(3000L, Lrclib.retryDelayMs("120", 0)) + // An HTTP date isn't worth parsing for a few seconds' wait. + assertEquals(1000L, Lrclib.retryDelayMs("Wed, 21 Oct 2026 07:28:00 GMT", 0)) + } + + @Test + fun lrclibErrorsNeverSignTheUserOut() { + assertTrue(Lrclib.lrclibError(404, "/get") is YmError.NotFound) + assertTrue(Lrclib.lrclibError(403, "/get") is YmError.Api) + assertTrue(Lrclib.lrclibError(401, "/get") is YmError.Api) + assertTrue(Lrclib.lrclibError(429, "/get").isRetryable) + assertTrue(Lrclib.lrclibError(503, "/get").isRetryable) + } + // ---- Auth, errors, signing ---- @Test