[Suggestion] Implement lyrics button on player to fetch and display song lyrics

[Wikijito7]

Is your feature request related to a problem? Please describe.
Currently the player has playback control buttons (pause, skip, shuffle, etc.) but no way to view lyrics for the currently playing track. Users have to look up lyrics manually outside Discord.

Describe the solution you'd like
Add a Lyrics button (📝) to the player's action row that fetches and displays lyrics for the current track using LavaLyrics + LavaSrc's built-in lyrics providers.

Implementation Plan

🧱 1. Build Configuration

• File: gradle/libs.versions.toml
  • Add version: lavalyrics = "1.1.0"
  • Add library: lavalyrics = { module = "com.github.topi314.lavalyrics:lavalyrics", version.ref = "lavalyrics" }
• File: build.gradle.kts
  • Add dependency: implementation(libs.lavalyrics)
• No new repository needed — https://maven.topi.wtf/releases is already configured.

📦 2. New Service: LyricsService

• Path: src/main/kotlin/services/lavaplayer/LyricsService.kt
• Wraps LavaLyrics' LyricsManager and registers LrcLibLyricsManager (from LavaSrc) as the lyrics provider.
• LrcLibLyricsManager searches lrclib.net by track name + artist, works for any source (YouTube, Spotify, Deezer, etc.)
• Exposes:
  • getLyrics(track: AudioTrack): AudioLyrics? — fetches lyrics
  • getFormattedLyrics(track: AudioTrack): String? — returns formatted plain text lyrics or null
• Future enhancement: Register SpotifySourceManager / DeezerAudioSourceManager directly into LyricsManager once they're exposed from AudioPlayerManagerProvider, for source-native higher-quality lyrics.

🔌 3. DI Registration

• File: src/main/kotlin/di/ServicesModule.kt
  • Add singleOf(::LyricsService) (singleton)

🆕 4. Button Component

• File: src/main/kotlin/commands/ComponentsEnum.kt
  • Add PLAYER_LYRICS("player_lyrics")

🎛️ 5. Player UI — Add Button

• File: src/main/kotlin/commands/player/PlayerCommons.kt
  • Add lyrics button (📝) to createPlayerComponents():

  interactionButton(
      style = ButtonStyle.Secondary,
      customId = ComponentsEnum.PLAYER_LYRICS.customId
  ) {
      label = localizationService.getString(key = LocalizationKeys.PLAYER_LYRICS, ...)
      emoji = DiscordPartialEmoji(name = "📝")
  }

🕹️ 6. Button Handler

• File: src/main/kotlin/commands/player/PlayerCommand.kt
  • Inject LyricsService
  • Add PLAYER_LYRICS case in onInteract():
    1. Get current track from lavaPlayerService.getCurrentPlayingTrack()
    2. If nothing playing → send ephemeral "no track playing"
    3. Try lyricsService.getFormattedLyrics(track.audioTrack)
    4. If found → send ephemeral message with lyrics
    5. If not → send ephemeral "lyrics not found" message

🌐 7. Localization

• lang.yml:

  player_lyrics: Lyrics
  player_lyrics_not_found: No lyrics found for the current track
  player_lyrics_title: Lyrics — %s

• lang_es-ES.yml:

  player_lyrics: Letra
  player_lyrics_not_found: No se encontraron letras para la pista actual
  player_lyrics_title: Letra — %s

• LocalizationKeys.kt — auto-generated via generateLangClass Gradle task.

🧪 8. Tests

• Path: src/test/kotlin/services/lavaplayer/LyricsServiceTest.kt
• Unit tests for LyricsService with mocked LyricsManager:
  • Returns lyrics when found
  • Returns null when no lyrics available
  • Handles null/empty/malformed responses

Architecture Reference

Component	File	Relevant Lines
Player embed builder	commands/player/PlayerCommons.kt	23-87 embed, 102-150 buttons
Button handler	commands/player/PlayerCommand.kt	146-176
Button IDs enum	commands/ComponentsEnum.kt	3-26
Button dispatch	services/commands/CommandHandlerService.kt	112-137, 168-179
DI ServicesModule	di/ServicesModule.kt	21-34
LyricsManager (LavaLyrics)	LavaLyrics repo	LyricsManager.java, AudioLyrics.java
LrcLibLyricsManager (LavaSrc)	LavaSrc repo	lrclib/LrcLibLyricsManager.java

Describe alternatives you've considered

• Modal popup: Discord modals have 4000-char limit and disappear after one use — unsuitable for lyrics.
• Edit player embed: Would replace the controls interface until next interaction — disruptive UX.
• Separate channel: Creates noise — ephemeral follow-up is cleaner.
• Scrolling embed: Discord embeds have field limits — synchronous lyrics in a text message is simpler.

Chosen UX: Ephemeral follow-up message (only the user who clicked sees it), showing lyrics in a code block for readability.

Additional context

