Tidal Plugin#

The tidal plugin provides metadata matches for the autotagger using the Tidal Web APIs.

Why Use the Tidal Plugin?#

The Tidal plugin allows you to:

  • Fetch metadata for albums and tracks from Tidal's catalog

  • Look up tracks by ISRC code (useful if your music files already contain ISRC tags)

  • Look up albums by barcode ID (useful if your CDs have UPC barcodes)

  • Get matches during import without needing to manually search

This is especially useful if your music already has ISRC or barcode metadata embedded, as it allows for quick and accurate matching to Tidal's catalog.

Requirements#

  • A Tidal account (free or premium)

  • Python environment with network access to Tidal's API

Before using the plugin, you need to authorize your beets installation to access your Tidal account.

Authentication#

To authenticate with Tidal, run:

beet tidal --auth

This will open a browser window where you can log in to your Tidal account. After successful authentication, your token will be saved to the configured token file and you won't need to re-authenticate on subsequent runs.

Basic Usage#

Enable the tidal plugin (see Using Plugins). Once enabled, you will receive Tidal matches when importing new items.

During import, you can also manually enter a Tidal URL at the enter Id prompt:

Enter search, enter Id, aBort, eDit, edit Candidates, plaY? i
Enter release ID: https://tidal.com/album/226495055

You can enter both album and track URLs. For example:

https://tidal.com/track/490839595
https://tidal.com/album/234493117

Configuration#

This plugin can be configured like other metadata source plugins as described in Using Metadata Source Plugins.

Default#

tidal:
    client_id: mcjmpl1bPATJXcBT
    tokenfile: tidal_token.json
    data_source_mismatch_penalty: 0.5
    search_limit: 5
client_id (default: mcjmpl1bPATJXcBT)#

The Tidal API client ID. The default value is the public demo client ID. You can register your own application at Tidal's developer portal for production use.

tokenfile (default: tidal_token.json)#

The path to the file where the Tidal authentication token is stored.

data_source_mismatch_penalty (default: 0.5)#

Penalty applied when the data source of a match candidate differs from the original source of your existing tracks. Any decimal number between 0.0 and 1.0

This setting controls how much to penalize matches from different metadata sources during import. The penalty is applied when beets detects that a match candidate comes from a different data source than what appears to be the original source of your music collection.

Example configurations:

# Prefer MusicBrainz over Discogs when sources don't match
plugins: musicbrainz discogs

musicbrainz:
    data_source_mismatch_penalty: 0.3  # Lower penalty = preferred
discogs:
    data_source_mismatch_penalty: 0.8  # Higher penalty = less preferred

# Do not penalise candidates from Discogs at all
plugins: musicbrainz discogs

musicbrainz:
    data_source_mismatch_penalty: 0.5
discogs:
    data_source_mismatch_penalty: 0.0

# Disable cross-source penalties entirely
plugins: musicbrainz discogs

musicbrainz:
    data_source_mismatch_penalty: 0.0
discogs:
    data_source_mismatch_penalty: 0.0

Tip

The last configuration is equivalent to setting:

match:
    distance_weights:
        data_source: 0.0  # Disable data source matching
source_weight (default: 0.5)#

Deprecated since version 2.5: Use data_source_mismatch_penalty instead.

search_limit (default: 5)#

Maximum number of search results to return.