Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions src/libopensonic/_async/connection.py
Original file line number Diff line number Diff line change
Expand Up @@ -1249,7 +1249,7 @@ async def get_lyrics(self, artist:str|None=None, title:str|None=None) -> Lyrics:
return Lyrics.from_dict(dres['lyrics'])


async def get_lyrics_by_song_id(self, song_id:str) -> list[StructuredLyrics]:
async def get_lyrics_by_song_id(self, song_id:str, enhanced:bool=False) -> list[StructuredLyrics]:
"""Retrieve all structured lyrics for a given song.

Lyrics may come from embedded tags (SYLT/USLT), LRC file, or any
Expand All @@ -1260,6 +1260,10 @@ async def get_lyrics_by_song_id(self, song_id:str) -> list[StructuredLyrics]:

Args:
song_id: The ID of the requested song.
enhanced: Request word-level cue data from servers that support
the OpenSubsonic lyrics v2 extension. When True, the response
may include cueLine entries in addition to the line data.
Defaults to False, which keeps the version 1 response.

Returns:
A list of media.StructuredLyrics objects.
Expand All @@ -1269,7 +1273,7 @@ async def get_lyrics_by_song_id(self, song_id:str) -> list[StructuredLyrics]:
"""
method = 'getLyricsBySongId'

q = self._get_query_dict({'id': song_id})
q = self._get_query_dict({'id': song_id, 'enhanced': True if enhanced else None})

res = await self._do_request(method, q)
dres = await self._handle_info_res(res)
Expand Down
56 changes: 56 additions & 0 deletions test/test_connection.py
Original file line number Diff line number Diff line change
Expand Up @@ -1694,6 +1694,62 @@ async def test_get_lyrics_by_song_id_with_data(self, conn, mock_session, mock_re
assert len(result) == 1
assert isinstance(result[0], StructuredLyrics)

@pytest.mark.asyncio
async def test_get_lyrics_by_song_id_enhanced(self, conn, mock_session, mock_response):
"""Test get_lyrics_by_song_id asks for word-level cues when enhanced."""
set_json_response(mock_response, make_response({"lyricsList": {}}))
mock_session.post = AsyncMock(return_value=mock_response)

await conn.get_lyrics_by_song_id("song-1", enhanced=True)

data = mock_session.post.call_args.kwargs["data"]
assert data["enhanced"] == "true"

@pytest.mark.asyncio
async def test_get_lyrics_by_song_id_defaults_to_line_level(self, conn, mock_session, mock_response):
"""Test get_lyrics_by_song_id omits enhanced unless requested."""
set_json_response(mock_response, make_response({"lyricsList": {}}))
mock_session.post = AsyncMock(return_value=mock_response)

await conn.get_lyrics_by_song_id("song-1")

data = mock_session.post.call_args.kwargs["data"]
assert "enhanced" not in data

@pytest.mark.asyncio
async def test_get_lyrics_by_song_id_with_cues(self, conn, mock_session, mock_response):
"""Test get_lyrics_by_song_id parses word-level cue data."""
lyrics = {
"lyricsList": {
"structuredLyrics": [{
"lang": "en",
"synced": True,
"line": [{"value": "We're no strangers to love", "start": 18890}],
"cueLine": [{
"index": 0,
"start": 18890,
"end": 22820,
"value": "We're no strangers to love",
"cue": [
{"start": 18890, "end": 19250, "byteStart": 0,
"byteEnd": 5, "value": "We're "},
{"start": 19250, "end": 19530, "byteStart": 6,
"byteEnd": 8, "value": "no "},
],
}],
}]
}
}
set_json_response(mock_response, make_response(lyrics))
mock_session.post = AsyncMock(return_value=mock_response)

result = await conn.get_lyrics_by_song_id("song-1", enhanced=True)

cue_line = result[0].cue_line[0]
assert cue_line.index == 0
assert [cue.value for cue in cue_line.cue] == ["We're ", "no "]
assert cue_line.cue[1].byte_start == 6


# ============================================================================
# NOW PLAYING / SCROBBLE / PLAY QUEUE
Expand Down
Loading