• LavaSrc (v4.8.1) already has AudioLyricsManager implementations in Spotify, Deezer, Yandex Music, and VK Music source managers.
• The LrcLibLyricsManager from LavaSrc provides a fallback that works for any track by searching by artist+title.
• The repository https://maven.topi.wtf/releases is already configured.
• LavaLyrics v1.1.0 requires no new infrastructure.

Media
N/A — this is a feature request.

[Wikijito7]

🔄 Update: Add Deezer lyrics integration (1st iteration)

After further analysis, we'll include Deezer as a lyrics source alongside LrcLibLyricsManager from the start.

How Deezer's loadLyrics() works

DeezerAudioSourceManager (from LavaSrc) implements AudioLyricsManager:

• For Deezer-sourced tracks → gets the Deezer track ID directly, fetches lyrics via Deezer API
• For any other track (YouTube, Spotify, etc.) → searches Deezer by ISRC first, then by title+author as fallback

This makes it a more robust fallback than LrcLib alone for tracks that exist on Deezer.

Integration approach: Inject LyricsService into AudioPlayerManagerProvider

The DeezerAudioSourceManager is created inside AudioPlayerManagerProvider.createAudioPlayerManager() but never exposed. To register it with the LyricsManager, we'll inject LyricsService into AudioPlayerManagerProvider and register the Deezer source right where it's created:

class AudioPlayerManagerProvider(
    private val configService: ConfigService,
    private val lyricsService: LyricsService      // ✨ new
) {
    private var lyricsConfigured = false

    fun createAudioPlayerManager(): AudioPlayerManager = DefaultAudioPlayerManager().apply {
        // ... existing code ...
        
        if (config.deezer.enabled) {
            val deezerSource = DeezerAudioSourceManager(
                config.deezer.masterDecryptionKey,
                config.deezer.arlToken
            )
            this.registerSourceManager(deezerSource)
            if (!lyricsConfigured) lyricsService.registerLyricsManager(deezerSource)  // ✨
        }
        
        if (!lyricsConfigured) {
            lyricsService.registerLyricsManager(LrcLibLyricsManager())               // ✨
            lyricsConfigured = true
        }
        
        // ... rest of existing code ...
    }
}

Updated file changes

File	Change
gradle/libs.versions.toml	Add lavalyrics = "1.1.0" + library entry
build.gradle.kts	Add implementation(libs.lavalyrics)
services/lavaplayer/AudioPlayerManagerProvider.kt	Inject LyricsService, register Deezer + LrcLib
services/lavaplayer/LyricsService.kt	NEW — wraps LyricsManager, exposes getLyrics(track)
di/ServicesModule.kt	singleOf(::LyricsService), change provider to singleOf
commands/ComponentsEnum.kt	Add PLAYER_LYRICS("player_lyrics")
commands/player/PlayerCommons.kt	Add 📝 button
commands/player/PlayerCommand.kt	Handle PLAYER_LYRICS, inject LyricsService
lang.yml + lang_es-ES.yml	New strings
services/lavaplayer/LyricsServiceTest.kt	NEW — unit tests

Total: 2 new files, 8 modified files.

Lyrics resolution priority (when button is clicked)

1. Deezer (if track source is "deezer" → native Deezer lyrics via DeezerAudioSourceManager.loadLyrics())
2. LrcLib (any track, searches lrclib.net by artist+title)
3. Deezer (fallback loop for non-Deezer tracks, searches by ISRC/title)

[Wikijito7]

🔄 Update: Lyrics visibility — public, not ephemeral

Per review: when a user clicks the lyrics button, everyone should see the lyrics, not just the clicker.

Updated UX flow

1. User clicks 📝 button
2. Bot fetches lyrics via LyricsService
3. If found → sends a public follow-up message in the #player channel (visible to all) with:
   • Track name as header
   • Lyrics text in a code block
4. If not found → sends an ephemeral "No lyrics found" message (only the clicker sees it)
5. Player embed stays unchanged — no edit needed

Implementation approach

Since onInteract() receives a ComponentInteraction, we can use Discord's follow-up webhook API to send a public message after the deferred response:

ComponentsEnum.PLAYER_LYRICS.customId -> {
    val track = lavaPlayerService?.getCurrentPlayingTrack()
    if (track == null) {
        interaction.kord.rest.interaction.createFollowupMessage(
            interaction.applicationId, interaction.token, ephemeral = true
        ) { content = noTrackMsg }
        return
    }
    val lyrics = lyricsService?.getFormattedLyrics(track.audioTrack)
    if (lyrics != null) {
        interaction.kord.rest.interaction.createFollowupMessage(
            interaction.applicationId, interaction.token, ephemeral = false
        ) { content = "**${trackName}**\n\n```$lyrics```" }
    } else {
        interaction.kord.rest.interaction.createFollowupMessage(
            interaction.applicationId, interaction.token, ephemeral = true
        ) { content = noLyricsMsg }
    }
    return  // skip player embed update
}

The return prevents the existing interaction.message.edit { ... } call from running after the when block, keeping the player view intact.

[Wikijito7]

🔄 Update: Lyrics auto-follows track changes

Per review: clicking 📝 once activates "lyrics mode" — the lyrics message auto-updates as tracks change, until the queue empties.

