Skip to main content
`Ctrl`+`K`

# 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.

## Installation

To use the `tidal` plugin, first enable it in your configuration (see Using Plugins). Then, install `beets` with `tidal` extra

    pip install "beets[tidal]"

## 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.

## Cover Art

When the FetchArt Plugin plugin is enabled, beets can retrieve album cover art from Tidal. The Tidal plugin automatically includes the cover art URL when looking up albums. No additional configuration is needed to enable this feature.

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.

## Flexible Attributes

The plugin stores the following flexible attributes on your items during import. You can use them in queries and path formats.

Attribute | Type | Description
--- | --- | ---
`tidal_track_id` | STRING | Tidal track ID
`tidal_album_id` | STRING | Tidal album ID
`tidal_artist_id` | STRING | Tidal artist ID
`tidal_track_popularity` | INTEGER | Track popularity score (0-100)
`tidal_album_popularity` | INTEGER | Album popularity score (0-100)
`tidal_updated` | DATE | Unix timestamp of last popularity sync

For example, to list your most popular tracks:

    beet ls tidal_track_popularity:80..

To find tracks that have not been synced yet:

    beet ls tidal_track_popularity:0

## Synchronise popularity

Use `beet tidalsync` to refresh popularity data for your imported items and albums from Tidal. By default it skips items that already have popularity data.

Options:

- `-f`, `--force` – re-fetch all items, even those already synced.

- `-a`, `--album` – sync albums instead of individual tracks.

- `-w`, `--write` – write updated metadata to media files.

You can also pass a query to narrow the scope:

    beet tidalsync -fw artist:"My Artist"