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 <noreply@anthropic.com>
This commit is contained in:
yuriy.pandClaude Opus 5.5 committed 2026-10-19 12:04:50 +06:00
1 parent 39aed49b88
commit 81fce4a335
8 files changed
+241 -10

No files matched your search

+2 -1
View File
@@ -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 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, other stations, search with suggestions and paged results, Collection (liked tracks,
albums, artists, playlists, clips), album, artist, playlist, genre and podcast pages, and a 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 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 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 session, so it keeps going in the background and answers the remote's media keys. While
@@ -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<JsonElement>, 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)
}
}
}
@@ -4,7 +4,15 @@ package it.panov.musyx.tv.api
/** One line of lyrics; synced lyrics carry the moment it's sung. */ /** One line of lyrics; synced lyrics carry the moment it's sung. */
data class LyricLine(val atMs: Long?, val text: String) data class LyricLine(val atMs: Long?, val text: String)
data class Lyrics(val lines: List<LyricLine>, val synced: Boolean, val writers: List<String>) { /** Where lyrics came from; anything but Yandex is credited under them. */
enum class LyricsSource { Yandex, Lrclib }
data class Lyrics(
val lines: List<LyricLine>,
val synced: Boolean,
val writers: List<String>,
val source: LyricsSource = LyricsSource.Yandex,
) {
/** The line being sung at `positionMs`: the last line that has started. */ /** The line being sung at `positionMs`: the last line that has started. */
fun current(positionMs: Long): Int? { fun current(positionMs: Long): Int? {
if (!synced) return null if (!synced) return null
@@ -13,11 +21,11 @@ data class Lyrics(val lines: List<LyricLine>, val synced: Boolean, val writers:
companion object { companion object {
/** Plain text: one line per line, blank lines kept as paragraph breaks. */ /** Plain text: one line per line, blank lines kept as paragraph breaks. */
fun fromText(text: String, writers: List<String>) = fun fromText(text: String, writers: List<String>, source: LyricsSource = LyricsSource.Yandex) =
Lyrics(text.lines().map { LyricLine(null, it.trimEnd()) }, synced = false, writers = writers) 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. */ /** LRC: `[mm:ss.xx] words`. Lines with several stamps repeat; metadata tags are dropped. */
fun fromLrc(lrc: String, writers: List<String>): Lyrics { fun fromLrc(lrc: String, writers: List<String>, source: LyricsSource = LyricsSource.Yandex): Lyrics {
val lines = mutableListOf<LyricLine>() val lines = mutableListOf<LyricLine>()
for (raw in lrc.lines()) { for (raw in lrc.lines()) {
var rest = raw.trim() var rest = raw.trim()
@@ -37,7 +45,7 @@ data class Lyrics(val lines: List<LyricLine>, val synced: Boolean, val writers:
} }
for (at in stamps) lines += LyricLine(at, rest) 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`. */ /** `mm:ss`, `mm:ss.x`, `mm:ss.xx` or `mm:ss.xxx`. */
@@ -23,6 +23,7 @@ import it.panov.musyx.tv.api.Genre
import it.panov.musyx.tv.api.Home import it.panov.musyx.tv.api.Home
import it.panov.musyx.tv.api.LibraryPlaylists import it.panov.musyx.tv.api.LibraryPlaylists
import it.panov.musyx.tv.api.LikedIds 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.Lyrics
import it.panov.musyx.tv.api.MY_WAVE import it.panov.musyx.tv.api.MY_WAVE
import it.panov.musyx.tv.api.PlaylistId import it.panov.musyx.tv.api.PlaylistId
@@ -541,11 +542,11 @@ class AppState(
// ---- Lyrics ---- // ---- 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) { fun wantLyrics(track: Track) {
if (lyrics.containsKey(track.id)) return if (lyrics.containsKey(track.id)) return
lyrics[track.id] = Loadable.Loading 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) { fun retryLyrics(track: Track) {
@@ -71,6 +71,7 @@ import androidx.tv.material3.Text
import it.panov.musyx.tv.MainActivity import it.panov.musyx.tv.MainActivity
import it.panov.musyx.tv.R import it.panov.musyx.tv.R
import it.panov.musyx.tv.api.Lyrics 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.api.Track
import it.panov.musyx.tv.player.Notice import it.panov.musyx.tv.player.Notice
import it.panov.musyx.tv.player.PlaybackState 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),
)
}
}
} }
} }
+2 -1
View File
@@ -208,10 +208,11 @@
<string name="queue_next_up">Далее · %1$d</string> <string name="queue_next_up">Далее · %1$d</string>
<string name="queue_empty">Очередь пока пуста. Здесь появятся треки, которые вы включите, и те, что за ними.</string> <string name="queue_empty">Очередь пока пуста. Здесь появятся треки, которые вы включите, и те, что за ними.</string>
<string name="lyrics_play_first">Включите трек, чтобы увидеть его текст.</string> <string name="lyrics_play_first">Включите трек, чтобы увидеть его текст.</string>
<string name="lyrics_none">У Яндекс Музыки нет текста этого трека.</string> <string name="lyrics_none">Текст этого трека не найден.</string>
<string name="lyrics_failed">Не удалось загрузить текст. Проверьте подключение и попробуйте ещё раз.</string> <string name="lyrics_failed">Не удалось загрузить текст. Проверьте подключение и попробуйте ещё раз.</string>
<string name="lyrics_loading">Загружаем текст…</string> <string name="lyrics_loading">Загружаем текст…</string>
<string name="lyrics_writers">Авторы: %1$s</string> <string name="lyrics_writers">Авторы: %1$s</string>
<string name="lyrics_source_lrclib">Текст из LRCLIB</string>
<string name="notice_station_dry">Не удалось загрузить продолжение станции. Проверьте подключение и попробуйте ещё раз.</string> <string name="notice_station_dry">Не удалось загрузить продолжение станции. Проверьте подключение и попробуйте ещё раз.</string>
<string name="notice_too_many">Несколько треков подряд не удалось воспроизвести. Проверьте подключение и попробуйте ещё раз.</string> <string name="notice_too_many">Несколько треков подряд не удалось воспроизвести. Проверьте подключение и попробуйте ещё раз.</string>
<string name="notice_skipped">Не удалось воспроизвести «%1$s», трек пропущен.</string> <string name="notice_skipped">Не удалось воспроизвести «%1$s», трек пропущен.</string>
+2 -1
View File
@@ -222,10 +222,11 @@
<string name="queue_next_up">Next up · %1$d</string> <string name="queue_next_up">Next up · %1$d</string>
<string name="queue_empty">Nothing queued yet. Tracks you play, and the ones lined up after them, show up here.</string> <string name="queue_empty">Nothing queued yet. Tracks you play, and the ones lined up after them, show up here.</string>
<string name="lyrics_play_first">Play a track to see its lyrics.</string> <string name="lyrics_play_first">Play a track to see its lyrics.</string>
<string name="lyrics_none">Yandex Music has no lyrics for this track.</string> <string name="lyrics_none">No lyrics found for this track.</string>
<string name="lyrics_failed">Couldn\'t load the lyrics. Check your connection and try again.</string> <string name="lyrics_failed">Couldn\'t load the lyrics. Check your connection and try again.</string>
<string name="lyrics_loading">Loading lyrics…</string> <string name="lyrics_loading">Loading lyrics…</string>
<string name="lyrics_writers">Written by %1$s</string> <string name="lyrics_writers">Written by %1$s</string>
<string name="lyrics_source_lrclib">Lyrics from LRCLIB</string>
<string name="notice_station_dry">Couldn\'t load more of this station. Check your connection and try again.</string> <string name="notice_station_dry">Couldn\'t load more of this station. Check your connection and try again.</string>
<string name="notice_too_many">Several tracks in a row couldn\'t be played. Check your connection and try again.</string> <string name="notice_too_many">Several tracks in a row couldn\'t be played. Check your connection and try again.</string>
<string name="notice_skipped">Couldn\'t play “%1$s”, so it was skipped.</string> <string name="notice_skipped">Couldn\'t play “%1$s”, so it was skipped.</string>
@@ -367,6 +367,86 @@ class ApiTest {
assertNull(Lyrics.parseStamp("00:01.1234")) 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 ---- // ---- Auth, errors, signing ----
@Test @Test