From 9297243b5f7efa5b9cfc7ee2d3889ef9ea84b16f Mon Sep 17 00:00:00 2001 From: Janek Date: Wed, 18 Nov 2026 15:12:08 +0100 Subject: [PATCH] Add enhanced flag to get_lyrics_by_song_id --- src/libopensonic/_async/connection.py | 8 +++- test/test_connection.py | 56 +++++++++++++++++++++++++++ 2 files changed, 62 insertions(+), 2 deletions(-) diff --git a/src/libopensonic/_async/connection.py b/src/libopensonic/_async/connection.py index 723e9eb..8042e5b 100644 --- a/src/libopensonic/_async/connection.py +++ b/src/libopensonic/_async/connection.py @@ -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 @@ -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. @@ -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) diff --git a/test/test_connection.py b/test/test_connection.py index 013c25e..e2552d2 100644 --- a/test/test_connection.py +++ b/test/test_connection.py @@ -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