tidal: Add flexible attributes and tidalsync command for popularity data by arsaboo · Pull Request #6744 · beetbox/beets

arsaboo · 2026-06-14T20:13:40Z

This PR adds six typed flexible attributes to the Tidal plugin that are populated during album/track imports, and introduces a new beet tidalsync command to refresh popularity data post-import.

cc: @semohr

Flexible Attributes (`item_types`)

tidal_track_id, tidal_album_id, tidal_artist_id — INTEGER fields for Tidal entity IDs.
tidal_track_popularity, tidal_alb_popularity — INTEGER (0–100) normalized popularity scores.
tidal_updated — DATE timestamp of last sync.

Import population

_get_album_info() and _get_track_info() pass the new fields through to AlbumInfo / TrackInfo, which store them as flexattrs on the item.
_popularity() helper normalizes float/int/None from the Tidal API.

Reimport support

All Tidal fields added to REIMPORT_FRESH_FIELDS_ITEM so they refresh on reimport.

`beet tidalsync` command

Iterates library items, looks up each track by tidal_track_id, and updates tidal_track_popularity + tidal_updated.
--force/-f — re-fetch even if data already exists.
--write/-w — write updated tags to media files.
Accepts an optional query to filter items (e.g., beet tidalsync artist:Miles).

Documentation & Tests

Attribute reference table and command usage examples in
docs/plugins/tidal.rst.
Flexattr assertions in existing tests, new TestPopularity and
TestTidalsync test classes.
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.)

- Add item_types ClassVar with tidal_track_id, tidal_album_id, tidal_artist_id, tidal_track_popularity, tidal_alb_popularity, tidal_updated fields - Populate flexattrs during album/track import via AlbumInfo/TrackInfo kwargs - Add beet tidalsync command to refresh popularity data post-import - Add tidal fields to REIMPORT_FRESH_FIELDS_ITEM for reimport support - Add tests for flexattr population and tidalsync behavior - Update tidal plugin docs with attribute reference and tidalsync usage

codecov · 2026-06-14T20:21:18Z

Codecov Report

❌ Patch coverage is 57.37705% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.50%. Comparing base (60047df) to head (ab2a9ce).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
beetsplug/tidal/__init__.py	57.37%	24 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6744      +/-   ##
==========================================
- Coverage   74.52%   74.50%   -0.03%     
==========================================
  Files         162      162              
  Lines       20818    20865      +47     
  Branches     3295     3305      +10     
==========================================
+ Hits        15515    15545      +30     
- Misses       4547     4563      +16     
- Partials      756      757       +1

Files with missing lines	Coverage Δ
beets/importer/tasks.py	`90.95% <ø> (ø)`
beetsplug/tidal/api.py	`32.53% <ø> (ø)`
beetsplug/tidal/__init__.py	`81.03% <57.37%> (-4.38%)`	⬇️

🚀 New features to boost your workflow:

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

- Use self.add_item() instead of self.lib.add_item() in tests - Fix mypy: add isinstance(val, int) check in _popularity() - Apply ruff formatting

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

            duration=self._duration_to_seconds(track["attributes"]["duration"]),
            label=self._parse_label(track["attributes"]),
+            # Flexattrs
+            tidal_track_id=int(track["id"]),


It looks like we're now storing the same track ID twice in the database: track_id and tidal_track_id.
Summoning @snejus ;) What's our preferred approach here? Should we consolidate these?

**same for artist_id

I am not sure we can consolidate. All the other plugins (bandcamp, spotify, etc. store bandcamp_album_id, spotify_album_id as flexattrs). Until we can make musicbrainz completely optional, I feel we keep them for consistency with the plugin ecosystem pattern (other metadata plugins store their own *_id flexattrs), but we should get @snejus's input.

Also makes queries like tidal_track_id unambiguous without needing to know which standard field maps to which source.

I see two separate topics here:

1. <source>_album_id set by musicbrainz

musicbrainz sets <source>_album_id flex attr - this is reliable information, and it's a good idea to record those. However, we aren't making any use of them currently.

A potential use case could be something like:

Extend autotagging candidates with a result for each of the URLs (using the corresponding plugin, if enabled).

2. Everything else

I only see problems with setting source-specific <source>_{artist,label,track,album}_id etc. fields:

Lack of consistency:

$ grep -ahoR 'discogs[a-z_]*id=' beets* discogs_albumid= discogs_labelid= discogs_artistid= $ grep -ahoR 'deezer[a-z_]*id=' beets* deezer_album_id= deezer_track_id= $ grep -ahoR 'spotify[a-z_]*id=' beets* spotify_album_id= spotify_artist_id= spotify_track_id= spotify_artist_id=

