Tidal Plugin
============

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

.. _tidal: https://tidal.com

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
:ref:`using-plugins`). Then, install ``beets`` with ``tidal`` extra

.. code-block:: bash

    pip install "beets[tidal]"

Authentication
--------------

To authenticate with Tidal, run:

.. code-block:: bash

    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 :ref:`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:

.. code-block:: bash

    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:

.. code-block:: bash

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

Configuration
-------------

This plugin can be configured like other metadata source plugins as described in
:ref:`metadata-source-plugin-configuration`.

Default
~~~~~~~

.. code-block:: yaml

    tidal:
        client_id: mcjmpl1bPATJXcBT
        tokenfile: tidal_token.json
        data_source_mismatch_penalty: 0.5
        search_limit: 5

.. conf:: 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.

.. conf:: tokenfile
    :default: tidal_token.json

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

Cover Art
---------

When the :doc:`fetchart` 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.

.. include:: ./shared_metadata_source_config.rst

Flexible Attributes
-------------------

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

.. list-table::
    :header-rows: 1

    - - 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"
