feat(lyrics): Tidal as lyrics source by treyturner · Pull Request #6730 · beetbox/beets

treyturner · 2026-06-11T21:59:22Z

Description

Add TIDAL API support for fetching track lyric relationships, including typed lyric resources and configurable OAuth scopes.
Add tidal as an opt-in lyrics source with plain/synced lyric selection, token scope validation, defensive JSON:API response handling, and match-debug parity with search backends.
Document TIDAL lyrics configuration, user.read authentication requirements, and scope formats.

Testing

poetry run ruff format --check --diff beetsplug/tidal/__init__.py beetsplug/tidal/api.py beetsplug/tidal/api_types.py beetsplug/tidal/session.py test/plugins/test_tidal.py
poetry run ruff check beetsplug/tidal/__init__.py beetsplug/tidal/api.py beetsplug/tidal/api_types.py beetsplug/tidal/session.py test/plugins/test_tidal.py
poetry run pytest test/plugins/test_tidal.py
poetry run ruff format --check --diff beetsplug/lyrics.py test/plugins/test_lyrics.py
poetry run ruff check beetsplug/lyrics.py test/plugins/test_lyrics.py
poetry run pytest test/plugins/test_lyrics.py
poetry run docstrfmt --preserve-adornments --check docs/plugins/lyrics.rst docs/plugins/tidal.rst docs/changelog.rst
poetry run sphinx-lint --enable all --disable default-role docs/plugins/lyrics.rst docs/plugins/tidal.rst docs/changelog.rst
env -u NO_COLOR poetry run pytest

To Do

