Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/calmerism/Tamed/llms.txt

Use this file to discover all available pages before exploring further.

Tamed has one of the most comprehensive lyrics systems of any Android music player. It queries up to ten independent providers in priority order, caches results in an LruCache, pre-loads lyrics for upcoming queue tracks in the background, and displays them with six distinct animation styles. Every aspect—from provider order to text size to AI translation target language—is user-configurable.

​
Supported Lyric Formats

LRC

Line-by-line timestamped lyrics. Each line carries a [mm:ss.xx] timestamp and maps to a LyricsEntry.

TTML

Word-by-word timed lyrics (TTML/Apple Syllable format). Each LyricsEntry contains a list of WordTimestamp objects with per-word startTime and endTime.

Plain Text

Unsynced lyrics without timestamps. Displayed statically when no timed variant is available.

​
LyricsEntry Data Model

data class LyricsEntry(
    val time: Long,
    val text: String,
    val words: List<WordTimestamp>? = null,
    val agent: String? = null,
    val isInstrumental: Boolean = false,
    val durationMs: Long = 0L,
    val providerRomanizedText: String? = null,
    val providerRomanizedWords: List<String>? = null,
    val providerRomanizedLanguage: String? = null,
    val providerTranslationText: String? = null,
    val romanizedTextFlow: MutableStateFlow<String?> = MutableStateFlow(null),
)
Word-level timing comes from WordTimestamp, which carries the word text, its start/end time in seconds, and an isBackground flag for backing-vocal styling.

​
Provider System

​
LyricsHelper

LyricsHelper is the central coordinator. Its primary method is: 
suspend fun getLyrics(
    mediaMetadata: MediaMetadata,
    preferredProviderOnly: Boolean = false,
    ignoreCache: Boolean = false,
): String
  • When preferredProviderOnly is true, only the highest-priority enabled provider is queried.
  • When ignoreCache is true, both the single-result cache and the multi-result LruCache are cleared for the current track before fetching.
  • Results are cached with a key derived from "$artists-$title" (whitespace stripped).
The LruCache holds up to 16 entries (MAX_CACHE_SIZE = 16).

​
The 10 Providers

All providers implement the LyricsProvider interface: 
interface LyricsProvider {
    val name: String
    fun isEnabled(context: Context): Boolean
    suspend fun getLyrics(
        id: String, title: String, artist: String,
        album: String?, duration: Int,
    ): Result<String>
}
Enabled via EnableBetterLyricsKey. Fetches synced LRC/TTML lyrics from the BetterLyrics API, which aggregates several upstream sources.
Enabled via EnableLrcLibKey. Open-source, community-driven LRC database at lrclib.net. Typically returns well-timed LRC files.
Enabled via EnableKugouKey. One of the largest Chinese lyrics databases. Strong coverage for Mandarin, Cantonese, and K-pop.
Enabled via EnableSimpMusicLyricsKey. Lyrics sourced from the SimpMusic project’s endpoint.
Enabled via EnableUnisonLyricsKey. A community lyrics provider with a focus on accuracy.
Enabled via EnablePaxsenixAppleMusicLyricsKey. Fetches Apple Music TTML syllable-level lyrics via the Paxsenix proxy API. Best for word-by-word timing.
Enabled via EnablePaxsenixNeteaseLyricsKey. NetEase Cloud Music via Paxsenix. Excellent coverage for Chinese-language tracks.
Enabled via EnablePaxsenixSpotifyLyricsKey. Spotify line-synced lyrics via Paxsenix.
Enabled via EnablePaxsenixMusixmatchLyricsKey. Musixmatch line-synced lyrics via Paxsenix.
Enabled via EnablePaxsenixYouTubeLyricsKey. YouTube auto-generated captions reformatted as lyrics via Paxsenix.

​
Default Provider Order

The DefaultLyricsProviderOrder constant defines the fallback priority when no user-defined order exists: 
val DefaultLyricsProviderOrder = listOf(
    PreferredLyricsProvider.BETTER_LYRICS,
    PreferredLyricsProvider.LRCLIB,
    PreferredLyricsProvider.KUGOU,
    PreferredLyricsProvider.SIMPMUSIC,
    PreferredLyricsProvider.UNISON,
    PreferredLyricsProvider.PAXSENIX_APPLE_MUSIC,
    PreferredLyricsProvider.PAXSENIX_NETEASE,
    PreferredLyricsProvider.PAXSENIX_SPOTIFY,
    PreferredLyricsProvider.PAXSENIX_MUSIXMATCH,
    PreferredLyricsProvider.PAXSENIX_YOUTUBE,
)
Drag providers into your preferred order in Settings → Lyrics → Provider Order (LyricsProviderOrderKey). LyricsHelper reads this serialised order string on every fetch.

​
Display Settings

​
Animation Styles

The LyricsAnimationStyle enum controls how the active lyric line is highlighted:
StyleBehaviour
NONENo animation — instant highlight switch
FADEThe active line fades in, inactive lines fade out
GLOWActive line gains a colour glow
SLIDELines slide vertically into position
KARAOKEA fill sweep progresses across the text in sync with playback
APPLEMimics the Apple Music bouncing / scaling style

​
Lyrics Mode

enum class LyricsMode {
    V2,
    ENHANCED,
}
V2 is the standard mode. ENHANCED enables additional physics tuning.

​
V2 / Enhanced Tuning Parameters

KeyDescription
LyricsV2BounceFactorKeyAmplitude of the bounce spring effect
LyricsV2GlowFactorKeyIntensity of the glow halo
LyricsV2FillTransitionWidthKeyWidth of the karaoke fill sweep gradient
LyricsV2LrcBounceEnabledKeyWhether LRC lines use the bounce animation

​
Layout Settings

KeyTypeDescription
LyricsTextSizeKeyFloatFont size for lyric lines
LyricsLineSpacingKeyFloatVertical spacing between lines
LyricsTextPositionKeyStringHorizontal alignment (left / centre / right)

​
Romanization & Translation

​
Romanization

Tamed can transliterate non-Latin scripts into Latin characters at display time. Each language is individually toggled:
KeyLanguage
LyricsRomanizeJapaneseKeyJapanese (romaji)
LyricsRomanizeKoreanKeyKorean (revised romanization)
LyricsRomanizeChineseKeyChinese (pinyin)
LyricsRomanizeHindiKeyHindi
LyricsRomanizeOtherLanguagesKeyAll other non-Latin scripts

​
AI Translation

When TranslateLyricsKey is enabled, each lyric line is sent to the configured AI provider and the translated text is displayed below the original. The target language is stored in TranslatorTargetLangKey.
AI translation requires a valid AI provider to be configured in Settings → AI. Supported providers include ChatGPT, Gemini, Claude, OpenRouter, and custom endpoints.

​
Queue Pre-Load

To avoid waiting for lyrics when a track starts, Tamed can pre-fetch lyrics for upcoming queue items:
KeyTypeDescription
PreloadQueueLyricsEnabledKeyBooleanEnable background pre-loading
QueueLyricsPreloadCountKeyIntNumber of upcoming tracks to pre-load
The LyricsPreloadManager runs on the IO dispatcher and stores results in LyricsHelper’s LruCache, so they are available instantly when the track becomes active.

Build docs developers (and LLMs) love

Get started for freeTalk to us