They can stay around even after data_source changes. That makes the fields look authoritative when they may just be stale leftovers from a previous tag source.

Our current source of truth is already confusing: mb_albumid, mb_trackid, and mb_artistid are the fields that drive a lot of beets behavior, but in practice they can contain source-specific IDs, not only MusicBrainz IDs. Adding more provider-specific ID fields without clarifying that model risks making this ambiguity worse.

They become part of the user-visible data model, but without a clear contract around naming, ownership, or semantics.

They are easy to write and hard to make useful. If no code reads them, we are mostly creating permanent metadata surface area that has to be documented, migrated, tested, and kept consistent across plugins.

So I think recording a source ID is fine when it has a concrete consumer or when the plugin is preserving the exact source used for a match. But I would avoid adding more provider-specific ID fields as a general pattern until we have a shared abstraction and an actual feature that uses them.

musicbrainz sets _album_id flex attr - this is reliable information, and it's a good idea to record those. However, we aren't making any use of them currently.

We use the same pattern here and it looks like we actually make use of it here: We can get the popularity values (from tidal) via these ids. Even for albums/tracks that are initially tagged via musicbrainz if they include the tidal_album_id.

For me this sounds like we should keep the flex fields for now until we have designed a better solution.

semohr · 2026-06-15T14:57:13Z

Sorry about the iterative comments. Im coming back to this whenever I have time or thought about something ;)

I just noticed that albums on tidal also have popularity values. I would vote we make popularity work for both tracks and albums (currently it only works for tracks, right?). Maybe a general tidal_popularity flex attribute could work?

I'm also able to make some changes if you feel like it gets too much give me a headsup 😨

…d album popularity to sync

arsaboo · 2026-06-15T15:39:31Z

Sorry about the iterative comments. Im coming back to this whenever I have time or thought about something ;)

I just noticed that albums on tidal also have popularity values. I would vote we make popularity work for both tracks and albums (currently it only works for tracks, right?). Maybe a general tidal_popularity flex attribute could work?

I'm also able to make some changes if you feel like it gets too much give me a headsup 😨

We have tidal_album_popularity to be explicit and avoid any confusion. Updated the parsing based on your comments.

Please don't worry about it. Happy to work with you on this and get this merged. Thanks for all your guidance, and by all means, feel free to improve upon it.

semohr · 2026-06-15T15:54:32Z

We have tidal_album_popularity to be explicit and avoid any confusion. Updated the parsing based on your comments.

Im not entirely sure how the best UX should look like here tbh. Both variants (with and without prefix) come with tradeoffs 🤔

arsaboo · 2026-06-15T16:10:03Z

We have tidal_album_popularity to be explicit and avoid any confusion. Updated the parsing based on your comments.

Im not entirely sure how the best UX should look like here tbh. Both variants (with and without prefix) come with tradeoffs 🤔

We are not currently exposing popularity information in UI. This is mostly for the DB so that we can use it for other smart things (playlists)

semohr · 2026-06-15T16:17:09Z

We are not currently exposing popularity information in UI. This is mostly for the DB so that we can use it for other smart things (playlists)

I mean the query syntax with UX. The question is whether users should have separate fields per entity, such as:

beet ls tidal_album_popularity:5..20

or a single generic field whose meaning depends on the search scope, for example:

beet ls tidal_popularity:5..50 -a

The latter is shorter and more flexible, but the former is more explicit and consistent across entity types.

arsaboo · 2026-06-15T16:22:04Z

We are not currently exposing popularity information in UI. This is mostly for the DB so that we can use it for other smart things (playlists)

I mean the query syntax with UX. The question is whether users should have separate fields per entity, such as:
beet ls tidal_album_popularity:5..20
or a single generic field whose meaning depends on the search scope, for example:
beet ls tidal_popularity:5..50 -a
The latter is shorter and more flexible, but the former is more explicit and consistent across entity types.

I would (strongly) prefer the former, just to be explicit.

Replace tidalsync() with sync_item_popularity() / sync_album_popularity() backed by a shared _sync_popularity() helper. Split the `tidal` command into `tidal` (auth-only) and `tidalsync` (popularity sync with --item, --album, --force, --write flags). While I liked the tidal [auth|sync] it is currently not well supported in beets and e.g. help pages are lacking. Accept int IDs throughout the search pipeline to avoid unnecessary str conversions.

semohr · 2026-06-15T19:59:46Z

