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:

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.

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:

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:

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:

beet lyrics artist:"Daft Punk"

Fetch album art through the normal fetchart command:

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:

uv sync
uv run pytest
uv run mypy
uv run pyright

Run a single module:

uv run pytest tests/test_client.py

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for treyturner from gravatar.com treyturner

Credits

Author: Trey Turner

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <3.15, >=3.10

Tags

beets tidal lyrics album-art

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beets_tidalv1-0.1.1.tar.gz (21.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

beets_tidalv1-0.1.1-py3-none-any.whl (15.7 kB view details)

Uploaded Python 3

File details

Details for the file beets_tidalv1-0.1.1.tar.gz.

File metadata

  • Download URL: beets_tidalv1-0.1.1.tar.gz
  • Upload date:
  • Size: 21.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for beets_tidalv1-0.1.1.tar.gz
Algorithm Hash digest
SHA256 2317108dfa2213ef2e0bda4410a9b50d595781b6657cc83880eb85d652402209
MD5 7be4ca7fd9937610ff16f4493ae89fe4
BLAKE2b-256 55977432ee140a2cc4e3a054efa765108fb51d38df97e25e7c617d53041be1bb

See more details on using hashes here.

Provenance

The following attestation bundles were made for beets_tidalv1-0.1.1.tar.gz:

Publisher: release.yml on treyturner/beets-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file beets_tidalv1-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: beets_tidalv1-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 15.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for beets_tidalv1-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ac9e4b7966db9e9cf910617ea1ae6c7958e1c8b2c1558df51b994c472e03fb3b
MD5 d3848d1c39fc9845fcbbaca6fac9688f
BLAKE2b-256 c0619dff20c1f7bd1a9ee68e47d1e2b16acb6ef3007676d1ff52369b3fdd8309

See more details on using hashes here.

Provenance

The following attestation bundles were made for beets_tidalv1-0.1.1-py3-none-any.whl:

Publisher: release.yml on treyturner/beets-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page