beets-tidalv1 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Trey Turner
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,124 @@
1
+ Metadata-Version: 2.4
2
+ Name: beets-tidalv1
3
+ Version: 0.1.0
4
+ Summary: beets plugin sources for TIDAL v1 lyrics and album art
5
+ Author: Trey Turner
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/treyturner/beets-plugins
8
+ Project-URL: Source, https://github.com/treyturner/beets-plugins/tree/main/plugins/tidalv1
9
+ Keywords: beets,tidal,lyrics,album-art
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Framework :: Pytest
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Multimedia :: Sound/Audio
21
+ Requires-Python: <3.15,>=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: beets>=2.7
25
+ Requires-Dist: beautifulsoup4>=4.12
26
+ Requires-Dist: requests>=2.31
27
+ Dynamic: license-file
28
+
29
+ # beets-tidalv1
30
+
31
+ `tidalv1` adds TIDAL v1 sources to the built-in beets `lyrics` and `fetchart` plugins.
32
+
33
+ The lyrics endpoint used is the legacy v1 endpoint:
34
+
35
+ ```text
36
+ GET https://api.tidal.com/v1/tracks/{track_id}/lyrics
37
+ ```
38
+
39
+ TIDAL v2 does not currently expose the same lyrics payload.
40
+
41
+ ## Install
42
+
43
+ `beets-tidalv1` requires Beets 2.7 or newer and Python 3.10–3.14.
44
+
45
+ ```sh
46
+ python -m pip install "beets-tidalv1 @ git+https://github.com/treyturner/beets-plugins.git#subdirectory=plugins/tidalv1"
47
+ ```
48
+
49
+ ## Configure beets
50
+
51
+ Enable this plugin before `lyrics` and `fetchart` so it registers before beets builds the source lists:
52
+
53
+ ```yaml
54
+ plugins:
55
+ - tidalv1
56
+ - lyrics
57
+ - fetchart
58
+
59
+ lyrics:
60
+ sources:
61
+ - tidalv1
62
+ - lrclib
63
+
64
+ fetchart:
65
+ sources:
66
+ - filesystem
67
+ - tidalv1
68
+ - coverart
69
+
70
+ tidalv1:
71
+ v1_client_id: YOUR_TIDAL_V1_APP_CLIENT_ID
72
+ v1_client_secret: YOUR_TIDAL_V1_APP_CLIENT_SECRET
73
+ country_code: US
74
+ prefer_synced: yes
75
+ art_size: 1280
76
+ match_threshold: 0.78
77
+ ```
78
+
79
+ 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:
80
+
81
+ ```yaml
82
+ tidalv1:
83
+ v1_client_id_secret_b64: BASE64_ENCODED_PAIR
84
+ ```
85
+
86
+ If left empty, a best-effort attempt will be made to find it for you.
87
+
88
+ Run `beet tidalv1 --auth` once to authorize a TIDAL account, mirroring the official
89
+ `tidal` plugin's `beet tidal --auth` interface. The command opens the authorization
90
+ URL in your browser and stores a refreshable token cache named `tidalv1_token.json`
91
+ in beets' application config directory.
92
+
93
+ ## Usage
94
+
95
+ Fetch lyrics through the normal beets command:
96
+
97
+ ```sh
98
+ beet lyrics artist:"Daft Punk"
99
+ ```
100
+
101
+ Fetch album art through the normal fetchart command:
102
+
103
+ ```sh
104
+ beet fetchart -f album:"Discovery"
105
+ ```
106
+
107
+ During imports, the built-in `lyrics` and `fetchart` plugins handle automatic updates when their own `auto` settings are enabled.
108
+
109
+ ## Development
110
+
111
+ Run tests:
112
+
113
+ ```sh
114
+ uv sync
115
+ uv run pytest
116
+ uv run mypy
117
+ uv run pyright
118
+ ```
119
+
120
+ Run a single module:
121
+
122
+ ```sh
123
+ uv run pytest tests/test_client.py
124
+ ```
@@ -0,0 +1,96 @@
1
+ # beets-tidalv1
2
+
3
+ `tidalv1` adds TIDAL v1 sources to the built-in beets `lyrics` and `fetchart` plugins.
4
+
5
+ The lyrics endpoint used is the legacy v1 endpoint:
6
+
7
+ ```text
8
+ GET https://api.tidal.com/v1/tracks/{track_id}/lyrics
9
+ ```
10
+
11
+ TIDAL v2 does not currently expose the same lyrics payload.
12
+
13
+ ## Install
14
+
15
+ `beets-tidalv1` requires Beets 2.7 or newer and Python 3.10–3.14.
16
+
17
+ ```sh
18
+ python -m pip install "beets-tidalv1 @ git+https://github.com/treyturner/beets-plugins.git#subdirectory=plugins/tidalv1"
19
+ ```
20
+
21
+ ## Configure beets
22
+
23
+ Enable this plugin before `lyrics` and `fetchart` so it registers before beets builds the source lists:
24
+
25
+ ```yaml
26
+ plugins:
27
+ - tidalv1
28
+ - lyrics
29
+ - fetchart
30
+
31
+ lyrics:
32
+ sources:
33
+ - tidalv1
34
+ - lrclib
35
+
36
+ fetchart:
37
+ sources:
38
+ - filesystem
39
+ - tidalv1
40
+ - coverart
41
+
42
+ tidalv1:
43
+ v1_client_id: YOUR_TIDAL_V1_APP_CLIENT_ID
44
+ v1_client_secret: YOUR_TIDAL_V1_APP_CLIENT_SECRET
45
+ country_code: US
46
+ prefer_synced: yes
47
+ art_size: 1280
48
+ match_threshold: 0.78
49
+ ```
50
+
51
+ 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:
52
+
53
+ ```yaml
54
+ tidalv1:
55
+ v1_client_id_secret_b64: BASE64_ENCODED_PAIR
56
+ ```
57
+
58
+ If left empty, a best-effort attempt will be made to find it for you.
59
+
60
+ Run `beet tidalv1 --auth` once to authorize a TIDAL account, mirroring the official
61
+ `tidal` plugin's `beet tidal --auth` interface. The command opens the authorization
62
+ URL in your browser and stores a refreshable token cache named `tidalv1_token.json`
63
+ in beets' application config directory.
64
+
65
+ ## Usage
66
+
67
+ Fetch lyrics through the normal beets command:
68
+
69
+ ```sh
70
+ beet lyrics artist:"Daft Punk"
71
+ ```
72
+
73
+ Fetch album art through the normal fetchart command:
74
+
75
+ ```sh
76
+ beet fetchart -f album:"Discovery"
77
+ ```
78
+
79
+ During imports, the built-in `lyrics` and `fetchart` plugins handle automatic updates when their own `auto` settings are enabled.
80
+
81
+ ## Development
82
+
83
+ Run tests:
84
+
85
+ ```sh
86
+ uv sync
87
+ uv run pytest
88
+ uv run mypy
89
+ uv run pyright
90
+ ```
91
+
92
+ Run a single module:
93
+
94
+ ```sh
95
+ uv run pytest tests/test_client.py
96
+ ```
@@ -0,0 +1,100 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "beets-tidalv1"
7
+ version = "0.1.0"
8
+ description = "beets plugin sources for TIDAL v1 lyrics and album art"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10,<3.15"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [
14
+ { name = "Trey Turner" },
15
+ ]
16
+ keywords = ["beets", "tidal", "lyrics", "album-art"]
17
+ classifiers = [
18
+ "Development Status :: 3 - Alpha",
19
+ "Environment :: Console",
20
+ "Framework :: Pytest",
21
+ "Intended Audience :: End Users/Desktop",
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Programming Language :: Python :: 3.14",
28
+ "Topic :: Multimedia :: Sound/Audio",
29
+ ]
30
+ dependencies = [
31
+ "beets>=2.7",
32
+ "beautifulsoup4>=4.12",
33
+ "requests>=2.31",
34
+ ]
35
+
36
+ [dependency-groups]
37
+ dev = [
38
+ "mypy>=1.18",
39
+ "pre-commit>=3.8",
40
+ "pyright>=1.1.410",
41
+ "pytest>=8",
42
+ "pytest-cov>=5",
43
+ "ruff>=0.6.9",
44
+ "types-requests>=2.32",
45
+ ]
46
+
47
+ [project.urls]
48
+ Homepage = "https://github.com/treyturner/beets-plugins"
49
+ Source = "https://github.com/treyturner/beets-plugins/tree/main/plugins/tidalv1"
50
+
51
+ [tool.setuptools.packages.find]
52
+ where = ["src"]
53
+ include = ["beetsplug*"]
54
+ namespaces = true
55
+
56
+ [tool.pytest.ini_options]
57
+ addopts = "--strict-markers --strict-config --cov=beetsplug.tidalv1 --cov-report=term-missing"
58
+ testpaths = ["tests"]
59
+
60
+ [tool.coverage.run]
61
+ branch = true
62
+ source = ["beetsplug.tidalv1"]
63
+
64
+ [tool.coverage.report]
65
+ show_missing = true
66
+ skip_covered = true
67
+
68
+ [tool.mypy]
69
+ strict = true
70
+ files = ["src/beetsplug/tidalv1"]
71
+ warn_unused_ignores = true
72
+
73
+ [[tool.mypy.overrides]]
74
+ module = [
75
+ "beets.*",
76
+ "beetsplug.*",
77
+ ]
78
+ ignore_missing_imports = true
79
+
80
+ [tool.pyright]
81
+ include = ["src"]
82
+ extraPaths = ["src"]
83
+ typeCheckingMode = "strict"
84
+ venvPath = "."
85
+ venv = ".venv"
86
+ reportMissingTypeStubs = "none"
87
+
88
+ [tool.ruff]
89
+ target-version = "py310"
90
+ line-length = 100
91
+ src = ["src"]
92
+
93
+ [tool.ruff.lint]
94
+ select = ["E", "F", "W", "B", "I", "UP"]
95
+ ignore = []
96
+
97
+ [tool.ruff.format]
98
+ quote-style = "double"
99
+ indent-style = "space"
100
+ line-ending = "lf"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,124 @@
1
+ Metadata-Version: 2.4
2
+ Name: beets-tidalv1
3
+ Version: 0.1.0
4
+ Summary: beets plugin sources for TIDAL v1 lyrics and album art
5
+ Author: Trey Turner
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/treyturner/beets-plugins
8
+ Project-URL: Source, https://github.com/treyturner/beets-plugins/tree/main/plugins/tidalv1
9
+ Keywords: beets,tidal,lyrics,album-art
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Framework :: Pytest
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Multimedia :: Sound/Audio
21
+ Requires-Python: <3.15,>=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: beets>=2.7
25
+ Requires-Dist: beautifulsoup4>=4.12
26
+ Requires-Dist: requests>=2.31
27
+ Dynamic: license-file
28
+
29
+ # beets-tidalv1
30
+
31
+ `tidalv1` adds TIDAL v1 sources to the built-in beets `lyrics` and `fetchart` plugins.
32
+
33
+ The lyrics endpoint used is the legacy v1 endpoint:
34
+
35
+ ```text
36
+ GET https://api.tidal.com/v1/tracks/{track_id}/lyrics
37
+ ```
38
+
39
+ TIDAL v2 does not currently expose the same lyrics payload.
40
+
41
+ ## Install
42
+
43
+ `beets-tidalv1` requires Beets 2.7 or newer and Python 3.10–3.14.
44
+
45
+ ```sh
46
+ python -m pip install "beets-tidalv1 @ git+https://github.com/treyturner/beets-plugins.git#subdirectory=plugins/tidalv1"
47
+ ```
48
+
49
+ ## Configure beets
50
+
51
+ Enable this plugin before `lyrics` and `fetchart` so it registers before beets builds the source lists:
52
+
53
+ ```yaml
54
+ plugins:
55
+ - tidalv1
56
+ - lyrics
57
+ - fetchart
58
+
59
+ lyrics:
60
+ sources:
61
+ - tidalv1
62
+ - lrclib
63
+
64
+ fetchart:
65
+ sources:
66
+ - filesystem
67
+ - tidalv1
68
+ - coverart
69
+
70
+ tidalv1:
71
+ v1_client_id: YOUR_TIDAL_V1_APP_CLIENT_ID
72
+ v1_client_secret: YOUR_TIDAL_V1_APP_CLIENT_SECRET
73
+ country_code: US
74
+ prefer_synced: yes
75
+ art_size: 1280
76
+ match_threshold: 0.78
77
+ ```
78
+
79
+ 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:
80
+
81
+ ```yaml
82
+ tidalv1:
83
+ v1_client_id_secret_b64: BASE64_ENCODED_PAIR
84
+ ```
85
+
86
+ If left empty, a best-effort attempt will be made to find it for you.
87
+
88
+ Run `beet tidalv1 --auth` once to authorize a TIDAL account, mirroring the official
89
+ `tidal` plugin's `beet tidal --auth` interface. The command opens the authorization
90
+ URL in your browser and stores a refreshable token cache named `tidalv1_token.json`
91
+ in beets' application config directory.
92
+
93
+ ## Usage
94
+
95
+ Fetch lyrics through the normal beets command:
96
+
97
+ ```sh
98
+ beet lyrics artist:"Daft Punk"
99
+ ```
100
+
101
+ Fetch album art through the normal fetchart command:
102
+
103
+ ```sh
104
+ beet fetchart -f album:"Discovery"
105
+ ```
106
+
107
+ During imports, the built-in `lyrics` and `fetchart` plugins handle automatic updates when their own `auto` settings are enabled.
108
+
109
+ ## Development
110
+
111
+ Run tests:
112
+
113
+ ```sh
114
+ uv sync
115
+ uv run pytest
116
+ uv run mypy
117
+ uv run pyright
118
+ ```
119
+
120
+ Run a single module:
121
+
122
+ ```sh
123
+ uv run pytest tests/test_client.py
124
+ ```
@@ -0,0 +1,16 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/beets_tidalv1.egg-info/PKG-INFO
5
+ src/beets_tidalv1.egg-info/SOURCES.txt
6
+ src/beets_tidalv1.egg-info/dependency_links.txt
7
+ src/beets_tidalv1.egg-info/requires.txt
8
+ src/beets_tidalv1.egg-info/top_level.txt
9
+ src/beetsplug/tidalv1/__init__.py
10
+ src/beetsplug/tidalv1/auth.py
11
+ src/beetsplug/tidalv1/client.py
12
+ src/beetsplug/tidalv1/http_types.py
13
+ src/beetsplug/tidalv1/sources.py
14
+ tests/test_auth.py
15
+ tests/test_client.py
16
+ tests/test_sources.py
@@ -0,0 +1,3 @@
1
+ beets>=2.7
2
+ beautifulsoup4>=4.12
3
+ requests>=2.31
@@ -0,0 +1,89 @@
1
+ from __future__ import annotations
2
+
3
+ import time
4
+ import webbrowser
5
+ from contextlib import suppress
6
+ from importlib.metadata import PackageNotFoundError, version
7
+ from typing import Any, cast
8
+
9
+ from beets import ui
10
+ from beets.plugins import BeetsPlugin
11
+
12
+ from .auth import (
13
+ DEFAULT_AUTH_BASE,
14
+ DEFAULT_AUTH_CACHE_FILENAME,
15
+ AuthManager,
16
+ )
17
+ from .client import DEFAULT_API_BASE
18
+ from .sources import register_sources
19
+
20
+ try:
21
+ __version__ = version("beets-tidalv1")
22
+ except PackageNotFoundError: # pragma: no cover - source tree without installation
23
+ __version__ = "0.1.0"
24
+
25
+ DEFAULT_CONFIG: dict[str, str | int | float | bool | None] = {
26
+ "api_base": DEFAULT_API_BASE,
27
+ "auth_base": DEFAULT_AUTH_BASE,
28
+ "v1_client_id": None,
29
+ "v1_client_secret": None,
30
+ "v1_client_id_secret_b64": None,
31
+ "access_token": None,
32
+ "refresh_token": None,
33
+ "token_expires_at": None,
34
+ "country_code": "US",
35
+ "auth_cache": DEFAULT_AUTH_CACHE_FILENAME,
36
+ "request_timeout": 15.0,
37
+ "search_limit": 10,
38
+ "match_threshold": 0.78,
39
+ "prefer_synced": True,
40
+ "art_size": 1280,
41
+ }
42
+
43
+ register_sources()
44
+
45
+
46
+ class TidalV1Plugin(BeetsPlugin):
47
+ def __init__(self) -> None:
48
+ super().__init__()
49
+ self.config.add(DEFAULT_CONFIG)
50
+ for key in (
51
+ "v1_client_id",
52
+ "v1_client_secret",
53
+ "v1_client_id_secret_b64",
54
+ "access_token",
55
+ "refresh_token",
56
+ ):
57
+ self.config[key].redact = True
58
+ register_sources()
59
+
60
+ def commands(self) -> list[Any]:
61
+ cmd = cast(Any, ui.Subcommand)("tidalv1", help="TIDAL v1 plugin commands")
62
+ cmd.parser.add_option(
63
+ "-a",
64
+ "--auth",
65
+ action="store_true",
66
+ default=False,
67
+ help="authenticate and log in to TIDAL",
68
+ )
69
+
70
+ def func(lib: Any, opts: Any, args: Any) -> None:
71
+ if not opts.auth:
72
+ cmd.print_help()
73
+ return
74
+
75
+ manager = AuthManager.from_config(self.config)
76
+ device = manager.start_device_authorization()
77
+ url = device.verification_uri_complete or device.verification_uri
78
+ ui.print_("OAuth login started; waiting for a response.")
79
+ ui.print_(f"Open this TIDAL authorization URL: {url}")
80
+ ui.print_(f"If not auto-filled, use code: {device.user_code}")
81
+ with suppress(webbrowser.Error):
82
+ webbrowser.open(url)
83
+
84
+ token = manager.poll_device_authorization(device, sleep=time.sleep)
85
+ manager.save_token(token)
86
+ ui.print_(f"TIDAL authorization saved to {manager.cache_path}")
87
+
88
+ cmd.func = func
89
+ return [cmd]