@arsaboo Just enhanced the sync logic a bit. Make sure to pull ;) Please have a look! Am mostly happy with the changes but ofcourse if you see something or have a better idea, lets discuss.

arsaboo · 2026-06-15T21:31:52Z

@semohr Excellent. Updated the other parts of the code. Everything is green.

semohr · 2026-06-15T21:38:38Z

Neat I will have another iteration at it tomorrow. Mainly tests and docs as I have not checked these in detail yet but than we should be good to go 👍

semohr · 2026-06-15T21:56:17Z

            write=write,
            force=force,
-            id_field="mb_trackid",
+            id_field="tidal_track_id",


I used mb_trackid intentionally. If we want to keep it as tidal_track_id, we'll need a way to migrate the existing mb_trackid values into the tidal_track_id flex field for users who were using the plugin before flex fields were introduced.

Is there a command that copies mb_trackid values into the tidal_track_id flex field? If so, we can mention it in the changelog, and I'm happy with that approach. 🙂

mb_trackid is a MusicBrainz UUID, while tidal_track_id is an integer (type mismatch). The Tidal API cannot be called with a MusicBrainz ID. So using mb_trackid as the id_field would have other unintended consequences. I don't think that is the right path. Users can re-import or create a custom script.

One option is to try tidal_track_id first and, if missing, fall back to mb_trackid (I don't think this is a good idea, but I will defer to your judgment).

That's not how it currently works, unfortunately. The mb_trackid field stores the ID corresponding to the data_source, this is what I was referring to as duplication in my other comment. For example, if data_source == "tidal", then mb_trackid will always contain the TIDAL track ID.

What I had in mind instead was a simple beets command that migrates all mb_*id values for models where data_source == "tidal" into the new flex fields. Otherwise, users who have previously used the TIDAL plugin won't be able to use sync after these changes unless they manually fix their libraries (me included :/)

arsaboo added 2 commits June 14, 2026 13:44

fix tests

71d0989

arsaboo requested review from a team and semohr as code owners June 14, 2026 20:13

semohr self-assigned this Jun 14, 2026

Fix tests and mypy error

bed1f02

- Use self.add_item() instead of self.lib.add_item() in tests - Fix mypy: add isinstance(val, int) check in _popularity() - Apply ruff formatting

semohr requested changes Jun 15, 2026

View reviewed changes

semohr added the tidal label Jun 15, 2026

address reviewer comments

2f434b2

semohr reviewed Jun 15, 2026

View reviewed changes

Comment thread beetsplug/tidal/__init__.py Outdated

address reviewer comments: type _parse_popularity with attributes, ad…

a6bf76b

…d album popularity to sync

semohr reviewed Jun 15, 2026

View reviewed changes

Comment thread beetsplug/tidal/__init__.py Outdated

arsaboo added 3 commits June 15, 2026 13:00

address reviewer comments: simplify _parse_popularity, fix flake8 E501

4a0b2be

apply ruff formatting

4cd996c

fix mypy: use explicit if-guard for album_result

b85e5ec

semohr force-pushed the tidal branch from cfba00b to 9dfedfe Compare June 15, 2026 19:55

semohr force-pushed the tidal branch from 9dfedfe to 7fdcffe Compare June 15, 2026 19:59

arsaboo added 2 commits June 15, 2026 17:08

Fix id_field, update tests, fix flake8

5904dc2

Apply ruff formatting

ab2a9ce

semohr reviewed Jun 15, 2026

View reviewed changes

Conversation

arsaboo commented Jun 14, 2026

Flexible Attributes (item_types)

Import population

Reimport support

beet tidalsync command

Documentation & Tests

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

semohr Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snejus Jun 16, 2026

Choose a reason for hiding this comment

1. <source>_album_id set by musicbrainz

2. Everything else

Uh oh!

semohr Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

semohr Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

semohr commented Jun 15, 2026

Uh oh!

arsaboo commented Jun 15, 2026

Uh oh!

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!

arsaboo 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!

arsaboo 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!

arsaboo commented Jun 15, 2026

Uh oh!

semohr commented Jun 15, 2026

Uh oh!

semohr Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Flexible Attributes (`item_types`)

`beet tidalsync` command

codecov Bot commented Jun 14, 2026 •

edited

Loading

arsaboo Jun 15, 2026 •

edited

Loading

1. `<source>_album_id` set by `musicbrainz`

semohr commented Jun 15, 2026 •

edited

Loading

semohr commented Jun 15, 2026 •

edited

Loading

semohr commented Jun 15, 2026 •

edited

Loading

arsaboo Jun 15, 2026 •

edited

Loading

semohr Jun 16, 2026 •

edited

Loading