Documentation. (If you've added a new command-line flag, for example, find the appropriate page under docs/ to describe it.)
Changelog. (Add an entry to docs/changelog.rst to the bottom of one of the lists near the top of the document.)
Tests. (Very much encouraged but not strictly required.)

codecov · 2026-06-11T22:07:13Z

Codecov Report

❌ Patch coverage is 97.93103% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.86%. Comparing base (ec729d3) to head (a96a565).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
beetsplug/lyrics.py	98.56%	1 Missing and 1 partial ⚠️
beetsplug/tidal/api.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6730      +/-   ##
==========================================
+ Coverage   74.71%   74.86%   +0.15%     
==========================================
  Files         162      162              
  Lines       20831    20969     +138     
  Branches     3298     3327      +29     
==========================================
+ Hits        15563    15699     +136     
- Misses       4508     4509       +1     
- Partials      760      761       +1

Files with missing lines	Coverage Δ
beetsplug/tidal/__init__.py	`85.40% <100.00%> (ø)`
beetsplug/tidal/session.py	`40.00% <100.00%> (ø)`
beetsplug/tidal/api.py	`34.11% <75.00%> (+1.58%)`	⬆️
beetsplug/lyrics.py	`89.59% <98.56%> (+2.30%)`	⬆️

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

semohr

Thanks! It's great to see more activity around the TIDAL plugin. I already did a quick scan of the changes, but I'll do a more thorough review next week.

I think we should keep the requested capabilities (scope) out of the user configuration. While I understand it's convenient to make this configurable during development, I can foresee quite a few user errors if it's exposed.

I see two possible approaches:

Run the TIDAL plugin with search.read user.read by default.
Run with only search.read by default, and automatically request user.read when the tidal lyrics plugin is enabled.

I'd vote for the first option. It keeps the configuration simpler and avoids potential issues for users. The user.read scope will be needed at some point anyways if we want e.g. to allow users to use their own music.

@snejus Any strong opinion here?

semohr · 2026-06-14T14:29:49Z

+        return self.scope_set(token.get("scope") or token.get("scopes"))
+
+    @cached_property
+    def token_has_required_scopes(self) -> bool:


Lets put the scope safeguards into the general tidal session. Checking that the token includes the correct scope can be done once on token loading. Inside the load_token function should work. This should allow users to update their tokens.

I get where you come from as technically we don't need the user.read scope for the non lyrics functions (yet). Most of the logic here looks a bit overengineered to me tho, let's keep it simple. Will spare us some maintenance down the line.

semohr · 2026-06-14T14:48:39Z

+        self, track_ids: list[str]
+    ) -> Iterable[tuple[str, TidalLyrics]]:
+        """Fetch lyric resources for TIDAL track IDs."""
+        tracks_data = self.api.get_tracks(


Lets rename this for consistency.

Suggested change

tracks_data = self.api.get_tracks(

tracks_doc = self.api.get_tracks(

semohr · 2026-06-14T14:52:43Z

+
+        return None
+
+    def fetch_tracks_lyrics(


Can we change the signature to -> Iterable[TrackInfo | None]: and move the warnings out of this function. Have a look at TidalApi.search_tracks_by_ids I used that approach to keep the order of returned objs to align with the input ids.

semohr · 2026-06-14T15:04:00Z

+            country_code=self.country_code,
+        )
+
+        search_result = search_data.get("data")


Do we need to be defensive here? We are basically doing the same in the tidal plugin without being defensive. Am just wondering.

Same for relationships = search_result.get("relationships")

semohr · 2026-06-15T09:21:33Z

FYI: I just enabled the user.read for our tidal app. Im now wondering how requesting the user.read scope worked in the first place 🤔

semohr · 2026-06-15T09:23:41Z

Document TIDAL lyrics configuration, user.read authentication requirements, and scope formats.

I'm now also wondering which request does need the user.read scope in the first place? 😄

treyturner · 2026-06-16T17:18:51Z

I had initially verified lyrics retrieval via a developer app ID, but once I saw there was a public API that purported to retrieve lyrics I cut over to it. That may have been premature though, as I now can't actually get their public API to return lyrics as documented. I'm moving this back into draft while I figure out if the only path to lyrics is via developer app credentials. Sorry for the false start.

treyturner · 2026-06-16T18:23:07Z

The user.read scope was my misunderstanding that we'd get the same data back from the v2 API as I got from the legacy r_usr scope on the v1 API, but this seems to not be the case. I can't actually get the v2 API to hand me lyrics with any scope I'm able to configure at the moment, so I'm going to cut this back over to the v1 API totally independent of the built-in tidal plugin and will release it as an external plugin. I was too eager to contribute to tidal once I saw it existed and didn't identify the risk of functional gaps in the API version change since the documentation suggests they're still retrievable.

I'm really sad it can't land in the project and want to apologize again for the hassle. If I see something change in the API I'll pick it back up; I was also hoping to add Tidal as an art source.

semohr · 2026-06-16T19:59:33Z

I had initially verified lyrics retrieval via a developer app ID, but once I saw there was a public API that purported to retrieve lyrics I cut over to it. That may have been premature though, as I now can't actually get their public API to return lyrics as documented. I'm moving this back into draft while I figure out if the only path to lyrics is via developer app credentials. Sorry for the false start.

No worries :/ The tidal public api can be a bit difficult to use and sometimes even buggy. If you want I can also have a look at it, maybe we can make it work. You have a curl request that should work?

semohr · 2026-06-16T20:25:42Z

Seems like a known issue https://github.com/orgs/tidal-music/discussions/279

github-actions Bot added the lyrics lyrics plugin label Jun 11, 2026

treyturner force-pushed the feat/tidal_as_lyrics_source branch from 3d016e6 to 0b59185 Compare June 11, 2026 22:45

treyturner marked this pull request as ready for review June 11, 2026 22:51

treyturner requested review from a team and semohr as code owners June 11, 2026 22:51

semohr self-assigned this Jun 12, 2026

semohr requested changes Jun 12, 2026

View reviewed changes

Comment thread beetsplug/tidal/__init__.py Outdated

Comment thread docs/plugins/lyrics.rst Outdated

semohr added the tidal label Jun 12, 2026

treyturner force-pushed the feat/tidal_as_lyrics_source branch 3 times, most recently from 06de8f8 to 81bb966 Compare June 12, 2026 13:23

treyturner added 4 commits June 12, 2026 11:28

Support configurable TIDAL OAuth scopes

4c51c84

Add TIDAL lyrics backend

d81da0f

Document TIDAL lyrics source

a5018bf

Hardcode expanded TIDAL scope

a96a565

treyturner force-pushed the feat/tidal_as_lyrics_source branch from 81bb966 to a96a565 Compare June 12, 2026 16:28

semohr requested changes Jun 14, 2026

View reviewed changes

treyturner marked this pull request as draft June 16, 2026 17:16

treyturner closed this Jun 16, 2026

	tracks_data = self.api.get_tracks(
	tracks_doc = self.api.get_tracks(

Conversation

treyturner commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

To Do

Uh oh!

codecov Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

semohr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

semohr Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

semohr Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

semohr Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

semohr Jun 14, 2026

Choose a reason for hiding this comment

Uh oh!

semohr commented Jun 15, 2026

Uh oh!

semohr commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

treyturner commented Jun 16, 2026

Uh oh!

treyturner commented Jun 16, 2026

Uh oh!

semohr commented Jun 16, 2026

Uh oh!

semohr commented Jun 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

treyturner commented Jun 11, 2026 •

edited

Loading

codecov Bot commented Jun 11, 2026 •

edited

Loading

semohr commented Jun 15, 2026 •

edited

Loading