Lyrics API

Provide synced or plain lyrics for tracks in your Spotube plugin.

Implement LyricsAPI to provide lyrics. Include "LYRICS" in plugin.json abilities.

Interface

interface LyricsAPI : ZiplineService {
    suspend fun getLyrics(track: MetadataTrack): LyricsResponse?
}

getLyrics() receives a MetadataTrack and returns either a LyricsResponse or null (no lyrics available). You can provide synced lyrics, plain text, or both.

Lyric formats

Two formats are supported, and you can provide either or both in the response:

Synced lyrics - timestamped lines (LRC-style). Each LyricsLine has a time in milliseconds and the text at that timestamp. Spotube uses these to highlight lyrics as the track plays.

Plain lyrics - a single string with the full lyrics. Shown when synced lyrics aren't available or the user prefers a static view.

data class LyricsResponse(
    val syncedLyrics: List<LyricsLine>?,
    val plainLyrics: String?,
)

data class LyricsLine(val time: Long, val text: String)

Implementation guide

Most lyrics providers can be queried by track title and artist name. Pass track.title and track.artists.firstOrNull()?.name to your provider's API. Map the response to LyricsResponse - parse LRC timestamps into LyricsLine objects if the provider returns synced lyrics, or set plainLyrics for unstructured text.

For a complete working implementation, see the example's RealLyricsAPI.

Binding

import dev.krtirtho.plugin_interfaces.plugin_apis.lyrics.LyricsAPI
import dev.krtirtho.plugin_interfaces.plugin_apis.lyrics.LyricsAPI_SERVICE_NAME

zipline.bind<LyricsAPI>(LyricsAPI_SERVICE_NAME, RealLyricsAPI())