Behavior

1. User clicks 📝 → bot sends a public message with current track's lyrics
2. Track ends, new track starts → bot edits the same message with the new track's lyrics
3. Queue empties → lyrics message stays as the last track's lyrics (no cleanup needed)
4. User clicks 📝 again → rebinds/updates for the current track (idempotent)

Implementation

GuildLavaPlayerService changes

private var lyricsMessage: Message? = null   // NEW
private var lyricsService: LyricsService? = null  // injected

fun saveLyricsMessage(message: Message) {
    this.lyricsMessage = message
}

fun getLyricsMessage(): Message? = lyricsMessage

// In onTrackStart — after existing logic:
override fun onTrackStart(player: AudioPlayer?, track: AudioTrack?) {
    if (isRetrying) return
    coroutineScope.launch {
        discordLocale = voiceChannel.getLocale()
        val voiceChannelName = voiceChannel.asChannel().name
        playerMessage?.let {
            updateSeekChannel.send(Unit)
        } ?: sendNowPlayingMessage(discordLocale, voiceChannelName)
        
        updateLyricsMessage()  // ✨ NEW: auto-update lyrics on track change
    }
}

private suspend fun updateLyricsMessage() {
    val msg = lyricsMessage ?: return
    val track = currentTrack ?: return
    val lyrics = lyricsService?.getFormattedLyrics(track.audioTrack)
    if (lyrics != null) {
        msg.edit { content = "**${track.getDisplayTrackName()}**\n\n${lyrics}" }
    }
}

PlayerCommand.onInteract() — PLAYER_LYRICS handler

ComponentsEnum.PLAYER_LYRICS.customId -> {
    val track = lavaPlayerService?.getCurrentPlayingTrack() ?: run {
        // ephemeral "no track" message
        interaction.kord.rest.interaction.createFollowupMessage(...)
        return
    }
    val lyrics = lyricsService?.getFormattedLyrics(track.audioTrack)
    val existingMsg = lavaPlayerService?.getLyricsMessage()
    
    if (existingMsg != null) {
        // Update existing lyrics message for new current track
        if (lyrics != null) {
            existingMsg.edit { content = "**${track.getDisplayTrackName()}**\n\n$lyrics" }
        } else {
            existingMsg.edit { content = noLyricsMsg }
        }
    } else if (lyrics != null) {
        // Create new public lyrics message
        val msg = interaction.kord.rest.interaction.createFollowupMessage(...)
        lavaPlayerService?.saveLyricsMessage(PublicFollowupMessage(msg, ...))
    } else {
        // Ephemeral "no lyrics" message
        interaction.kord.rest.interaction.createFollowupMessage(ephemeral = true, ...)
    }
    return  // skip player embed edit
}

GuildLavaPlayerService injection

LyricsService must be injected into GuildLavaPlayerService. Since GuildLavaPlayerService is not created via Koin (it's instantiated manually in GuildQueueService.createLavaPlayer()), we'll pass it as a constructor parameter from GuildQueueService.

File changes (updated)

File	Change
gradle/libs.versions.toml	Add lavalyrics = "1.1.0" + library entry
build.gradle.kts	Add implementation(libs.lavalyrics)
services/lavaplayer/AudioPlayerManagerProvider.kt	Inject LyricsService, register Deezer + LrcLib
services/lavaplayer/LyricsService.kt	NEW — wraps LyricsManager, exposes getFormattedLyrics(track)
services/lavaplayer/GuildLavaPlayerService.kt	Add lyricsMessage field, updateLyricsMessage() in onTrackStart(), cleanup
services/queue/GuildQueueService.kt	Pass LyricsService to GuildLavaPlayerService
di/ServicesModule.kt	singleOf(::LyricsService), change provider to singleOf
commands/ComponentsEnum.kt	Add PLAYER_LYRICS("player_lyrics")
commands/player/PlayerCommons.kt	Add 📝 button
commands/player/PlayerCommand.kt	Handle PLAYER_LYRICS: send public msg + save ref, return early
lang.yml + lang_es-ES.yml	New strings
services/lavaplayer/LyricsServiceTest.kt	NEW — unit tests

Total: 2 new files, 10 modified files.

[Wikijito7]

🔄 Update: Lyrics button is a toggle (show/hide with auto-follow)

Finalized UX:

• First click → bot sends a public lyrics message + starts auto-follow (updates as tracks change)
• Second click → bot deletes the lyrics message, auto-follow stops
• Third click → creates it again (re-binds)
• And so on... it's a toggle

The button itself shows different labels:

• When lyrics hidden → Lyrics (📝)
• When lyrics showing → Hide Lyrics (📝) — or same label, behavior toggles

Implementation hooks:

• GuildLavaPlayerService stores var lyricsMessage: Message? = null
• onTrackStart() checks if lyricsMessage != null → fetches + edits with new lyrics
• Toggle off: deletes the message + sets lyricsMessage = null
• handleDisconnectEvent() also cleans up the lyrics message

This is the final UX design. Ready for implementation whenever approved. 🍌