Metadata-Version: 2.4
Name: beets-tidalv1
Version: 0.1.1
Summary: beets plugin sources for TIDAL v1 lyrics and album art
Author: Trey Turner
License-Expression: MIT
Project-URL: Homepage, https://github.com/treyturner/beets-plugins
Project-URL: Source, https://github.com/treyturner/beets-plugins/tree/main/plugins/tidalv1
Keywords: beets,tidal,lyrics,album-art
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Pytest
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beets>=2.7
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: requests>=2.31
Requires-Dist: urllib3>=2
Dynamic: license-file

# beets-tidalv1

`tidalv1` adds TIDAL v1 sources to the built-in beets `lyrics` and `fetchart` plugins.

The lyrics endpoint used is the legacy v1 endpoint:

```text
GET https://api.tidal.com/v1/tracks/{track_id}/lyrics
```

TIDAL v2 does not currently expose the same lyrics payload.

## Install

`beets-tidalv1` requires Beets 2.7 or newer and Python 3.10–3.14.

```sh
python -m pip install "beets-tidalv1 @ git+https://github.com/treyturner/beets-plugins.git#subdirectory=plugins/tidalv1"
```

## Configure beets

Enable this plugin before `lyrics` and `fetchart` so it registers before beets builds the source lists:

```yaml
plugins:
  - tidalv1
  - lyrics
  - fetchart

lyrics:
  sources:
    - tidalv1
    - lrclib

fetchart:
  sources:
    - filesystem
    - tidalv1
    - coverart

tidalv1:
  v1_client_id: YOUR_TIDAL_V1_APP_CLIENT_ID
  v1_client_secret: YOUR_TIDAL_V1_APP_CLIENT_SECRET
  country_code: US
  prefer_synced: yes
  art_size: 1280
  match_threshold: 0.78
```

A **legacy v1 client ID and secret** are required. If you have a credential pair in the same format used by `tiddl`, you can provide a Base64-encoded `<v1_client_id>;<v1_client_secret>` value instead:

```yaml
tidalv1:
  v1_client_id_secret_b64: BASE64_ENCODED_PAIR
```

If left empty, a best-effort attempt will be made to find it for you.

Run `beet tidalv1 --auth` once to authorize a TIDAL account, mirroring the official `tidal` plugin's `beet tidal --auth` interface. The command opens the authorization URL in your browser and stores a refreshable token cache named `tidalv1_token.json` in beets' application config directory.

## Usage

Fetch lyrics through the normal beets command:

```sh
beet lyrics artist:"Daft Punk"
```

Fetch album art through the normal fetchart command:

```sh
beet fetchart -f album:"Discovery"
```

During imports, the built-in `lyrics` and `fetchart` plugins handle automatic updates when their own `auto` settings are enabled.

All TIDAL requests share a process-wide HTTP session limited to 4 requests/sec. HTTP 429 responses are retried up to six times with exponential backoff, and `Retry-After` is honored if provided. If retries remain exhausted, lyrics and artwork sources log one warning and allow the next configured source to run.

## Development

Run tests:

```sh
uv sync
uv run pytest
uv run mypy
uv run pyright
```

Run a single module:

```sh
uv run pytest tests/test_client.py
```
