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

@@ -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. */
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. */
fun current(positionMs: Long): Int? {
if (!synced) return null
@@ -13,11 +21,11 @@ data class Lyrics(val lines: List<LyricLine>, 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<String>) =
Lyrics(text.lines().map { LyricLine(null, it.trimEnd()) }, synced = false, writers = writers)
fun fromText(text: String, writers: List<String>, 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<String>): Lyrics {
fun fromLrc(lrc: String, writers: List<String>, source: LyricsSource = LyricsSource.Yandex): Lyrics {
val lines = mutableListOf<LyricLine>()
for (raw in lrc.lines()) {
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)
}
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`. */
@@ -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) {
@@ -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),
)
}
}
}
}
+2 -1
View File
@@ -208,10 +208,11 @@
<string name="queue_next_up">Далее · %1$d</string>
<string name="queue_empty">Очередь пока пуста. Здесь появятся треки, которые вы включите, и те, что за ними.</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_loading">Загружаем текст…</string>
<string name="lyrics_writers">Авторы: %1$s</string>
<string name="lyrics_source_lrclib">Текст из LRCLIB</string>
<string name="notice_station_dry">Не удалось загрузить продолжение станции. Проверьте подключение и попробуйте ещё раз.</string>
<string name="notice_too_many">Несколько треков подряд не удалось воспроизвести. Проверьте подключение и попробуйте ещё раз.</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_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_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_loading">Loading lyrics…</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_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>
@@ -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