Song Lyrics

OpenSubsonic version: 1

OpenSubsonic extension name songLyrics (As returned by getOpenSubsonicExtensions)

Version 1

Line-level structured lyrics with multi-language support.

This extension requires the following endpoints:

• getLyricsBySongId: Fetch structured song lyrics by id

Version 2

Word/syllable-level timing (karaoke) and lyric layer classification (translations, pronunciations).

Adds:

• enhanced query parameter on getLyricsBySongId to opt-in to enhanced lyrics data
• kind field on structuredLyrics to classify independent lyric layers (main, translation, pronunciation)
• agent objects within an optional agents array on structuredLyrics for reusable agent attribution metadata
• cueLine array on structuredLyrics for word/syllable-level timing
• agentId field on cueLine to reference an agent in the same structuredLyrics entry
• cue objects within each cueLine for individual word/syllable timestamps, with required byteStart / byteEnd offsets into cueLine.value

When agent attribution is present, the reusable agent metadata lives once in structuredLyrics.agents, while each cueLine points at the relevant agent via agentId. Simple unattributed single-layer lyrics may omit agents entirely. Entries with multiple vocal agents/layers must emit agents, and every attributed entry that uses agents must define exactly one role: "main" agent. A single-agent attributed/default layer may also use agents with that lone agent marked as main.

Each cue includes byteStart / byteEnd, defined as 0-based inclusive offsets into the UTF-8 encoding of the final cueLine.value, with no normalization step. Accordingly, each cueLine that contains cues must also include value. When multiple agent cueLines share one parent line index, each cueLine.value is the renderable text for that agent/layer, not necessarily the parent line’s combined text.

All new fields are gated behind enhanced=true — without it, the response is identical to version 1.

Servers that support Version 2 should advertise songLyrics versions [1, 2] via getOpenSubsonicExtensions.

This extension requires the following endpoints:

• getLyricsBySongId: Fetch structured song lyrics by id (with optional enhanced parameter)