/
/
/
1# Tidal official API models
2
3The Tidal provider is migrating its read/write operations (catalog, search,
4favorites, playlists) from the unofficial `api.tidal.com/v1` API to the official
5`openapi.tidal.com/v2` API.
6
7Some functionality stays on the unofficial API because the official API does not
8offer a usable equivalent at the third-party access tier:
9
10- **Playback** (the official API only serves 30s previews) and **lyrics**.
11- **Recommendations** (the whole feed). The editorial content
12 (curated playlists, charts, new-music modules) is gated to a higher access
13 tier (`dynamicPages`/`dynamicModules` are not reachable). The personalized
14 mixes are only reachable via the `userRecommendations` endpoint, which is
15 **deprecated** with a ~6-month removal window, so building on it would just
16 buy a forced rewrite back to `pages/*`. The existing `pages/*` scraper
17 therefore stays as the single source for recommendations.
18
19This directory holds the tooling for the typed models generated from the
20official API's OpenAPI spec.
21
22## Files
23
24- `tidal-api-oas.json`: vendored copy of the official spec (source of truth for
25 generation and for spotting upstream changes). Not shipped in the package.
26- `generate_models.py`: regenerates the TypedDict models from the vendored spec.
27
28The generated output lives at
29`music_assistant/providers/tidal/_openapi_models.py` and **must not be edited by
30hand**. Only the `*_Attributes` payloads are generated: the JSON:API envelope
31(`data` / `included` / `links`) is handled generically in the provider's api
32client, so it is not modelled here.
33
34## Regenerating the models
35
36```sh
37python scripts/tidal_openapi/generate_models.py
38```
39
40This runs `datamodel-code-generator` via `uvx` (no project dependency added,
41version pinned in the script for reproducible output) and formats the result
42with the repo-pinned `ruff`. To cover a new area in a later slice, add its
43`*_Attributes` schema name to `SEED_SCHEMAS` in `generate_models.py` and rerun.
44When bumping the generator pin, regenerate and commit the (otherwise unchanged)
45output in the same change.
46
47## Refreshing the vendored spec
48
49The official spec evolves (new fields, deprecations with a stated 6-month
50window). To pick up changes:
51
52```sh
53curl -sSL https://tidal-music.github.io/tidal-api-reference/tidal-api-oas.json \
54 -o scripts/tidal_openapi/tidal-api-oas.json
55git diff scripts/tidal_openapi/tidal-api-oas.json # review what changed upstream
56python scripts/tidal_openapi/generate_models.py # regenerate models
57```
58
59The `git diff` on the vendored spec is the low-effort way to stay ahead of
60deprecations: it surfaces exactly which fields/endpoints changed so the handful
61we use can be adjusted deliberately.
62